commit db70623bff0f77d29f70c7267c24c15f4d71ae71
parent 0777bb47c0015e9b34b2c72ee05ed35d90fc6320
Author: Daniel Barlow <dan@telent.net>
Date: Fri, 17 Feb 2023 20:54:18 +0000
improve markup
Diffstat:
1 file changed, 32 insertions(+), 26 deletions(-)
diff --git a/doc/developer.rst b/doc/developer.rst
@@ -8,7 +8,7 @@ documents various affordances for iteration and experiments.
In general, packages and tools that run on the "build" machine are
available in the ``buildEnv`` derivation and can most easily
-be added to your environment by running ``nix-shell``
+be added to your environment by running :command:`nix-shell`
@@ -27,7 +27,7 @@ To build it,
nix-build -I liminix-config=path/to/your/configuration.nix --arg device "import ./devices/qemu" -A outputs.default
-In a ``buildEnv`` nix-shell, you can use the ``mips-vm`` command
+In a ``buildEnv`` nix-shell, you can use the :command:`mips-vm` command
to run Qemu with appropriate options. It connects the Liminix
serial console and the `QEMU monitor <https://www.qemu.org/docs/master/system/monitor.html>`_ to stdin/stdout. Use ^P (not ^A) to switch to the monitor.
@@ -37,9 +37,9 @@ serial console and the `QEMU monitor <https://www.qemu.org/docs/master/system/m
If you run with ``--background /path/to/some/directory`` as the first
parameter, it will fork into the background and open Unix sockets in
-that directory for console and monitor. Use ``connect-vm`` (also in the
-``buildEnv`` environment) to connect to either of these sockets, and ^O
-to disconnect.
+that directory for console and monitor. Use :command:`connect-vm`
+(also in the ``buildEnv`` environment) to connect to either of these
+sockets, and ^O to disconnect.
Networking
==========
@@ -47,13 +47,13 @@ Networking
VMs can network with each other using QEMU
socket networking. We observe these conventions, so that we can run
multiple emulated instances and have them wired up to each other in
-the right way
+the right way:
* multicast 230.0.0.1:1234 : access (interconnect between router and "isp")
* multicast 230.0.0.1:1235 : lan
* multicast 230.0.0.1:1236 : world (the internet)
-A VM started with ``mips-vm`` is connected to "lan" and "access", and
+A VM started with :command:`mips-vm` is connected to "lan" and "access", and
the emulated border network gateway (see below) runs PPPoE and is
connected to "access" and "world".
@@ -65,8 +65,8 @@ In pkgs/routeros there is a derivation to install and configure
concentrator connected to the ``access`` and ``world`` networks, so that
Liminix PPPoE client support can be tested without actual hardware.
-This is made available as the ``routeros`` command in ``buildEnv``, so you
-can do something like::
+This is made available as the :command:`routeros` command in
+``buildEnv``, so you can do something like::
mkdir ros-sockets
nix-shell
@@ -95,8 +95,8 @@ TFTP.
There is a rudimentary TFTP server bundled with the system which runs
from the command line, has an allowlist for client connections, and
follows symlinks, so you can have your device download images direct
-from the ``./result`` directory without exposing ``/nix/store/`` to the
-internet or mucking about copying files to ``/tftproot``. If the
+from the :file:`./result` directory without exposing :file:`/nix/store/` to the
+internet or mucking about copying files to :file:`/tftproot`. If the
permitted device is to be given the IP address 192.168.8.251 you might
do something like this:
@@ -122,9 +122,9 @@ image instead of flashing. In your device configuration add
};
and then build ``outputs.tftproot``. This creates a file in
-``result/`` called ``boot.scr`` containing commands that you can copy
-and paste into U-Boot which will transfer the kernel and filesystem
-over TFTP and boot the kernel from RAM.
+``result/`` called ``boot.scr``, which you can copy and paste into
+U-Boot to transfer the kernel and filesystem over TFTP and boot the
+kernel from RAM.
Networking
@@ -144,16 +144,16 @@ router from the internet so you can borrow the cable/fibre/DSL.
* an L2TP service such as https://www.aa.net.uk/broadband/l2tp-service/
You need to configure the Ethernet card for VFIO passthru, then
-you can execute ``run-border-vm`` in a ``buildEnv`` shell,
+you can execute :command:`run-border-vm` in a ``buildEnv`` shell,
which starts up QEMU using the NixOS configuration in
-``bordervm-configuration.nix``.
+:file:`bordervm-configuration.nix`.
In this VM
-* your Liminix checkout is mounted under ``/home/liminix/liminix``
+* your Liminix checkout is mounted under :file:`/home/liminix/liminix`
* TFTP is listening on the ethernet device and serving
- ``/home/liminix/liminix``. The server IP address is 10.0.0.1
+ :file:`/home/liminix/liminix`. The server IP address is 10.0.0.1
* a PPPOE-L2TP relay is running on the same ethernet card, which
spawns L2TPv2 Access Concentrator sessions to your specified
@@ -163,18 +163,20 @@ In this VM
service can be configured into your test device - bordervm
doesn't need to know about them.
-To configure bordervm, you need a file called ``bordervm.conf.nix``
-which you can create by copying and appropriately editing ``bordervm.conf-example.nix``
+To configure bordervm, you need a file called :file:`bordervm.conf.nix`
+which you can create by copying and appropriately editing :file:`bordervm.conf-example.nix`
-Note: If you make changes to the bordervm configuration after
-executing ``run-border-vm``, you need to remove the ``border.qcow2``
-disk image file otherwise the changes won't get picked up.
+.. note::
+
+ If you make changes to the bordervm configuration after executing
+ :command:`run-border-vm`, you need to remove the :file:`border.qcow2` disk
+ image file otherwise the changes won't get picked up.
Running tests
*************
-You can run all of the tests by evaluating ``ci.nix``, which is the
+You can run all of the tests by evaluating :file:`ci.nix`, which is the
input I use in Hydra. Note that it expects Nixpkgs stable `and` unstable
as inputs, because it builds the qemu device against both.
@@ -197,9 +199,13 @@ Diagnosing unexpectedly large images
Sometimes you can add a package and it causes the image size to balloon
because it has dependencies on other things you didn't know about. Build the
``outputs.manifest`` attribute, which is a JSON representation of the
-filesystem, and you can run ``nix-store --query`` on it.::
+filesystem, and you can run :command:`nix-store --query` on it.
+
+.. code-block:: console
- nix-build -I liminix-config=path/to/your/configuration.nix --arg device "import ./devices/qemu" -A outputs.manifest -o manifest
+ nix-build -I liminix-config=path/to/your/configuration.nix \
+ --arg device "import ./devices/qemu" -A outputs.manifest \
+ -o manifest
nix-store -q --tree manifest
