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>