Ubuntu Manpage: Configure — module providing build time configuration system

NAME

     Configure — module providing build time configuration system

SYNOPSIS

     include z.mk

     $(eval $(call ZMK.Import,Configure))

DESCRIPTION

     The Configure module provides two sides of the build-time configuration system. On one hand side it
     provides the familiar configure script, which can be used to set up various settings, prepare a directory
     for out-of-tree build, and integrate with project specific configuration settings. On the other hand it
     exposes the collected information as a set of variables, allowing the rest of the build system to modify
     its behavior accordingly.

TARGETS

     This module provides the following targets.

   configure
     This target generates the configuration script. The script is also automatically placed inside the source
     archive, so that the recipient does not need to have a local installation of zmk to build a project from
     source.

   config.$(NAME).mk
     This target is named after the configuration file created by the configure script. The rules are such, that
     if the configure script is newer than the configuration file, then the script is re-executed to generate a
     possibly updated configuration file.

   distclean
     This phony target removes the configuration file config.$(NAME).mk.  In maintainer mode, the configuration
     file is also removed.

VARIABLES

This module provides the following variables.

Configure.HostArchTriplet
This variable is set by the configure script when invoked with the --host=... option. It represents the
triplet describing the system which will eventually execute the compiled binaries. This is in contrast to
the system that is preforming the build.

Unlike in autoconf this variable is not set automatically. It is usually provided by Linux distribution
packaging which follows the up-to-date conventions on architecture triplet names. The triplet contains
three components, separated by dashes, the CPU architecture, Kernel name and Operating System name.
Popular values include x86_64-linux-gnu, aarch64-linux-gnu and riscv64-linux-gnu. Note that there is a lot
of variability in the architecture name and special cases related to the ARM architecture.

Configure.BuildArchTriplet
This variable is set by the configure script when invoked with the --build=... option. It represents the
triplet describing the system which is performing the build process. This is in contrast to the system that
will execute the built binaries.

When both Configure.HostArchTriplet and Configure.BuildArchTriplet are set and their values differ and when
CC and CXX are not overridden, then zmk automatically selects a cross-compiler from the GNU Compiler
Collection named $(Configure.HostArchTriplet)-gcc and $(Configure.HostArchTriplet)-g++ for the C and C++
compilers, respectively.

Configure.TargetArchTriplet
This variable is set by the configure script when invoked with the --target=... option. It represents the
triplet describing the system for which any generated code will be made. This variable is needed
infrequently, usually by tools such as compilers, to prepare them for creating binary code for a given
architecture.

Configure.SysRoot
This variable is set by the configure script when invoked with the --with-libtool-sysroot=... option. It
represents the explicit root directory of the file system where the compiler should look for libraries and
headers. It is typically used during cross-compilation, to isolate the build process from whatever headers
and libraries are installed natively on the system.

Configure.DependencyTracking
This variable is controlled by the configure script options --enable-dependency-tracking (default) and
--disable-dependency-tracking. When enabled it expands to yes and causes compatible compilers to generate
dependency information when compiling source files, that is subsequently used by Make to understand
relationship between all the source files and object files.

When performing pristine builds in a scratch environment that does not contain any old object files, this
setting can be disabled to speed up the build a little.

Configure.MaintainerMode
This variable is controlled by the configure script options --enable-maintainer-mode (default) and
--disable-maintainer-mode. When enabled it expands to yes and impacts the configure and config.$(NAME).mk
targets as described earlier.

Configure.SilentRules
This variable is controlled by the configure script options --enable-silent-rules and
--disable-silent-rules (default). When enabled it expands to yes and silences make rules defined by zmk.

Configure.StaticLibraries
This variable is controlled by the configure script options --enable-static (default) and --disable-static.
When static libraries are disabled the template Library.A becomes inactive.

Configure.DynamicLibraries
This variable is controlled by the configure script options --enable-dynamic (default) and
--disable-dynamic. When dynamic libraries are disabled the templates Library.So and Library.DyLib become
inactive.

Configure.ProgramPrefix
This variable is set by the configure script when invoked with the --program-prefix=... option.

The argument is the prefix added to installed name of all the programs built with the Program and the
Script templates.

Configure.ProgramSuffix
This variable is set by the configure script when invoked with the --program-suffix=... option.

The argument is the suffix added to installed name of all the programs built with the Program and the
Script templates.

Configure.ProgramTransformName
This variable is set by the configure script when invoked with the --program-transform-name=... option.

The argument is a sed expression used to transform the installed name of all the programs built with the
Program and the Script templates. The transformation affects the entire name, together with any prefix or
suffix defined by their options.

Configure.Configured
This variable expands to yes when the configure script was used to customize the build process. It can be
used to offer default behaviors that are appropriate to a given project, without interacting with
customizations performed by distribution packaging.

Configure.Options
This variable expands to the command line arguments passed to the configure script. It is used for
automatic re-configuration supported by maintainer mode. It can be also provided to the pre-processor to
embed the information about build-time configuration into the application or library binary.

FILES

   configure
     Automatically generated POSIX shell script mimicking the appearance and behavior of a similar file provided
     by GNU autoconf. This script should not be committed to version control systems. This script is added to
     release archives, as it allows one to compile a project from source without additionally depending on zmk
     libraries.

   config.$(NAME).mk
     Project specific configuration file generated by executing the configure script.

EXAMPLES

     The Configure module is automatically imported and is implicitly available when templates such as Program
     or Script are used. It does not require any additional input files. All customization is available directly
     from the project makefile.

HISTORY

     The Configure module first appeared in zmk 0.3. Starting with version 0.4 the configuration module provides
     the configure script and configuration persistence only to projects which define their Configure NAME .

BUGS

     Versions prior to 0.4 used a fixed name for the configuration file created by running the configure script,
     namely GNUmakefile.configured.mk.  This caused issues with make's PATH traversal when searching for include
     candidates that was resolved by using configuration files specific to a given project, called
     config.$(NAME).mk.

AUTHORS

     Zygmunt Krynicki <me@zygoon.pl>