Overview

This project is written in Python, mostly presenting as a CLI using Click.

NixOS Compose also exposes itself as an execo interface for use in other execo scripts.

NixOS Compose heavily uses the subprocess module for using adjacent tools on the system. You should be good to go if you are using the nxcShell flake devShell.

NixOS Compose runs its unit tests & integration tests with pytest.

The project also uses Halo as a UI helper.

Development environment

Local

The main way to develop the tool is to do this locally on your computer.

All you need is Nix (both nixcpp or Lix are supported). Once you have flakes enabled, you can run:

nix develop

This will setup a shell where everything you need is available!

You will only be missing an editor; We recommend using zed (it is not included in the devshell).

You can now run your favorite IDE in your devshell:

Tip

For opening zed:

zeditor .

Grid5000

Some users have reportedly developed the tool on g5k directly. That’s a crazy thing as g5k does not support nix by default.

Support for this is limited (Justfile does not take this in account when running) & may break in the future.

One way to get it working is to follow the g5k local installation.

Important commands

Most of the helper commands use just. Make sure it is installed to use the justfile.

Linting

It is important to lint your project before pushing, or the CI will block your PR.

You can do that by running:

just lint

or:

nix fmt

This will change existing code, make sure to run it BEFORE you commit anything (or you will have to amend).

BasedPyRight

If you are using an editor (ie zed) with pyright/basedpyright support, you should already be good to go.

If not, it is important to validate your code before pushing, or the CI will block your PR.

You can do that by running:

basedpyright

Pytest

It is important for you to run tests when you change stuff in the code.

The tests are written to make sure that none of your changes break existing features. If it does, it will let you know and tell you which tests to change (or which feature was broken!!!).

Tests are your friends, not your enemy, treat them with care and they will tell you their wisdom (just keep tests up-to-date with current behaviour & you will know what’s broken).

To run tests you can run 1 of these, in speed order (test is around <20sec per tests, test-full takes hours in total):

just test
just test-fast
just test-slow
just test-full

• You can specify a Grid5000 site as a 1st argument if you want to test run integration tests on G5K, default is none (local only).
• You can specify the number of cores to use in tests as 2nd argument (paralellism is provided by pytest-xdist), default is 4.
• You can specify the -k flag as 3rd argument; -k enables you to run tests matching an expression (kind of a test search bar), here is the doc.

Tip

just test-full grenoble 8 g5k-image-script-nbp-mpi

Contributing

You can find all of that in CONTRIBUTING.md.