Dev Guide

Development Environment

Currently, we target 24.04 Ubuntu LTS for releases. However, we don't recommend using your host machine for development (due to the fact that setting up tests modifies your host system and requires root privileges). Instead, we recommend using a virtual machine to develop and test SaunaFS. In the future, we will probably provide a Docker image for development instead.

You can use any virtualisation software you like.

Editors

You can use any editor you like. The core team uses various editors, including Visual Studio Code, CLion and Vim.

Building

Sharing the source code with the VM

If you want to use the editors on your host machine, you should share the source directory with the VM and do your building/testing/running on the VM. You'll need to check your virtualisation software's documentation for how to do this.

For example, in KVM you can add a filesystem passthrough in virt-manager or by editing the VM XML file directly. If using virt-manager, you should use the virtiofs driver, the source path should be the path to the SaunaFS source code on your host machine, and target path something like saunafs.

You can then mount the shared directory with the following command:

sudo mkdir /opt/saunafs
sudo mount -t virtiofs saunafs /opt/saunafs

To mount every time you start the VM, add the following line to /etc/fstab:

saunafs /opt/saunafs virtiofs defaults 0 0

Dependencies/Installing Tests

You can use the following script to both install the dependencies and the testing environment:

tests/setup_machine.sh setup /mnt/hda /mnt/hdb /mnt/hdc /mnt/hdd /mnth/hde /mnt/hdf

You can also run the script without arguments, and it will explain what it does.

Compiling

We use CMake for building. There are some useful options you can pass to CMake:

• DCMAKE_COMPILE_COMMANDS=ON: This will generate a compile_commands.json file which is useful for editors and tools to understand the build system. It should work fine on the host machine, as long as you have the necessary dependencies installed on the host (otherwise, it might show missing dependencies). Check the previous script code for the dependencies for Ubuntu LTS 22.04.
• DENABLE_TESTS=1: This will enable building the tests.
• DENABLE_DOCS=1: This will enable building the documentation.

In the source directory, you can run the following commands to build the project:

mkdir build && cd build
cmake -DCMAKE_COMPILE_COMMANDS=ON -DENABLE_TESTS=1 -DENABLE_DOCS=1 ..
make -j4 # Generally 4 is a safe option, see below

The number of jobs you should use for make depends on the number of cores your VM has (i.e if you have less than 4 cores, you should use less than 4 jobs) and the amount of RAM you have. If you use too many jobs, you could run out of RAM pretty quickly. For example, with 32 cores, you could use 32 jobs, but you'll need about 100GB of RAM.

After make finishes, you can install SaunaFS with the following command:

sudo make install

You can also sudo make -j$(jobs) install to both build and install in one command. However, you'll need to use sudo every time you want to build.

Configuring SaunaFS/tests

We use a mixture of unit and integration tests. The integration tests require some more setup. Assuming you ran the setup_machine.sh script, you need to edit the /etc/saunafs_tests.conf file, uncomment the part with SAUNAFS_ROOT, and set that to /usr/local/ (or wherever you installed SaunaFS).

You also need to setup networking a bit. Currently SaunaFS forbids communication with master on localhost. You need to add a new IP address to your loopback interface. You can do this with the following command:

sudo ip addr add 10.33.33.33 dev lo

To make this change permanent, you can add the following line under ethernets in /etc/network/00-installer-config.yaml (if you installed Ubuntu Server):

  lo:
    addresses:
    - 10.33.33.33/8

Generate the configuration with the following command:

sudo netplan --debug generate

Restart the network service with the following command:

sudo systemctl restart systemd-networkd

Verify localhost works with both 127.0.0.1 and 10.33.33.33 with ping.

You should then set sfsmaster in /etc/hosts to that IP address for ease of remembering the IP address.

10.33.33.33 sfsmaster

Running the tests

Running unit tests is easy, in the build directory after building, run the following command:

src/unittests/unittests

For the integration tests, there are test suites available. These are managed by gtest and are simple shell scripts. You can see all of the test suites in the tests/test_suites directory, but the most important one is the SanityChecks suite. This should be run to ensure nothing is broken and before submitting a pull request.

To run the SanityChecks suite, you can run the following command:

saunafs-tests --gtest_filter="SanityChecks.*"

Others of note are the LongSystemTests and the ShortSystemTests. These are run by the CI system. The ShortSystemTests take about an hour to run, and the LongSystemTests can take up to a day.

Submitting Pull Requests

See the CONTRIBUTING.md file for more information on how to submit pull requests.

Git specific settings

Code Style

We use clang-format to enforce a consistent code style. You can run something like git-clang-format to format your changes before committing.

git add <your changes>
git clang-format --style=file

Ignore revisions

Sometimes you want to ignore certain revisions when running git blame (i.e large rename commits). You can use the .git-blame-ignore-revs file to do this.

git config blame.ignoreRevsFile .git-blame-ignore-revs