notes.md

Deploying the rust compiler to Blue Gene

Luckily for us, powerpc64-unknown-linux-gnu is a supported target triple, and we can download the toolchain through rustup.

If a firewall prevents the use of rustup on the remote machine, you can download the toolchain on your own your own machine:

$ rustup toolchain add 1.20.0-powerpc64-unknown-linux-gnu
$ cd ~/.rustup/toolchains/1.20.0-powerpc64-unknown-linux-gnu/
$ tree -d -L 2
.
├── bin
├── etc
│   └── bash_completion.d
├── lib
│   └── rustlib
└── share
    ├── doc
    ├── man
    └── zsh

You can just copy this directory straight to Blue Gene, and put bin on PATH and lib on LD_LIBRARY_PATH. That's it!

Try making a test program to verify that it works:

[ CMNDlmpm@q ] ~
$ export PATH=$HOME/rust-dist/bin:$PATH
$ export LD_LIBRARY_PATH=$HOME/rust-dist/lib:$LD_LIBRARY_PATH
$ rustc --version -v
rustc 1.20.0 (f3d6973f4 2017-08-27)
binary: rustc
commit-hash: f3d6973f41a7d1fb83029c9c0ceaf0f5d4fd7208
commit-date: 2017-08-27
host: powerpc64-unknown-linux-gnu
release: 1.20.0
LLVM version: 4.0
$ cargo new --bin howdy-bgq
     Created binary (application) `howdy-bgq` project
