mobile-nixos · Apr 5, 2020 · Apr 5, 2020 · Apr 6, 2020 · Apr 6, 2020 · Apr 6, 2020
diff --git a/default.nix b/default.nix
@@ -40,27 +40,20 @@ let
     else deviceFromEnv
   ;
 
-  # Evaluates NixOS, mobile-nixos and the device config with the given
-  # additional modules.
-  # Note that we can receive a "special" configuration, used internally by
-  # `release.nix` and not part of the public API.
-  evalWith = modules: import ./lib/eval-config.nix {
-    modules =
-      (if device ? special
-      then [ device.config ]
-      else [ (import (./. + "/devices/${final_device}" )) ])
-      ++ modules
-      ++ [ additionalConfiguration ]
-    ;
-  };
+  inherit (import ./lib/release-tools.nix) evalWith;
 
   # The "default" eval.
-  eval = evalWith configuration;
+  eval = evalWith {
+    device = final_device;
+    modules = configuration;
+  };
 
   # This is used by the `-A installer` shortcut.
-  installer-eval = evalWith [
-    ./profiles/installer.nix
-  ];
+  installer-eval = evalWith {
+    modules = [
+      ./profiles/installer.nix
+    ];
+  };
 
   # Makes a mostly useless header.
   # This is mainly useful for batch evals.

diff --git a/doc/_support/options/default.nix b/doc/_support/options/default.nix
@@ -0,0 +1,55 @@
+{ pkgs
+, glibcLocales
+, nixosOptionsDoc
+, runCommandNoCC
+, ruby
+}:
+
+let
+  # Release tools used to evaluate the devices metadata.
+  mobileReleaseTools = (import ../../../lib/release-tools.nix);
+  inherit (mobileReleaseTools) evalWith;
+  inherit (mobileReleaseTools.withPkgs pkgs) specialConfig;
+
+  dummyConfig = system: specialConfig {
+    name = system;
+    buildingForSystem = system;
+    system = system;
+    config = {};
+  };
+
+  dummyEval = evalWith {
+    device = (dummyConfig "aarch64-linux");
+    modules = [
+      {
+        disabledModules = [
+          # As of 2020-04-06 this module fails the evaluation. (ae6bdcc53584aaf20211ce1814bea97ece08a248)
+          # ⇒ Invalid package attribute path `nextcloud17'
+          <nixpkgs/nixos/modules/services/web-apps/nextcloud.nix>
+
+          # As of 2020-04-06 this module fails the evaluation. (ae6bdcc53584aaf20211ce1814bea97ece08a248)
+          # ⇒ Package ‘ceph-14.2.7’ in .../nixpkgs/pkgs/tools/filesystems/ceph/default.nix:178
+          #   is not supported on ‘aarch64-linux’, refusing to evaluate.
+          <nixpkgs/nixos/modules/services/network-filesystems/ceph.nix>
+        ];
+      }
+    ];
+  };
+
+  optionsJSON = (nixosOptionsDoc { options = dummyEval.options; }).optionsJSON;
+  systemTypesDir = ../../../modules/system-types;
+in
+
+runCommandNoCC "mobile-nixos-docs-options" {
+  nativeBuildInputs = [
+    ruby
+    glibcLocales
+  ];
+  optionsJSON = "${optionsJSON}/share/doc/nixos/options.json";
+}
+''
+  mkdir -p $out/options
+  export LC_CTYPE=en_US.UTF-8
+  cp $optionsJSON $out/options/options.json
+  ruby ${./generate-options-listing.rb}
+''
diff --git a/doc/_support/options/generate-options-listing.rb b/doc/_support/options/generate-options-listing.rb
@@ -0,0 +1,87 @@
+require "json"
+
+$out = ENV["out"]
+$root = ENV["mobileNixOSRoot"]
+
+# We want `null` for `nil`s...
+# We already know it's *set* at this point.
+def as_nix(value)
+  if value.nil?
+    "null"
+  else
+    value.inspect
+  end
+end
+
+# Filter non-mobile-nixos options.
+options = JSON.parse(File.read(ENV["optionsJSON"]))
+  .select do |k, v|
+    v["declarations"].any? {|path| path.match(/^#{$root}/)}
+  end
+
+# Write the options listing.
+File.open(File.join($out, "options/index.adoc"), "w") do |file|
+  file.puts <<~EOF
+    = Mobile NixOS Options
+    include::_support/common.inc[]
+    :generated: true
+
+    The following list only includes the options defined by Mobile NixOS.
+
+    Refer to the link:https://nixos.org/nixos/options.html[NixOS options listing]
+    for more options.
+
+    == Options list
+
+  EOF
+
+  # "mobile.quirks.u-boot.initialGapSize"=>
+  #{"declarations"=>
+  #  [".../mobile-nixos/modules/system-types/u-boot"],
+  # "default"=>true, 
+  # "description"=>
+  #  "Size (in bytes) to keep reserved in front of the first partition.\n",
+  # "loc"=>["mobile", "quirks", "u-boot", "initialGapSize"],
+  # "readOnly"=>false,
+  # "type"=>"signed integer"},
+
+  file.puts <<~EOF
+    ++++
+    <dl class="options-list">
+  EOF
+  options.keys.sort.each do |path|
+    option = options[path]
+    file.puts <<~EOF
+    <div>
+      <dt>
+        <tt>
+          #{path}
+        </tt>
+      </dt>
+      <dd>
+        <dl class="option-definition">
+        <dt>Type:</dt>
+        <dd class="option-type">#{option["type"]}</dd>
+    #{
+      if option.has_key?("default")
+        <<~EOD
+        <dt>Default:</dt>
+        <dd class="option-default"><code>#{as_nix(option["default"])}</code></dd>
+        EOD
+      end
+    }
+        <dt>Description:</dt>
+        <dd class="option-description">
+    ++++
+    #{option["description"]}
+    ++++
+        </dd>
+      </dd>
+    </div>
+    EOF
+  end
+  file.puts <<~EOF
+    </dl>
+    ++++
+  EOF
+end
diff --git a/doc/_support/styles/theme.less b/doc/_support/styles/theme.less
@@ -62,10 +62,6 @@ table.with-links {
 	}
 }
 
