fobos keys

A fobos file is the project's build configuration, in INI syntax: one section per mode (a build configuration), plus the special sections below. fobis reads ./fobos, or the file given with -f/--fobos. A mode key has the name of a command-line option without the leading -- and with underscores (--build-dir is build_dir); a key FoBiS does not know is ignored without a warning, so check the spelling against every mode key. A value runs to the end of the line: a ; or # after it is part of the value, and FoBiS warns about it.

How to write one, with examples: Building.

Special sections

Section	Purpose	Recipes
[modes]	The mode sections, modes = debug release	Building
template = SECTION	A mode inheriting the keys of another section	Building
[project]	Name, version, authors	Building
[features], [feature:NAME], [feature-group:NAME]	Named sets of flags switched on with --features	Building
[varsets], [varset:NAME]	Bundles of $variable values chosen with --varset	Building
[include]	Other fobos files read into this one	Building
[target.NAME], [example.NAME]	Programs built with their own keys	Building
[rule-NAME]	Commands run with fobis rule --execute NAME	Libraries and other build systems
[externals]	External libraries found with pkg-config or MPI wrappers	Libraries and other build systems
[dependencies]	Projects fetched from git, or taken from a directory	Dependencies
[test]	Defaults of fobis test	Testing
[coverage]	Defaults of fobis coverage	Testing
[lint]	Rules selected and ignored, the baseline	Code quality
[case:NAME], [verification], [assess:NAME], [bench:NAME], [gate]	Cases, references, assessments, benchmarks, the gate	Verifying results
[scheduler]	Slurm settings (also in the user configuration)	HPC and clusters
[scaffold], [ecosystem]	Shared boilerplate, the ecosystem's checks and release rule	Many projects

Every mode key

Generated from the settings of the commands that read a mode.

Any key can be qualified, key.QUALIFIER, and applies only when QUALIFIER is the mode's compiler (gnu, intel, intel_nextgen, g95, opencoarrays-gnu, pgi, ibm, nag, nvfortran, amd, lfortran, custom) or the operating system (linux, macos, windows, freebsd): cflags, lflags, preproc, c_cflags, c_preproc get the value appended (compiler, then system), any other key is replaced. An unknown qualifier, or one key replaced by both a compiler and a system key, is an error. See flags that differ by compiler or system.

