nix-flake: Add Section in 'Getting Started' documentation

Signed-off-by: Sarah Renkhoff <[email protected]>

doc/bridle/getting_started.rst

@@ -3,10 +3,10 @@
 Getting started
 ###############
 
-To quickly get started with |BRIDLE|, use the
-:ref:`Getting Started Assistant <gs_assistant>` to set up your development
-environment. Alternatively, check the :ref:`gs_installing` section for
-instructions on setting up your environment manually.
+To quickly get started with |BRIDLE|, use the :ref:`Getting Started Assistant
+<gs_assistant>` to set up your development environment. Alternatively, check the
+:ref:`gs_installing` section for instructions on setting up your environment
+manually. To set up your system for using Bridle with Nix, see :ref:`gs_nix`.
 
 We recommend using [t.b.d.] for building your applications. See
 :ref:`gs_programming` for the download links and instructions. In case you
@@ -25,7 +25,7 @@ start developing!
    gs_recommended_versions
    gs_assistant
    gs_installing
+   gs_nix
    gs_programming
    gs_testing
    gs_modifying
-

doc/bridle/gs_nix.rst

@@ -0,0 +1,69 @@
+.. _gs_nix:
+
+Working with Bridle via Nix
+###########################
+
+.. contents::
+   :local:
+   :depth: 2
+
+An alternative way to develop with Bridle is through `Nix <https://nixos.org/>`, a functional package
+managing system. This way, all dependencies can be installed using a single
+tool. Packages installed this way don't pollute your regular system, and can
+easily be removed later.
+
+Installing the Nix Package Manager
+**********************************
+
+To get started using Nix, you will need to install the package manager itself.
+Most distributions provide packages for installing it using their regular
+package manager (e.g. on Ubuntu provides a ``nix`` package that can be installed
+using ``apt install nix``). If your distribution doesn't provide such a package, see the
+instructions on `nixos.org <https://nixos.org/download>` to get a Nix
+installation.
+
+Enabling Flakes
+***************
+
+Flakes are an experimental feature that enables fully hermetic and reproducible
+builds. To enable flakes, add
+
+.. parsed-literal::
+   :class: highlight
+
+   experimental-features = nix-command flakes
+
+to ``~/.config/nix/nix.conf`` (creating this file if it doesn't exist).
+
+Using the Bridle Flake
+**********************
+
+The Bridle flake provides several outputs that can be used in different ways.
+The most straight-forward way to use it is via the ``devShell`` output. By running
+``nix develop`` in your bridle directory, nix will build and drop you into a
+shell environment in which all necessary tools and dependencies are present for
+developing Zephyr applications with Bridle. You can then proceed to create a
+west workspace ontop of your bridle directory and work as usual.
+
+The Bridle flake also provides a special output ``workspace``, which provides a
+fully fetched west workspace according to the current west manifest, in the nix
+store. This output can be used in further nix derivations, e.g. to create
+reproducible firmware builds. The ``bridle-doc`` output is an example of a
+derivation using this workspace to build the Bridle documentation.
+
+Keeping the Bridle Flake Up-to-date
+***********************************
+
+Like all nix flakes, the Bridle flake has its inputs locked using the
+``flake.lock`` file. Running ``nix flake update`` in the bridle directory will
+check for upstream changes and bump any changed inputs in the lockfile.
+
+The flake also relies on two auto-generated nix files to satisfy dependencies
+specified in python-specific ``requirements.txt`` files and in the west
+manifest, respectively. To keep these in sync with upstream changes, the west
+subcommand ``west nix-update`` can be used. It will parse the relevant
+``requirements.txt`` files and make sure the ``devshell`` environment provides
+all necessary python packages. It will also parse the west manifest, and update
+the workspace flake accordingly. Finally, it will run ``nix flake update`` on
+the workspace flake (**not** the main Bridle flake!), to make sure ``west`` and
+``nix`` use the same upstream revisions.