-dl dd p:last-child {
-	margin-bottom: 0;
-}
-
 .device-sidebar {
 	background-color: #fff;
 	#screen-sm-min({
@@ -102,4 +98,18 @@ dl dd p:last-child {
 
 	margin-bottom: @gutter;
 
+	dl dd > .paragraph:last-child p,
+	dl dd > p:last-child {
+		margin-bottom: 0;
+	}
+}
+
+.options-list {
+	dt > tt {
+		padding: 0;
+	}
+	& > div > dd {
+		border-left: @gutter/2 solid lighten(@color-blue-light, 20%);
+		padding-left: @gutter/2;
+	}
 }
diff --git a/doc/default.nix b/doc/default.nix
@@ -10,6 +10,9 @@ let
 
   # Asciidoc source for the devices section.
   devices = pkgs.callPackage ./_support/devices { };
+
+  # Asciidoc source for the options section.
+  options = pkgs.callPackage ./_support/options { };
 in
 
 stdenv.mkDerivation {
@@ -52,6 +55,9 @@ stdenv.mkDerivation {
     # Copies the generated asciidoc source for the devices.
     cp -prf ${devices}/devices devices
 
+    # Copies the generated asciidoc source for the options.
+    cp -prf ${options}/options options
+
     # Use our pipeline to process the docs.
     process-doc "**/*.adoc" "**/*.md" \
       --styles-dir="${styles}" \

diff --git a/doc/getting-started.adoc b/doc/getting-started.adoc
@@ -4,8 +4,8 @@ include::_support/common.inc[]
 This guide assumes the user knows how to prepare their device for development
 use. These instructions are device-dependent, but not specific to Mobile NixOS.
 
-Briefly said, the device's bootloader must be unlocked, allowing to run
-custom-built operating system images.
+Briefly said, the device's bootloader must be unlocked, meaning that it allows
+running custom-built operating system images.
 
 
 == Source Code
@@ -32,78 +32,45 @@ The link:https://help.github.com/en/github/collaborating-with-issues-and-pull-re
 GitHub help article] may help.
 
 
-== Compiling
+== Compiling and Running
 
 This is where it becomes harder to make a simple guide. These are different,
 heterogeneous, hardware platforms, with different quirks, compilation steps,
-and mainly, installation steps. Please also look at the documentation for your
-specific device as it may contain further or replacement instructions.
+and mainly, installation steps.
 
-=== Android devices
+Fear not, look for your particular device on the <<devices/index.adoc#,devices list>>
+page, will likely contain the necessary instructions.
 
-To build a system image, you will need to build on the native target architecture.
+=== Using a pre-built `system.img`
 
-Building the boot image (`boot.img`) can be done through cross-compilation. The
-build tooling will automatically handle this.
+When bootstrapping yourself up, without an aarch64-linux system, it may be
+easier to deal with some systems if you use a pre-built `rootfs` rather than
+rely on the dummy basic `rootfs`. For those systems, you can download a
+link:https://hydra.nixos.org/job/mobile-nixos/unstable/examples-demo.aarch64-linux.rootfs[pre-built rootfs],
+and configure the system build to use it. Assuming it is next to the
+`local.nix` file in your Mobile NixOS checkout.
 
+```nix
+# local.nix
+{ pkgs, ... }:
+
+let
+  fromPath = input: pkgs.runCommandNoCC "system.img" {
+    filename = "system.img";
+    filesystemType = "ext4";
+  } ''
+    mkdir -p "$out"
+    cp ${input} "$out/$filename"
+  '';
+in
+{
+  system.build.rootfs = fromPath ./system.img;
+}
+```
 
- nix-build --argstr device "$DEVICE" -A build.android-bootimg
-
-Assuming `DEVICE` has been set to an appropriate device name.
-
-=== Depthcharge devices
-
-To build full image, you will need to build on the native target architecture.
-
-Though, it is possible to build the partition `depthcharge` will boot from,
-which holds the kernel and initrd, through cross-compilation. The build tooling
-will automatically handle this.
-
- nix-build --argstr device "$DEVICE" -A build.kpart
-
-
-== Running
-
-This is where the device-specific and platform-specific instructions will help
-you. Though, here's a quick overview. Again, look at the documentation for your
-specific device, as it may contain further or replacement instructions.
-
-=== Android
-
-Some, if not most, Android-based platforms will allow you to boot the boot image
-using `fastboot`.
-
-Luckily, running stage-1 through `fastboot` is enough to get started porting for
-the target system, as it will exercise the harder initial bootstrapping parts.
-That is, getting a system working with a minimal set of useful features.
-
-The device will need to be booted in its bootloader, or `fastboot`, mode. The
-instructions are device-dependent. The boot image can be run using the following
-command.
-
- fastboot boot result
-
-If you have a system image (`system.img`) built, you can use `fastboot` to flash
-it to the device. Note that it might be too big to fit over the `system`
-partition. In such case, it can be flashed on the `userdata` partition.
-
-WARNING: *This will erase everything on the partition*. Additionally, the common
-backups methods, e.g. TWRP, will *not* backup the `userdata` partition.
-
- fastboot flash userdata system.img
-
-=== Depthcharge
-
-This one is annoying to get started currently. Without a full Mobile NixOS
-build, you will need to fill in some gaps manually.
-
-The link:https://www.chromium.org/chromium-os/chromiumos-design-docs/disk-format[
-upstream documentation about the disk format] may help shed some light in getting
-this booting.
-
-On a Mobile NixOS-built disk image for a ; depthcharge` device, you can replace
-the partition with the newly built image, for the next boot. This is especially
-useful with USB devices or SD cards.
+Note that for Android-based devices, you can simply use the `system.img`. There
+is no need to configure it as such. This is most useful for _depthcharge_ and
+_u-boot_ systems.
 
 
 == Customizing
@@ -124,6 +91,10 @@ A sample `local.nix`.
 }
 ```
 
+As Mobile NixOS is a superset on top of NixOS, all NixOS options can be used in
+this configuration file, though take note that most NixOS options will only
+affect the stage-2 (rootfs, system.img) build.
+
 
 == Contributing
 

diff --git a/lib/eval-config.nix b/lib/eval-config.nix
@@ -1,6 +1,2 @@
-{ baseModules ? import ../modules/module-list.nix
-, ...
-} @ args:
-import <nixpkgs/nixos/lib/eval-config.nix> (args // {
-  inherit baseModules;
-})
+# Simple proxy to the upstream Nixpkgs eval-config.nix
+import <nixpkgs/nixos/lib/eval-config.nix>
diff --git a/lib/release-tools.nix b/lib/release-tools.nix
@@ -6,6 +6,26 @@
     (builtins.attrNames (builtins.readDir ../devices))
   ;
 
+  # Evaluates NixOS, mobile-nixos and the device config with the given
+  # additional modules.
+  # Note that we can receive a "special" configuration, used internally by
+  # `release.nix` and not part of the public API.
+  evalWith =
+    { modules
+    , device
+    , additionalConfiguration ? {}
+    , baseModules ? ((import ../modules/module-list.nix) ++ [ ../modules/_nixos-integration.nix ])
+  }: import ./eval-config.nix {
+    inherit baseModules;
+    modules =
+      (if device ? special
+      then [ device.config ]
+      else [ (import (../. + "/devices/${device}" )) ])
+      ++ modules
+      ++ [ additionalConfiguration ]
+    ;
+  };
+
   # These can rely freely on lib, avoir depending on pkgs.
   withPkgs = pkgs:
     let