Key	Read by	Description
ar	build, clean, doctests, rule	Archiver executable for static libraries [default: ar]
arflags	build, clean, doctests, rule	Archiver flags for static libraries [default: -rcs]
bin	install	Sub-directory for executables [default: bin/]
build_all	build, clean, doctests, rule	Build all sources parsed
build_dir	all	Directory containing built objects [default: ./]; given here, it wins over the mode's build_dir
build_profile	build	Named build profile: debug, release, asan, coverage
c_cflags	build, doctests, rule	Compile flags of the .c sources (default -c)
c_preproc	build, doctests, rule	Preprocessor flags of the .c sources
cc	build, doctests, rule	C compiler for the .c sources (default: the compiler family's, e.g. gcc)
cflags	build, clean, doctests, rule	Compile flags
cflags_heritage	build, clean, doctests, rule	Store cflags for heritage checking; re-compile all if they change
coarray	build, clean, doctests, rule	Use coarrays
colors	all	Activate colors in shell prints
compile_commands	build	Write the compilation database compile_commands.json in the build directory, linked from the project root (opt-in)
compiler	build, clean, doctests, rule	Compiler used (case insensitive, default gnu)
coverage	build, clean, doctests, rule	Instrument for coverage analysis
dependon	build, clean, doctests, rule	Interdependent external fobos files for interdependent building
deps_dir	install	Directory for cloning GitHub repositories [default: ~/.fobis/]
disable_recursive_search	build, clean, doctests, rule	Disable recursive search inside directories
doctests_preprocessor	doctests	Preprocessor used during doctests parsing (cpp|fpp)
exclude	build, clean, doctests, rule	Exclude files from the building process
exclude_dirs	build, clean, doctests, rule	Exclude directories from the building process
exclude_from_doctests	doctests	Exclude files from the doctests process
ext_libs	build, clean, doctests, rule	External libraries in compiler path
ext_vlibs	build, clean, doctests, rule	Volatile external libraries in compiler path
extensions	build, clean, doctests, rule	Extensions of parsed files
externals	build	External libraries to detect and link (mpi hdf5 ...): their compile and link flags are added
fc	build, clean, doctests, rule	Fortran compiler statement (for --compiler custom)
features	build	Comma- or space-separated feature flags to activate (defined in [features] section). Prefix with '-' to deactivate (e.g. 'prod,-coverage'). A mode may declare 'features = a b c' to set its own default set.
force_compile	all	Force to (re-)compile all
graph	all	Generate a dependencies graph via graphviz
help	build	One line describing the mode, shown by fobis build --lmodes
inc	build, clean, doctests, rule	Extensions for include files
include	all	Directories for searching included files
intrinsic_modules	build
jobs	all	Number of concurrent compilation jobs [default: 1]
keep_volatile_doctests	doctests	Keep the volatile doctests programs
launcher	run, test	Start the mode's programs through this command (mpirun -np {ranks}, gdb --args, valgrind); --launcher wins, [test] launcher applies when the mode has none
lflags	build, clean, doctests, rule	Link flags
lib	install	Sub-directory for libraries [default: lib/]
lib_dir	build, clean, doctests, rule	Directories searched for libraries
libs	build, clean, doctests, rule	External libraries with full paths
log	all	Activate log file creation
mklib	build, clean, doctests, rule	Build library instead of program (static|shared)
mod_dir	build, clean, doctests, rule	Directory containing .mod files [default: ./mod/]
modsw	build, clean, doctests, rule	Module search path switch (for --compiler custom)
mpi	build, clean, doctests, rule	Use MPI enabled version of compiler
no_auto_discover	build	Disable convention-based source directory auto-discovery
no_default_features	build	Disable the default feature set defined in [features] default
obj_dir	build, clean, doctests, rule	Directory containing compiled objects [default: ./obj/]
openmp	build, clean, doctests, rule	Use OpenMP pragmas
openmp_offload	build, clean, doctests, rule	Use OpenMP Offload pragmas
output	build, clean, doctests, rule	Output file name (used with --target)
pkgconfig	build	Write a pkg-config .pc file for the library this mode builds
pkgconfig_desc	build	Description in the .pc file
pkgconfig_name	build	Package name in the .pc file (default: [project] name)
pkgconfig_req	build	Requires: line of the .pc file
pkgconfig_req_priv	build	Requires.private: line of the .pc file
pkgconfig_url	build	URL in the .pc file
post_build	build	Rule(s) to execute after successful linking (defined in [rule-X] sections)
pre_build	build	Rule(s) to execute before compilation (defined in [rule-X] sections)
prefix	install	Prefix path where built objects are installed [default: ./]
preproc	build, doctests, rule	Preprocessor flags for the main compiler
preprocessor	build, doctests, rule	Preprocessor name for pre-processing sources (e.g. PreForM.py)
preprocessor_args	build, doctests, rule	Preprocessor-specific flags
preprocessor_dir	build, doctests, rule	Directory for preprocessed files
preprocessor_ext	build, doctests, rule	File extensions to preprocess
preprocessor_no_o	build, doctests, rule	Do not add -o in front of output in preprocessor command
profile	build, clean, doctests, rule	Instrument for profiling analysis
quiet	all	Less verbose output
ranlib	build, clean, doctests, rule	Ranlib executable; empty string to skip [default: ranlib]
src	build, clean, doctests, rule	Root-directory of source files [default: ./]
target	build, clean, doctests, rule	Specify a target file [default: all programs found]
template	build	A [template-NAME] section whose keys this mode inherits (its own keys win)
track_build	build, clean, doctests, rule	Store build info for the install command
varset	build	Apply one or more [varset:NAME] sections' $variable bindings to the active mode. Comma- or space-separated; later varsets override earlier ones. Use to swap parameterized values (cluster paths, GPU arch, ...) without duplicating modes.
verbose	all	Extremely verbose output for debugging
vlibs	build, clean, doctests, rule	Volatile external libraries with full paths