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>

zmk 0.5.1                                         Oct 26, 2020                                           z.mk(5)