commit 1c3242cab1f89eae29ddc74942b7060b0c708b85
parent 44ea6833910650764ac47c30690dc9fadd9ab62b
Author: Daniel Barlow <dan@telent.net>
Date: Sun, 14 Jul 2024 12:26:07 +0100
doc: swap order of configuration and installation
you can get a device up and running using a lightly edited example
config before you need to read all the reference info, so let's
have the documentation in that order.
Diffstat:
3 files changed, 41 insertions(+), 22 deletions(-)
diff --git a/doc/configuration.rst b/doc/configuration.rst
@@ -1,27 +1,8 @@
+.. _configuration:
+
Configuration
#############
-Liminix uses the Nix language to provide congruent configuration
-management. This means that to change anything about the way in
-which a Liminix system works, you make that change in
-your :file:`configuration.nix` (or one of the other files it references),
-and rerun :command:`nix-build` or :command:`liminix-rebuild` to action
-the change. It is not possible (at least, without shenanigans) to make
-changes by logging into the device and running imperative commands
-whose effects may later be overridden: :file:`configuration.nix`
-always describes the entire system and can be used to recreate that
-system at any time. You can usefully keep it under version control.
-
-If you are familiar with NixOS, you will notice some similarities
-between NixOS and Liminix configuration, and also some
-differences. Sometimes the differences are due to the
-resource-constrained devices we deploy onto, sometimes due to
-differences in the uses these devices are put to.
-
-
-Configuration taxonomy
-**********************
-
There are many things you can specify in a configuration, but these
are the ones you most commonly need to change:
diff --git a/doc/index.rst b/doc/index.rst
@@ -7,8 +7,8 @@ Liminix
intro
tutorial
- configuration
installation
+ configuration
admin
development
modules
diff --git a/doc/installation.rst b/doc/installation.rst
@@ -8,6 +8,44 @@ generic instructions, but please refer to the documentation for your
device to find whether and how well they apply.
+Building a firmware image
+*************************
+
+Liminix uses the Nix language to provide congruent configuration
+management. This means that to change anything about the way in
+which a Liminix system works, you make that change in
+your :file:`configuration.nix` (or one of the other files it references),
+and rerun :command:`nix-build` or :command:`liminix-rebuild` to action
+the change. It is not possible (at least, without shenanigans) to make
+changes by logging into the device and running imperative commands
+whose effects may later be overridden: :file:`configuration.nix`
+always describes the entire system and can be used to recreate that
+system at any time. You can usefully keep it under version control.
+
+If you are familiar with NixOS, you will notice some similarities
+between NixOS and Liminix configuration, and also some
+differences. Sometimes the differences are due to the
+resource-constrained devices we deploy onto, sometimes due to
+differences in the uses these devices are put to.
+
+For a more full description of how to configure Liminix, see
+:ref:`configuration`. Assuming for the moment that you want a typical
+home wireless gateway/router, the best way to get started is to copy
+:file:`examples/rotuer.nix` and edit it for your requirements.
+
+
+.. code-block:: console
+
+ $ cp examples/rotuer.nix configuration.nix
+ $ vi configuration.nix # other editors are available
+ $ # adjust this next command for your hardware device
+ $ nix-build -I liminix-config=./configuration.nix \
+ --arg device "import ./devices/gl-mt300a" -A outputs.default
+
+Usually (not always, *please check the documentation for your device*)
+this will leave you with a file :file:`result/firmware.bin`
+which you now need to flash to the device.
+
Flashing from the boot monitor (TFTP install)
*********************************************
