Compatibility specifics

Disk location-dependent build process

Either on Linux or Windows, your project build process might be disk location-dependent, i.e. 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 location-dependent.

In case your project is location-dependent, you have to use local mode when setting up your 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 the optimization process, you must not modify any of the source code or build scripts, otherwise beLow's behaviour would be unpredictable.

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 interested in for the current project (you may create one project per target, for instance).

For example, using CMake, if you have multiple targets like myprogram and mylib in your CMakeLists.txt, do not run the generic build command that builds all targets, because some sources could be compiled multiple times in different ways and beLow will not know which of these compilations corresponds to your target.

Instead of:

# Configure
cmake -B build .

# Clean
cmake --build build --target clean

# Build
cmake --build build

use the target-specific build command if you are interested in myprogram:

# 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 leaving beLow to generate it.

If 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, it is automatically taken as the 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 the Disk location-dependent build process section: https://docs.wedolow.com/below-technical-documentation/compatibility-guide/compatibility-specifics#disk-location-dependent-build-process

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 during project configuration

If you are using a build framework able to generate a compilation database, make it generate it during configuration. If you can generate a compilation database at that point, beLow will work more reliably.

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

PreviousCompatibility generalities NextCMake