liminix

commit 3669a4000f4f038bceb246e853d6fca657b5cc19
parent f7b507587d2b612de61e29109ce16e26c3ca9f25
Author: Daniel Barlow <dan@telent.net>
Date:   Wed,  9 Aug 2023 22:27:18 +0100

explain (badly) the module/service dynamic

Diffstat:
M
doc/user.rst
 | 
39
++++++++++++++++++++++++++++++++-------

1 file changed, 32 insertions(+), 7 deletions(-)
diff --git a/doc/user.rst b/doc/user.rst
@@ -83,19 +83,42 @@ Creating configuration.nix
 ==========================
 
 
-You need to create a :file:`configuration.nix` that describes your device
-and the services that you want to run on it. Start by copying
-:file:`vanilla-configuration.nix` and adjusting it, or look in the `examples`
-directory for some pre-written configurations.
+You need to create a :file:`configuration.nix` that describes your
+device and the services that you want to run on it. The best way to
+get started is by reading one of the examples such as
+:file:`examples/rotuer.nix` and modifying it to your needs.
 
 :file:`configuration.nix` conventionally describes the packages, services,
 user accounts etc of the device. It does not describe the hardware
 itself, which is specified separately in the build command (as you
 will see below).
 
-Your configuration may include modules: it probably *should*
-include the ``standard`` module unless you understand what it
-does and what happens if you leave it out.
+Most of the functionality of a Liminix system is driven by *services*
+which are declared by *modules*: thus, to add for example an NTP service
+you first add :file:`modules/ntp` to your ``imports`` list, then
+you create a service by calling :code:`config.system.service.ntp.build { .... }`
+with the appropriate service-dependent configuration parameters.
+
+.. code-block:: nix
+
+  let svc = config.system.service;
+  in {
+    # ...
+    imports = [
+      ./modules/ntp
+      # ....
+    ];
+    config.services.ntp = svc.ntp.build {
+      pools = { "pool.ntp.org" = ["iburst"]; };
+      makestep = { threshold = 1.0; limit = 3; };
+    };
+
+A :ref:`full list of module options <module-options>` is provided
+later in this manual.
+
+You *most likely* want to include the ``standard`` module unless you
+have a quite unusual use case for a very minimal system, in which case
+you will understand what it does and what happens if you leave it out.
 
 .. code-block:: nix
 
@@ -319,4 +342,6 @@ Caveats
 Configuration options
 *********************
 
+.. _module-options:
+
 .. include:: modules.rst