OpenSolaris

OpenSolaris Freeware Consolidation
REQUIREMENTS FOR SFW USE OF SOFTWARE BUILD ENGINES
7 August 2007

1.  Summary

    The SFW consolidation is willing to support a variety of build
    approaches on a per-component basis.  This document includes
    requirements for the use of any high-level build tool, such as the
    pkgbuild utility.

2.  Discussion

    The OpenSolaris Freeware Consolidation (SFW) has historically
    allowed components to construct themselves in whatever manner is
    most appropriate to emit the binary and supporting artifacts needed.
    In practice, this policy has resulted primarily in components being
    built via one of two ways:

    - Makefile-driven build utilizing the component's build system

    - Makefile-driven build with a build crafted by the component's SFW
      maintainer

    These schemes are constructed around make(1)'s capabilities, plus
    the adoption of one or more conventions around Makefiles to state
    dependencies, invoke compilers and other tools, and to assemble
    packages.

    A higher level approach is to use a software build engine, which
    takes a more abstract build description and emits the output
    component's artifacts in the form of a package (or other assembly of
    binaries).  An example of a software build engine relevant to
    OpenSolaris is the pkgbuild utility [1], as used in the JDS
    Consolidation [2].

    The SFW C-team supports the utilization of software build engines in
    its Consolidation's build process.  The following requirements, in
    the form used for other OpenSolaris requirements documents [3], outline the
    implementation constraints on the use of such tools.

2.1  Requirements

    The intention of the requirements is that the SFW consolidation's
    build process be a predictable and convenient means of
    reproducibly producing software.  

2.1.1  Consolidation-wide requirements

    "Essential" requirements.

    E0.  Non-root build.

    SFW has historically permitted builds without special privilege.
    Requiring special privilege to build has been found to discourage
    participation in a consolidation's evolution.

    E1.  Reproducibility and source availability.

    As a consolidation publishing components used by other
    consolidations, SFW can get requests to redeliver these components.
    These requests can be satisfied if the consolidation can rebuild
    each component from a known set of sources.  That is, a method for
    guaranteeing that the source for the component is available over the
    delivery lifetime of the component.  (This requirement can be
    interpreted as a constraint on engine-driven automated source
    downloads.)

    E2.  Simultaneous builds on a single system

    Organizations contributing to SFW have had a set of supported build
    configurations, ranging from a single workstation to a shared build
    server.  In each of these cases, it is expected that the build
    system's installed configuration will not be changed as a result of
    the build process.

    This requirement implies that package modifying operations
    (installations, upgrades, and deletions) on the default path are
    disallowed without a waiver.  C-team approval will be required for a
    waiver of the "no package modifications"; any such operations
    executed during a build must be reversible.  (Since SFW builds will
    continue to take place on shared systems, such operations may also
    involve awareness of other consuming builds.)

    It is permissible to construct a special environment to permit
    simultaneous builds, as long as this construction can be carried out
    without manual intervention.  Such environments should be capable of
    being cleaned automatically by the build process.  Numerous options
    are available on OpenSolaris-based systems for the construction of
    isolated environments.

    E3.  Package auditing.

    It must be possible to audit, as a part of the build process, the
    changes made to a package between build invocations.  That is, a
    byproduct of the build should be an inventory of the changes in
    contents and metadata associated with a package, such that
    inventories of a package produced at distinct times can be compared.
    The primary purpose of auditing is to eliminate basic packaging
    errors, such as conflicting file membership or permissions.  Audited
    packages reduce C-team costs for interaction with distributions.

    E4.  Inter-component dependency.

    Build-time inter-component dependencies will be resolved via
    Makefiles and advertised installation.  That is, a component,
    regardless of its build method, must have a means of identifying its
    availability in a build-specific location if it is required by
    another component later in the build.  The build dependency will be
    handled via one or more Makefile statements.

    This requirement can be satisfied via use of a single proto area,
    but other approaches are permissible.  In principle, this
    requirement can be handled with a naming convention.

    "Conditional" requirements.

    C5.  Disconnected operation.

    It is strongly desired that it be possible to build the
    consolidation without network access.  Lack of disconnected
    operation will discourage potential contributors.

    There are no optional requirements in this section.

2.1.2  Consolidation-wide non-requirements

    Satisfaction of E0 and E2 via a consolidation specific setuid tool
    is permissible.

    With E3 "Package auditing" and E4 "Inter-component dependency"
    satisfied, it is not necessary for an isolated component to install
    in the proto area.

2.1.3  Per-component build requirements

    "Essential requirements"

    E6.  Documentation of native component build capability.

    For a small class of components, a "native" build is necessary, so
    that a component capable of running on the build system can
    construct other artifacts during the build process.  It is important
    for a software build engine to document clearly whether it is
    or is not capable of constructing native components, as well as the
    target components.

    There are no conditional or optional requirements in this section.

2.1.4  Software build engine requirements

    "Essential requirements"

    E7.  Open source

    Any software build engine used in SFW must be available under an
    OSI-approved license.

    "Conditional requirements"

    C8.  Engine-description versioning

    It is expected that a software build engine will have a statement of
    versioning such that build descriptions identify the minimal version
    of the engine required for their interpretation.

    C8.  OpenSolaris delivery

    It is strongly desired that any software build engine used in SFW
    ship in one of the OpenSolaris Consolidations.  It is not necessary
    that the engine be delivered by the SFW Consolidation.

    There no optional requirements in this section.

3.  References

[1] L. Peter, pkgbuild, http://pkgbuild.sf.net

[2] JDS Consolidation, http://opensolaris.org/os/project/jds/

[3] IEEE Std 830-1998, "IEEE Recommended Practice for Software Requirements Specifications", 1998.