Development setup

The requirements for compiling Fast Downward are listed in the build instructions. Our automated tests have additional dependencies that can be installed as follows:

apt-get install clang-format-18 clang-tidy-18 python3.8 python3.10 python3-pip valgrind wget
python3 -m pip install tox

For running the autodoc script you'll need to install txt2tags via python3 -m pip install -r misc/autodoc/requirements.txt.

We recommend using Ubuntu 24.04 for Fast Downward development since this version is also used by the core developers and it allows installing many dependencies via the package manager.

Important: We want the code to compile without warnings, but in favour of user-friendliness we did not add the -Werror flag to the build script. Make sure that you compile your code with the -Werror flag, for example by adding export CXXFLAGS+=-Werror to your bashrc. Note that you should build the binary from scratch after this (i.e. remove the builds directory if it exists), since it will not recompile files unless they have been changed.

Using clang-format

We use clang-format with a Fast Downward configuration file (.clang-format in the repository root) to enforce some of our formatting conventions. If a source file is properly formatted, applying clang-format should be an idempotent operation (i.e., result in an identical file). This is important so that we can verify our style rules automatically, at least for those rules which clang-format can handle.

Not all aspects of source layout are handled by clang-format, so please still pay attention to things not handled by clang-format and our coding conventions.

Install clang-format with

sudo apt install clang-format-18

To then check the style of Python and C++ files, you can navigate to the misc directory and run

tox -e style

To automatically fix the style, you can run

tox -e fix-style

When fixing style, tox complains if there are uncommitted changes. If you want to fix the style of C++ files before committing, you can instead run

./misc/style/run-clang-format.py --force --modify

Running tests

To run all tests under all locally-available Python versions, run tox in the misc/ directory. The command creates Python virtual environments under misc/.tox. The directory uses ~50 MB and is not shown by git status. You can safely delete the directory after the tests have been run. To run a subset of tests, e.g., only the style checks, use tox -e style (see misc/tox.ini for other test environments). Many of the tests that tox executes are Bash/Python scripts or pytest modules, which you can also run individually. To check a pytest module, execute pytest my_module.py.

Using ccache to speed up builds

When building the same code files multiple times, ccache can cache and re-use the resulting objects to speed up build times.

1. sudo apt install ccache
2. Set the following variables in your .bashrc to use it

   export CMAKE_CXX_COMPILER_LAUNCHER=ccache
   export CCACHE_BASEDIR=/home/user   # Replace /home/user with your home directory
   export CCACHE_NOHASHDIR=true
   

The last two lines are optional but they allow ccache to use the cache across different file locations. For example, you could build in ~/projects/downward/main and then reuse the cache in ~/projects/downward/issue999. This will store file paths that start with $CCACHE_BASEDIR inside the binary as relative paths rather than absolute paths. That should be fine and I never had a problem with this but under some circumstances it could mean that debug symbols are not resolved correctly. If that happens, you can switch off the setting and rebuild.