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>

zmk 0.5.1                                         Dec 28, 2020                              zmk.Configure.5(PRM)