Developer documentation
=======================

Building
--------

The build system uses `Nix`_ which must be installed before anything can be built.
Start by setting up the development/operations environment::

  $ nix-shell

Testing
-------

The test system uses `Nix`_ which must be installed before any tests can be run.

Unit tests are run using this command::

  $ nix-build nixos/unit-tests.nix

Unit tests are also run on CI.

The system tests are run using this command::

  $ nix-build nixos/system-tests.nix

The system tests boot QEMU VMs which prevents them from running on CI at this time.
The build requires > 10 GB of disk space,
and the VMs might be timing out on slow or busy machines.
If you run into timeouts,
try `raising the number of retries <https://whetstone.privatestorage.io/privatestorage/PrivateStorageio/-/blob/e8233d2/nixos/modules/tests/run-introducer.py#L55-62>`_.

It is also possible go through the testing script interactively - useful for debugging::

  $ nix-build -A private-storage.driver nixos/system-tests.nix

This will give you a result symlink in the current directory.
Inside that is bin/nixos-test-driver which gives you a kind of REPL for interacting with the VMs.
The kind of `Python in this testScript <https://whetstone.privatestorage.io/privatestorage/PrivateStorageio/-/blob/78881a3/nixos/modules/tests/private-storage.nix#L180>`_ is what you can enter into this REPL.
Consult the `official documentation on NixOS Tests <https://nixos.org/manual/nixos/stable/index.html#sec-nixos-tests>`_ for more information.

Updatings Pins
--------------

Nixpkgs
```````

To update the version of NixOS we deploy with, run:

.. code: shell

   nix-shell --run 'update-nixpkgs'

That will update ``nixpkgs-2015.json`` to the latest release on the nixos-21.05 channel.

To update the channel, the script will need to be updated,
along with the filenames that have the channel in them.


Gitlab Repositories
```````````````````
To update the version of packages we import from gitlab, run:

.. code: shell

   nix-shell --command 'tools/update-gitlab nixos/pkgs/<package>/repo.json'

That will update the package to point at the latest version of the project.\
The command uses branch and repository owner specified in the ``repo.json`` file,
but you can override them by passing the ``--branch`` or ``-owner`` arguments to the command.
A specific revision can also be pinned, by passing ``-rev``.


Architecture overview
---------------------

.. graphviz:: architecture-overview.dot


.. include::
      ../../../morph/grid/local/README.rst

.. _Nix: https://nixos.org/nix