{docs,examples,ci}: add flake devSehll examples

.github/workflows/ci.yaml

@@ -138,12 +138,16 @@ jobs:
  [[ "$(< out)" == *"warning: this loop never actually loops"* ]]
 
  test-cross-examples:
- name: Test cross compilation examples
  runs-on: ubuntu-latest
  strategy:
  fail-fast: false
  matrix:
  example: [cross-aarch64, cross-wasi, cross-mingw]
+ kind: [shell]
+ include:
+ - example: cross-aarch64
+ kind: flake
+ name: Test cross compilation examples (${{ matrix.kind }})
 
  steps:
  - name: Checkout
@@ -158,15 +162,23 @@ jobs:
  - name: Don't let ~/.cargo/bin mess things up
  run: rm -rf ~/.cargo/bin
 
- - name: Prepare nix-shell
+ - name: Prepare dev env
  run: |
  cd examples/${{ matrix.example }}
- nix-shell --pure --command true
+ if [[ ${{ matrix.kind }} == 'shell' ]]; then
+ nix-shell --pure --command true
+ else
+ nix develop --ignore-environment --override-input rust-overlay ../..
+ fi
 
  - name: Build and run example
  run: |
  cd examples/${{ matrix.example }}
  set -o pipefail
- # No --pure since it requires CA cert access for crates downloading.
- nix-shell --command "make run" | tee out
+ if [[ ${{ matrix.kind }} == 'shell' ]]; then
+ # No --pure since it requires CA cert access for crates downloading.
+ nix-shell --pure --command "make run" | tee out
+ else
+ nix develop --ignore-environment --override-input rust-overlay ../.. --command make run
+ fi
  [[ "$(< out)" == *"Hello, world!"* ]]

.gitignore

@@ -2,3 +2,5 @@ target
 result
 result-*
 *.tmp
+
+examples/cross-aarch64/flake.lock

docs/cross_compilation.md

@@ -1,5 +1,7 @@
 # Cross compilation with `rust-overlay`
 
+## `shell.nix` and `nix shell` development environment
+
 There are examples for cross compilation in [`example` directory](../examples).
 To try examples,
 1. `cd` into `example/cross-aarch64` (or other directory).
@@ -57,4 +59,34 @@ mkShell {
 ```
 
 For more details about these different kinds of dependencies,
-see also [Nix Wiki - Cross Compiling](https://nixos.wiki/wiki/Cross_Compiling#How_to_specify_dependencies).
+see also [Nix Wiki - Cross Compiling][wiki-cross]
+
+## Flakes and `nix develop` development environment
+
+Unfortunately flake output layout does not natively support cross-compilation
+(see [NixOS/nix#5157][flake-cross-issue]). We provide `mkRustBin` to allow
+construction of `rust-bin` on an existing nixpkgs to leverage flake benefits of
+not-importing nixpkgs again, with the cost of re-instantiating `rust-bin` for
+each host-target tuples.
+
+Pass the spliced packages for your cross-compilation target to `mkRustBin` to
+get corresponding compiler toolchains for them.
+
+```nix
+let
+ pkgs = nixpkgs.legacyPackages.x86_64-linux.pkgsCross.aarch64-multiplatform;
+ rust-bin = rust-overlay.lib.mkRustBin { } pkgs.buildPackages;
+in pkgs.mkShell {
+ nativeBuildInputs = [ rust-bin.stable.latest.minimal ];
+}
+```
+
+The full example can be seen in
+[`examples/cross-aarch64/flake.nix`](../examples/cross-aarch64/flake.nix).
+To try it,
+1. `cd` into `example/cross-aarch64`.
+2. `nix develop` to enter the development environment.
+3. `make run` to build and run the program in an emulator.
+
+[wiki-cross]: https://wiki.nixos.org/wiki/Cross_Compiling#How_to_specify_dependencies
+[flake-cross-issue]: https://github.com/NixOS/nix/issues/5157

examples/cross-aarch64/flake.nix

@@ -0,0 +1,29 @@
+# Example flake for `nix develop`.
+{
+ inputs = {
+ nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable";
+ rust-overlay.url = "github:oxalica/rust-overlay";
+ rust-overlay.inputs.nixpkgs.follows = "nixpkgs";
+ };
+
+ outputs = { self, rust-overlay, nixpkgs }: {
+ devShells.x86_64-linux.default = let
+ pkgs = nixpkgs.legacyPackages.x86_64-linux.pkgsCross.aarch64-multiplatform;
+ rust-bin = rust-overlay.lib.mkRustBin { } pkgs.buildPackages;
+ in
+ pkgs.mkShell {
+ nativeBuildInputs = [
+ rust-bin.stable.latest.minimal
+ pkgs.buildPackages.pkg-config
+ ];
+
+ depsBuildBuild = [ pkgs.pkgsBuildBuild.qemu ];
+ buildInputs = [ pkgs.openssl ];
+
+ env = {
+ CARGO_TARGET_AARCH64_UNKNOWN_LINUX_GNU_LINKER = "${pkgs.stdenv.cc.targetPrefix}cc";
+ CARGO_TARGET_AARCH64_UNKNOWN_LINUX_GNU_RUNNER = "qemu-aarch64";
+ };
+ };
+ };
+}

examples/cross-aarch64/shell.nix

@@ -1,3 +1,4 @@
+# Example flake for `nix shell`.
 # See docs/cross_compilation.md for details.
 (import <nixpkgs> {
  crossSystem = "aarch64-linux";