Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

FOR v3.6: Create a nix flake for reproducible development and build environments #209

Merged
merged 8 commits into from
Mar 15, 2024
60 changes: 60 additions & 0 deletions doc.nix
Original file line number Diff line number Diff line change
@@ -0,0 +1,60 @@
{ lib
, stdenv
, west2nixHook
, pythonEnv
, cmake
, ninja
, doxygen
, mscgen
, graphviz
, git
, zephyr
, bridle
}:

stdenv.mkDerivation {

name = "bridle-doc";
src = bridle;
unpackPhase = ''
cp -r ${bridle} bridle
chmod +w -R bridle
cd bridle
git init
git config user.email "[email protected]"
git config user.name "Foo"
git checkout -b fake-branch
git add -A
git commit -m "Fake Commnit"
cd ..
'';

nativeBuildInputs = [
west2nixHook
pythonEnv
cmake
ninja
doxygen
mscgen
graphviz
git
];

dontUseCmakeConfigure = true;

CMAKE_PREFIX_PATH = "/build/bridle/share/bridle-package:/build/zephyr/share/zephyr-package";

buildPhase = ''
cd /build
chmod +w -R ./*
west build --cmake-only -b none -d build bridle/doc
west build -t zephyr-doxygen -b none -d build
west build -t bridle-doxygen -b none -d build
west build -t build-all -b none -d build
'';

installPhase = ''
mkdir $out
cp -r build/html $out/
'';
}
10 changes: 5 additions & 5 deletions doc/bridle/getting_started.rst
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -25,7 +25,7 @@ start developing!
gs_recommended_versions
gs_assistant
gs_installing
gs_nix
gs_programming
gs_testing
gs_modifying

97 changes: 97 additions & 0 deletions doc/bridle/gs_nix.rst
Original file line number Diff line number Diff line change
@@ -0,0 +1,97 @@
.. _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. 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::

experimental-features = nix-command flakes

to your private Nix configuration in ``~/.config/nix/nix.conf`` (creating this
file if it doesn't exist).

Using the Bridle Flake
**********************

The Bridle flake provides a ``devShell`` output, which is a shell environment in
which all necessary tools and dependencies are present for developing Zephyr
applications with Bridle. By running ``nix develop`` within the bridle repository,
you enter this environment. You can then proceed to create a west workspace
ontop of your bridle directory and work as usual.

You can also use the build hooks provided by the ``west2nix`` input to perform
builds directly via Nix, without creating an explicit west workspace. In this
case, the workspace manifest used will be that provided by the ``west2nix.toml``
lockfile (see below on how to bring it up-to-date if required). For an example
of such a derivation, see ``doc.nix``, which builds this documentation. For
another example of a simpler build, see `the west2nix repository
<https://github.com/adisbladis/west2nix>`_.

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. After
checking for breakages due to the update, e.g. via ``nix flake check``, and
confirming that ``nix develop`` drops you into a working shell, you should can
commit the updated ``flake.lock``. If you do notice breakage, you can simply
revert the update with ``git checkout flake.lock``.

The flake also relies on the manifest lockfile ``west2nix.toml``, which reflects
the state of a west workspace at a specific time. To update this lockfile, you
first need a full checkout of the workspace you want to lock:

.. code-block:: console

mkdir workspace && cd workspace
git clone https://github.com/tiacsys/bridle.git
west init -l bridle
west update

You can then run ``west2nix`` on this workspace and place the resulting lockfile
into the ``bridle`` directory:

.. code-block:: console

nix run ./bridle#west2nix
mv west2nix.toml bridle/

.. note::

Running ``west2nix`` directly inside the ``bridle`` directory is
likely to fail due to permission issues, hence running it from the workspace
directory instead.

Finally, you can commit your new lockfile:

.. code-block:: console

git add west2nix.toml
git commit -m "Updated west2nix.toml"

Similarly to updating the flake inputs, this update can be reverted simply by
resetting ``west2nix.toml`` to an earlier state.
Loading
Loading