Build Makefile [build]
======================

A file named `build` directs the process of building and installing data files
to be provided by binary packages.  It must be a makefile, and it must be
executable by all users.

The first line of this file must name a **make**(1) interpreter in a magic
number sample as follows:

    #! /usr/bin/make -f

Any number of spaces and/or tabs may be used after the `#!` magic number and
before the `-f` argument.

The following targets are required:

  * `build`

    The `build` target should perform all the configuration and compilation
    needed to produce files for installation into binary packages.

    The `build` target should create a file named `build` in the build work area
    to prevent configuration and compilation from being performed multiple
    times.

    The `build` target must not do anything that might require superuser
    privilege.

  * `install`

    The `install` target should install data files into the data directories of
    binary packages (see $[sectlink][work-area] for information on these
    directories).

    The `install` target should depend on the `build` target.

    The `install` target shall be invoked as the superuser.

The required targets and their dependencies must not require interactive user
input.

Additional targets may exist in the `build` makefile.

Certain environment variables (see $[sectlink][env-vars]) shall be set when the
`build` makefile is executed.


Build Work Area [work-area]
===========================

When building packages, a new directory named `tmp` shall be created in the
source package directory.  In this directory, the package source code shall be
copied or unpacked into a directory called `src` shall be created.

After all expected binary packages have been built, the work area (`tmp` and its
children) shall be removed.


Environment Variables [env-vars]
================================

Certain environment variables shall be set to provide to the configuration
script and build makefile information about the package and the environments in
and for which binary packages are to be built.

The terms "build system" and "host system" below are used according to [the
convention set by GNU Autoconf][target-triplets].  The build system is the type
of system on which a package is built.  The host system is the type of system on
which a binary package is expected to be natively installed and used.

Package Variables [env-vars-pkg]
--------------------------------

The following environment variables shall be set to describe the source package:

  * `OPK_SOURCE`

    The source package name, as given in the most recent entry of the change
    log.  See $[sectlink][changelog] for more information on the source package
    name.

  * `OPK_SOURCE_VERSION`

    The source package version, as given in the most recent entry of the change
    log.  See $[sectlink][src-ver] for the syntax of source package version
    identifiers.

  * `OPK_SOURCE_VERSION_UPSTREAM`

  * `OPK_BINARY_VERSION`

  * `OPK_PACKAGES`

    A list of binary packages to be built.

    This may not include all packages for which the source package has metadata.
    The `Architecture` field of some packages may not match the host
    architecture for which packages are to be built.  Only
    architecture-dependent or architecture-independent packages may have been
    selected for building.

Build and Host System Variables [env-vars-sys]
----------------------------------------------

The following environment variables shall be set to describe the build system:

  * `OPK_BUILD_ARCH`

    The distribution architecture string of the build system.

  * `OPK_BUILD_ARCH_CPU`

    The CPU component of the distribution architecture string of the build
    system.

  * `OPK_BUILD_ARCH_KERNEL`

    The kernel component of the distribution architecture string of the build
    system.

  * `OPK_BUILD_ARCH_LIBS`

    The system libraries component of the distribution architecture string of
    the build system.

  * `OPK_BUILD_ARCH_GNU`

    The GNU system type of the build system.

  * `OPK_BUILD_PLAT`

    The application platform of the build system.

The following environment variables shall be set to describe the host system:

  * `OPK_HOST_ARCH`

    The distribution architecture string of the host system.

  * `OPK_HOST_ARCH_CPU`

    The CPU component of the distribution architecture string of the host
    system.

  * `OPK_HOST_ARCH_KERNEL`

    The kernel component of the distribution architecture string of the host
    system.

  * `OPK_HOST_ARCH_LIBS`

    The system libraries component of the distribution architecture string of
    the host system.

  * `OPK_HOST_ARCH_GNU`

    The GNU system type of the host system.

  * `OPK_HOST_PLAT`

    The application platform of the host system.

Toolchain Variables [env-vars-tools]
------------------------------------

The following environment variables shall be set to describe the toolchain:

  * `AR`

  * `AS`

  * `CC`

  * `CPP`

  * `CXX`

  * `LD`

  * `NM`

  * `OBJCOPY`

  * `OBJDUMP`

  * `RANLIB`

  * `READELF`

  * `SIZE`

  * `STRINGS`

  * `STRIP`

Note that this list of environment variables assumes the use of GNU Binutils,
GCC, and the ELF binary format.  Support for other toolchains may be specified
in a future version of this source package format.


[target-triplets]: https://www.gnu.org/software/autoconf/manual/html_node/Specifying-Target-Triplets.html