docs: add some initial more advanced documentationHEADmaster

The primary point of this is to describe installation procedure but we
should also describe basic router usage with NixOS as that ain't
documented elsewhere.

1 files changed, 48 insertions, 0 deletions

diff --git a/docs/qemu-vs-cross.adoc b/docs/qemu-vs-cross.adoc
new file mode 100644
index 0000000..7010ac0
--- /dev/null
+++ b/docs/qemu-vs-cross.adoc
@@ -0,0 +1,48 @@
+= Cross build vs. Qemu build
+
+When building packages or NixOS on any other machine (most likely amd64) you
+have two options how to build. You can either build natively like you would be
+running on the target platform using Qemu. Or you can use cross build. This
+document tires to gives you some comparison so you can decide on your own which
+you want to use. In general use what works for you.
+
+Compilation speed:: The cross build is much faster compared to Qemu. It is
+simple as that.
+
+Build success:: There is a lot of packages that are broken for cross build in
+Nixpkgs and thus sometimes you might have more luck with native builds. At the
+same time there is a lot of packages that won't compile natively on armv7 for
+multiple reasons (the most common is that test cases do not expect 32bit
+system). The rule of thumb is that with aarch64 native build is more stable
+while cross build might be more stable for armv7.
+
+Device rebuilds:: The one huge disadvantage for the cross builds is that they
+produce different result compared to native builds in Nix. The effect is that
+`nixos-rebuild` on the device can't reuse cross builds while it can reuse native
+builds.
+
+
+== Native (Qemu) build Nix setup
+
+To get native build work you need the Nix with ability to run aarch64 and/or
+armv7 binaries. That is in general option `extra-platforms` with value
+`aarch64-linux` for Turris Mox and `armv7l-linux` for Turris Omnia. To actually
+allow access to the emulator you need something like `extra-sandbox-paths` with
+value such as `/usr/bin/qemu-aarch64` (for Turris Mox) or `/usr/bin/qemu-arm`
+(for Turris Omnia). This way you can build aarch64 or armv7l package on other
+platforms. You might also want to add some ARM specific substituters.
+
+The configuration file for Nix should thus contain something like:
+
+----
+extra-platforms = aarch64-linux armv7l-linux
+extra-sandbox-paths = /usr/bin/qemu-aarch64 /usr/bin/qemu-arm
+extra-substituters = https://arm.cachix.org https://thefloweringash-armv7.cachix.org
+extra-trusted-public-keys = arm.cachix.org-1:K3XjAeWPgWkFtSS9ge5LJSLw3xgnNqyOaG7MDecmTQ8= thefloweringash-armv7.cachix.org-1:v+5yzBD2odFKeXbmC+OPWVqx4WVoIVO6UXgnSAWFtso=
+----
+
+If you are running on the NixOS then you can use configuration:
+
+----
+boot.binfmt.emulatedSystems = [ "aarch64-linux" "armv7l-linux" ];
+----