NAME

     z.mk — library for writing featureful Makefiles

SYNOPSIS

     # Define name and version of the project.
     Project.Name=foo
     Project.Version=1.2

     # Include the configuration file generated by the configure script, if one
     # exists. This enables a multitude of configuration options to be used.
     -include config.foo.mk

     # Assume the source code is in the current directory. This variable is always
     # defined by the generated configuration file, enabling support for out-of-tree
     # builds.
     ZMK.SrcDir ?= .

     # Include z.mk by searching include directories. If zmk is not globally
     # installed then ZMK.Version expands to nothing. As a last resort, assume that
     # zmk was bundled into the release archive.
     include z.mk
     ifeq ($(value ZMK.Version),)
     include $(ZMK.SrcDir)/z.mk
     endif

     # ZMK is now ready. Import additional modules or expand templates as necessary.

DESCRIPTION

     z.mk, also known as ZMK, is a library of GNU-make compatible makefiles providing an
     opinionated module and template system. The library comes with a collection of modules for
     common C/C++ software projects: compiling programs, creating libraries, installing
     development headers, data files, testing, etc. In addition the library offers specialized
     modules for constructing new modules that reuse specific behavior, such as participating in
     targets such as all, clean, install or uninstall.

   Naming Convention
     ZMK comes with a convention for development of Make libraries. This is an informal
     convention aimed at reducing friction in a untyped language devoid of any encapsulation
     system, such as that of Make itself.

     Almost all variables and functions use a naming convention prefixing all names with the name
     of the module followed by a dot. In addition, each name is either public, meant to be used
     by others and offering some API stability guarantees, or private, being a part of the
     implementation and not the interface one should rely on, even though nothing in make itself
     prevents this. Public names are capitalized, private names start with a lower case
     character.

     For example ZMK.Version is a public symbol containing the version of the ZMK library while
     ZMK.z.mk is a private symbol containing, at the time of this writing, the full path of the
     loaded z.mk library.

   Modules
     ZMK comes with a module system, which builds on the make include system. A module is a
     makefile installed to a zmk-specific directory. Typically each module defines some
     variables, one of which can be a template. A module which defines a template is simply
     called a template and is discussed below. To import a module use the following expression:

     $(eval $(call ZMK.Import,ModuleName))
     Modules encapsulate a piece of functionality or knowledge. For example, there is a module
     which handles well-known UNIX directories. Importing that module defines variables expanding
     to each of such directories. In addition, that module depends on a template handling
     creation of a directory, expanding that template many times, ensuring that make knows about
     all the directories, contains no duplicate rules and that conventions such as the DESTDIR
     variable are respected.

     Not all modules contain literal make rules. As another example, the Toolchain module knows
     how to detect and interrogate the compiler toolchain, offering information useful for other
     modules. For a full listing of modules built into zmk see MODULES below.

MODULES

     ZMK provides the following importable modules.

   AllClean
     This template interacts with the common targets all and clean.

   Configure
     This module provides a configuration facility and access to interactive configure script.

   Coverity
     This unstable module provides support for the Coverity static analyzer.

   Directories
     This module provides rules for configurable directories such as $(libdir) or $(bindir).

   Directory
     This template provides rules for creating a single directory. It's more involved than it
     seems.

   GitVersion
     This module allows augmenting project version with information from the Git version control
     system.

   Header
     This template provides targets for installation of public development headers.

   InstallUninstall
     This template provides rules for installing and uninstalling files.

   Library.A
     This template provides rules for preparing static libraries.

   Library.DyLib
     This template provides rules for preparing Mach-O dynamic libraries.

   Library.So
     This template provides rules for preparing ELF dynamic libraries.

   ManPage
     This template provides rules for checking and installing manual pages.

   OS
     This module provides information about the operating system.

   ObjectGroup
     This template provides rules for compiling a group of object files.

   PVS
     This module provides rules for working with the PVS static analyzer.

   Program.Test
     This template provides rules for compiling and executing test programs as well as for
     computing code coverage analysis.

   Program
     This template provides rules for compiling, installing and uninstalling executable programs.

   Script
     This template provides rules checking, installing and uninstalling executable scripts.

   Symlink
     This template provides rules for creating symbolic links.

   Tarball.Src
     This template provides rules for creating release archives. It offers utility targets such
     as distcheck, which performs a level of validation of the produced archive.

   Tarball
     This template provides rules for constructing arbitrary tarballs. It handles differences
     between GNU and BSD tar utilities.

   Toolchain
     This module provides information about the configured toolchain. ZMK offers support for gcc,
     clang and several less commonly used compilers.

TARGETS

     ZMK provides the following make goals.

   all
     This goal builds everything that can be compiled or otherwise built.

   clean
     This goal removes all the files that were built.

   coverage
     This goal provides information about test coverage.

   fmt
     This goal re-formats source code according to the selected standard.

   static-check
     This goal runs static check analysis programs.

   check
     This goal runs unit test programs.

   install
     This goal installs everything that is installable.

   uninstall
     This goal removes everything that is installable.

   dist
     This goal produces a release archive, or archives.

   distclean
     This goal is a superset of clean, removing some files that require a ZMK installation to
     recreate.

   distcheck
     This goal is a superset of dist which produces and tests the release archive.

VARIABLES

     ZMK provides several variables out of the box, even without importing any additional
     modules. Those are listed below.

   Project.Name
     Name of the software distribution project. This value is typically used for release archives
     but it shows up in several other places.

   Project.Version
     Version of the project. The value is sometimes interpolated into generated files. It is also
     used for release archives. It can be modified programmatically by the GitVersion module.

   NAME
     Compatibility alias for Project.Name

   VERSION
     Compatibility alias for Project.Version

   ZMK.Version
     Version of the included zmk library.

   ZMK.Path
     Path of the included zmk library. This is used to locate modules to import.

   ZMK.DistFiles
     List of files to place into release archives so that the recipient need not install zmk on
     their system to build the project from source.

   ZMK.SrcDir
     Location of the source tree, when building out-of-tree. This is rarely needed as out-of-tree
     builds are supported by all the modules bundled with zmk.

   ZMK.IsOutOfTreeBuild
     If building out-of-tree, a non-empty word indicating truth. This is rarely required but may
     be of use in specific circumstances. One such example is the makefile of zmk itself, where
     certain directories that are present in the version control system need to be created and
     removed when building out-of-tree.

   ZMK.OutOfTreeSourcePath
     When building out-of-tree, the full path, including the trailing slash, of the source
     directory. This may be a relative path.

   ZMK.ImportedModules
     The set of modules imported so far. This can be used for diagnostic purposes.  Please import
     modules by calling

   ZMK.BugFixes
     A list of bug identifiers representing the set of bugs that are resolved in zmk. Membership
     test can be used to conditionally enable hot-fixes that patch a part of ZMK in a given
     project, when upgrading zmk itself is not feasible.  ZMK.Import.

   VPATH
     When building out-of-tree, ZMK sets VPATH to the out-of-tree source path. This allows make
     implicit and built-in rules to find the source code without modification.

INTERNAL VARIABLES

   ZMK.z.mk
     Path of the entry point of the zmk library.

   ZMK.comma
     Variable expanding to a comma.

   ZMK.newline
     Variable expanding to a newline.

   ZMK.hash
     Variable expanding to a hash-or-pound symbol.

HISTORY

     The primary interface of zmk was first documented zmk 0.4

AUTHORS

     Zygmunt Krynicki <me@zygoon.pl>