From b7f79aba81d2746182772ddc3ce686ef56dbe1aa Mon Sep 17 00:00:00 2001 From: adelsolt Date: Sat, 3 Oct 2026 02:15:34 +0100 Subject: [PATCH] doc: document the remaining project.conf variables and build modes The page described 15 variables, while about 44 names are read from the project files. This adds the ones verified against generated Makefiles: package, version, vendor, config and includes in the default section, script, soname and command in target sections, and the CXXFLAGS, ASFLAGS, GOFLAGS, JFLAGS and VFLAGS families alongside the ones already listed. It also documents the "command" target type, sections named after a source file or after an entry of includes or dist, and adds a section on build modes covering the "mode::" sections, the mode variable and the -M option. --- doc/project.conf.xml | 93 ++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 93 insertions(+) diff --git a/doc/project.conf.xml b/doc/project.conf.xml index 7319325..fd86be5 100644 --- a/doc/project.conf.xml +++ b/doc/project.conf.xml @@ -94,8 +94,25 @@ In the default section: + package (mandatory): name of the project + version (mandatory): version of the + project + vendor: name of the vendor, as reported in the + generated configuration files + config: comma-separated list of configuration files + to generate, holding the project name, version and vendor (possible + values: h for a C header, + sh for a shell script, + ent for XML entities) + mode: name of the build mode to apply by default + (see ) subdirs: subdirectories to look for too + includes: header files to install, as a + comma-separated list; their destination defaults to + $(INCLUDEDIR) and may be overridden with + an install variable in a section named after + the file cppflags_force: CPPFLAGS to force globally cppflags: optional global @@ -108,6 +125,26 @@ globally ldflags: optional global LDFLAGS + cxxflags_force: CXXFLAGS to force + globally + cxxflags: optional global + CXXFLAGS + asflags_force: ASFLAGS to force + globally + asflags: optional global + ASFLAGS + goflags_force: GOFLAGS to force + globally + goflags: optional global + GOFLAGS + jflags_force: JFLAGS to force + globally + jflags: optional global + JFLAGS + vflags_force: VFLAGS to force + globally + vflags: optional global + VFLAGS targets: targets to handle in the Makefile dist: additional files to include in a @@ -124,10 +161,31 @@ target cflags: additional CFLAGS for this target + cxxflags: additional CXXFLAGS for this + target + asflags: additional ASFLAGS for this + target + goflags: additional GOFLAGS for this + target + jflags: additional JFLAGS for this + target + vflags: additional VFLAGS for this + target ldflags: additional LDFLAGS for this target sources: source files to compile + script: for targets of type + script, the script generating the target; it is + run from the directory holding the Makefile, so a script shipped with + the project is referred to as + ./script.sh + soname: for targets of type + library or plugin, the + soname to assign to the shared object, overriding the default name + and version number + command: for targets of type + command, the command to run depends: a list of files (or other targets) that this target depends on install: the destination path for @@ -139,6 +197,38 @@ target by default + Sections may also be named after one of the source files listed in + a sources variable. Such a section applies to that file + only, and accepts the compiler flags relevant to its language, such as + cflags for a C source file, or + cxxflags for a C++ source file. + The install variable is likewise recognized in + sections named after a file listed in includes or + dist, and sets the destination path for that file. + + + Build modes + A build mode is a named set of variables, overriding those from the + default section. Modes allow a project to be built in more than one way, + for instance with debugging symbols during development and with + optimizations enabled for a release. + A mode is defined in a section named after it, prefixed with + "mode::", and may carry a title variable describing it. + Only the variables it defines are overridden; every other variable is + looked up in the default section as usual. + The mode to apply is given with the option to + configure + 1, or with a mode + variable in the default section. The command line takes precedence. If + neither is given, the default section is used on its own. + In the following example, the project is built with + "-O0 -g" by default, and with "-O2 -DNDEBUG" + when configured with "-M release": + cflags=-O0 -g + +[mode::release] +title=Release +cflags=-O2 -DNDEBUG @@ -151,6 +241,9 @@ binary: produces binary files, linked from every object file produced with their source files. + command: runs the command given in the + command variable; no source file is + expected. library: produces a static and a shared version of the target, linked from every object file produced with their source files, and respectively appending ".a" and ".so" extensions