$ cd howdy-bgq
$ ls
Cargo.toml  src
$ cargo run
   Compiling howdy-bgq v0.1.0 (file:///gpfs/u/home/CMND/CMNDlmpm/howdy-bgq)
    Finished dev [unoptimized + debuginfo] target(s) in 0.63 secs
     Running `target/debug/howdy-bgq`
Hello, world!

Deploying a crate through the firewall

You could use scp or rsync or whatever, though for easy conveyance of fixes back and forth I recommend having three git repositories:

1. Your local development worktree.
2. A worktree on the remote for building/installation.
3. A bare repository on the remote to assist in data transfer and merges.

An example of setting up such a system can be seen in the secion on "Vendoring dependencies."

This works well because git supports local filepaths as well as ssh urls. The bare repository should be set as upstream for both normal repositories. After that, it will play the role frequently filled by e.g. a repo on github, as a centralized middleman that both repositories can easily push/pull to.

Vendoring dependencies

Let's start with a simple crate that uses Serde. Suppose this is on your local filesystem.

uses-serde/Cargo.toml

[package]
name = "uses-serde"
version = "0.1.0"

[dependencies]
serde = "1.0.14"
serde_derive = "1.0.14"
serde_json = "1.0.3"

uses-serde/src/main.rs

extern crate serde;
#[macro_use] extern crate serde_derive;
#[macro_use] extern crate serde_json;

#[derive(Serialize, Deserialize)]
#[derive(Debug, Copy, Clone, PartialEq, Eq, PartialOrd, Ord, Hash)]
pub enum These<A, B> {
	#[serde(rename = "this")]
	This(A),
	#[serde(rename = "that")]
	That(B),
	#[serde(rename = "these")]
	These(A, B),
}

fn main() {
	let j = json!({"these": [27i64, "ima string"]});
	let v: These<i64, String> = ::serde_json::from_value(j.clone()).unwrap();
	println!("json: {}", j);
	println!("parsed: {:?}", v);
}

There is an awesome cargo subcommand called cargo vendor which will gather all the dependencies you need into a local directory.

[ lampam@arch-t430s ] (master •23) ~/cpp/throwaway
$ cd uses-serde
$ cargo vendor
   Vendoring dtoa v0.4.2 (/home/lampam/.cargo/registry/src/github.com-1ecc6299db9ec823/dtoa-0.4.2) to vendor/dtoa
   Vendoring itoa v0.3.3 (/home/lampam/.cargo/registry/src/github.com-1ecc6299db9ec823/itoa-0.3.3) to vendor/itoa
   Vendoring num-traits v0.1.40 (/home/lampam/.cargo/registry/src/github.com-1ecc6299db9ec823/num-traits-0.1.40) to vendor/num-traits
   Vendoring quote v0.3.15 (/home/lampam/.cargo/registry/src/github.com-1ecc6299db9ec823/quote-0.3.15) to vendor/quote
   Vendoring serde v1.0.14 (/home/lampam/.cargo/registry/src/github.com-1ecc6299db9ec823/serde-1.0.14) to vendor/serde
   Vendoring serde_derive v1.0.14 (/home/lampam/.cargo/registry/src/github.com-1ecc6299db9ec823/serde_derive-1.0.14) to vendor/serde_derive
   Vendoring serde_derive_internals v0.16.0 (/home/lampam/.cargo/registry/src/github.com-1ecc6299db9ec823/serde_derive_internals-0.16.0) to vendor/serde_derive_internals
   Vendoring serde_json v1.0.3 (/home/lampam/.cargo/registry/src/github.com-1ecc6299db9ec823/serde_json-1.0.3) to vendor/serde_json
   Vendoring syn v0.11.11 (/home/lampam/.cargo/registry/src/github.com-1ecc6299db9ec823/syn-0.11.11) to vendor/syn
   Vendoring synom v0.11.3 (/home/lampam/.cargo/registry/src/github.com-1ecc6299db9ec823/synom-0.11.3) to vendor/synom
   Vendoring unicode-xid v0.0.4 (/home/lampam/.cargo/registry/src/github.com-1ecc6299db9ec823/unicode-xid-0.0.4) to vendor/unicode-xid
To use vendored sources, add this to your .cargo/config for this project:

    [source.crates-io]
    replace-with = "vendored-sources"
    
    [source.vendored-sources]
    directory = "/home/lampam/cpp/throwaway/uses-serde/vendor"

Save this text somewhere but don't bother putting it in .cargo/config; we'll get to that on the remote machine.

If you are using git, both vendor and .cargo should be added to .gitignore:

vendor  # vendored packages; large files
.cargo  # per-system configuration

Make the bare repository.

[ lampam@arch-t430s ] (master •23) ~/cpp/throwaway/uses-serde
$ # (naming convention: bare repositories usually end in '.git')
$ ssh cci 'git init --bare uses-serde.git'
Initialized empty Git repository in /gpfs/u/home/CMND/CMNDlmpm/uses-serde.git/
$ # (for the reader's sake, I have named the remote 'cci-remote'
$ #  to distinguish it from 'cci', which is my ssh alias)
$ git remote add cci-remote cci:uses-serde.git
$ git push --all cci-remote
Counting objects: 7, done.
Delta compression using up to 4 threads.
Compressing objects: 100% (5/5), done.
Writing objects: 100% (7/7), 1.71 KiB | 1.71 MiB/s, done.
Total 7 (delta 0), reused 0 (delta 0)
To cci:uses-serde.git
 * [new branch]      master -> master

Make the remote worktree.

$ ssh cci
[ CMNDlmpm@alp01 ] ~
$ git clone uses-serde.git uses-serde
$ cd uses-serde
$ mkdir .cargo
$ cat >.cargo/config <<HERE
[source.crates-io]
replace-with = "vendored-sources"

[source.vendored-sources]
directory = "vendor"
HERE
$ exit

Copy over the vendored crates.

If you use any git dependencies, consider copying over Cargo.lock as well; the file is portable, and cargo will not want to generate a lock file while source replacements for them exist in the config.

[ lampam@arch-t430s ] (master •23) ~/cpp/throwaway/uses-serde
$ rsync -az vendor Cargo.lock cci:uses-serde

You're now ready to build it on BGQ!

[ CMNDlmpm@q ] ~/uses-serde
$ cargo run
   Compiling quote v0.3.15
   Compiling num-traits v0.1.40
   Compiling unicode-xid v0.0.4
   Compiling serde v1.0.14
   Compiling itoa v0.3.3
   Compiling dtoa v0.4.2
   Compiling synom v0.11.3
   Compiling syn v0.11.11
   Compiling serde_derive_internals v0.16.0
   Compiling serde_json v1.0.3
   Compiling serde_derive v1.0.14
   Compiling uses-serde v0.1.0 (file:///gpfs/u/home/CMND/CMNDlmpm/uses-serde)
    Finished dev [unoptimized + debuginfo] target(s) in 37.60 secs
     Running `target/debug/uses-serde`
json: {"these":[27,"ima string"]}
parsed: These(27, "ima string")

In the future, the following process should suffice to push new commits to the remote:

[ lampam@arch-t430s ] (master •23) ~/cpp/throwaway/uses-serde
$ git push --all cci-remote
$ ssh cci 'cd uses-serde && git pull'
$ cargo vendor && rsync -az vendor cci:uses-serde