Compatibility specifics

Disk location-dependent build process

Either on Linux on Windows, your project build process might be disk location-dependent, i.e, that your build does not work any more if the project is copied to another location. This happens when:

• your build scripts or your build system uses absolute paths to determine the position of the C/C++ files, or

• your build scripts use dependencies which are outside of your project and referred to using relative paths (e.g for a compile command running at the root of the project, using includes with flag -I../mylib .

If you are not sure if your build system is location-dependent, copy your project directory elsewhere, and attempt to build it using your usual script. If the script fails, it is.

In case your project is location-dependent, you have to use local mode when setting up your project.

Use local mode with your location-dependent project

When using local mode, you can only run builds on your own machine (and not on runners running on another machine), and beLow will work directly in your project. During the whole usage of beLow, from setting your project up to optimization process, you must not modify any of the source code or build scripts, otherwise beLow's would have an unpredictible behaviour.

Local mode is also recommended if your project has thousands of files and/or an important volume on disk.

Specify your target

When using beLow, you should focus on building a single target. If your scripts are able to build multiple targets, try to specify the one you are interesting it for the current project (you may create one project per target for instance).

E.g, using CMake, if you have multiple targets like myprogram and mylib in your CMakeLists.txt, do not run:

# Configure
cmake -B build .

# Clean
cmake --build build --target clean

# Build
cmake --build build

because some sources could be compiled multiple times a different way and so beLow will not know which of these compilations is actually in your target. Instead, if you are interested in myprogram as an output, use:

# Configure
cmake -B build .

# Clean
cmake --build build --target clean

# Build
cmake --build build --target myprogram

Working with compilation databases

In the general case, making your project compatible with beLow is equivalent to providing a compilation database file, or scripts to generate one, or leave beLow generate it.

In the case you provide or generate it, this compilation database must be named compile_commands.json and must be generated in the project. If multiple compile_commands.json files are present in the project, only the first one found is kept.

When setting up your project, if a compile_commands.json file is found, then it is automatically taken as source of truth about your compilation process.

If you directly provide a compile_commands.json file, as the elements in this file are in general absolute paths, you must choose to work in local mode. See Disk location-dependent build process section.

However, the best way to work with compilation databases is to provide location-independent scripts which are able to generate one wherever the project is located. This way, beLow can work in copies of your code, allowing copy mode to be used.

If you are able to provide a command generating a compilation database, it is recommended to inform it in Configure commands.

Generate your compile_commands.json file during project configuration

If you are using a build framework able to generate a compilation database, you should make it generate it there too. If you are able to generate a compilation database at that point, it's a win: beLow will work flawlessly.

In the next sections, you will see how to generate one with different specific frameworks.