From 1c3242cab1f89eae29ddc74942b7060b0c708b85 Mon Sep 17 00:00:00 2001 From: Daniel Barlow Date: Sun, 14 Jul 2024 12:26:07 +0100 Subject: [PATCH] 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. --- doc/configuration.rst | 23 ++--------------------- doc/index.rst | 2 +- doc/installation.rst | 38 ++++++++++++++++++++++++++++++++++++++ 3 files changed, 41 insertions(+), 22 deletions(-) diff --git a/doc/configuration.rst b/doc/configuration.rst index e86c5ee..3f87850 100644 --- 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 index d8199c8..83ad8ec 100644 --- 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 index 4aaa8ff..85d74e7 100644 --- 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) *********************************************