Z Cross Build Environment

Introduction

The Z cross build environment is a tool for managing cross-compile environments. It comes with concurrent building, dependency tracking and other useful features.

Usage

Installation

ZCBE is available on PyPI:

pip install zcbe

Tutorial

0. Understanding concepts:

   • A "build" is an environment with multiple projects.
   • A "project" is a single package. They may depend on other projects.

1. The first step is to create a basic directory structure. ZCBE uses TOML as its configuration language.

   .
   |-- build.toml
   |-- mapping.toml
   |-- zcbe/
      |-- PROJECT.zcbe/
         |-- conf.toml
         |-- build.sh
   |-- ...
   

   The sources of projects can be anywhere. But generally it's suggested that you put them somewhere under the build's root directory.

2. Then we can populate the configurations.

   • build.toml: This file describes how to prepare environment. For example, the installation prefix and host triplets are set in this file. Go to templates/build.toml for an example.
   • mapping.toml: This file sets the working directory for each projects. This directory can be absolute or relative to build root. An example is at templates/mapping.toml.
   • zcbe/*.zcbe: Each project has a subdirectory here for holding their configuration, scripts and data.
   • zcbe/*.zcbe/conf.toml: This file contains the information about a project. The dependencies are specified here. An example is also available at templates/conf.toml.
   • zcbe/*.zcbe/build.sh: This is the build script.

3. Start building!

   • To build a single project and its dependencies, run zcbe <NAME>.
   • To build everything, pass -a.
   • To silence stdout, pass -s.
   • By default only one process is run at a time. To build concurrently, pass -j <N>.

   See CLI Usage Section for a complete list of options.

Contribution

For security-related issues, see SECURITY.md.

Contributions are very welcome on GitHub. Please try to follow PEP-8 coding guidelines and make sure test suites pass before submitting.

For new features and bug fixes, corresponding tests must be added.

The license is Apache-2.0.

Usage References and Specifications

CLI Usage

usage: zcbe [-h] [-w] [-W WARNING] [-B] [-C CHDIR] [-o FILE] [-e FILE]
            [-f FILE] [-p PREFIX] [-t TARGET_TRIPLET] [-m BUILD_NAME]
            [-j JOBS] [-a] [-s] [-n] [-u] [-y] [-H ABOUT]
            [PROJ ...]

The Z Cross Build Environment

positional arguments:
  PROJ                  List of projects to build

optional arguments:
  -h, --help            show this help message and exit
  -w                    Suppress all warnings
  -W WARNING            Modify warning behavior
  -B, --rebuild, --always-make, --always-build
                        Force build requested projects and dependencies
  -C CHDIR, --chdir CHDIR, --directory CHDIR
                        Change directory to
  -o FILE, --stdout-to FILE
                        Redirect stdout to FILE ('{n}' expands to the name of
                        the project)
  -e FILE, --stderr-to FILE
                        Redirect stderr to FILE ('{n}' expands to the name of
                        the project)
  -f FILE, --file FILE, --build-toml FILE
                        Read FILE as build.toml
  -p PREFIX, --prefix PREFIX, --override-prefix PREFIX
                        Override value for prefix
  -t TARGET_TRIPLET, --target-triplet TARGET_TRIPLET, --override-target TARGET_TRIPLET
                        Override value for target triplet
  -m BUILD_NAME, --build-name BUILD_NAME, --override-build-name BUILD_NAME
                        Override value for build name
  -j JOBS, --jobs JOBS  Number of maximum concurrent jobs
  -a, --all             Build all projects in mapping.toml
  -s, --silent          Silence make standard output(short for -o /dev/null)
  -n, --dry-run, --just-print, --recon
                        Don't actually run any commands
  -u, --show-unbuilt    List unbuilt projects and exit
  -y, --yes             Assume yes for all questions
  -H ABOUT, --about ABOUT
                        Help on a topic("topics" for a list of topics)

Environment Specification

In the build script, there are three environment variables set by ZCBE:

• ZCTOP: full path to the root of the build. That is, where zcbe is invoked or where the -C option points.
• ZCPREF: full path to the installation prefix.
• ZCHOST: GNU host triplet to cross compile for.

build.toml Specification

Tables:

• info: required.
  Keys:
  • build_name: name of this build environment. Required unless -m command-line option is set.
  • prefix: installation prefix. Required unless -p command-line option is set.
  • hostname: GNU triplet of the cross toolchain. Required unless -t command-line option is set.
  • mapping: Override path to mapping.toml. Optional. The default value is "mapping.toml".
• env: optional. Contains any number of environmental variables which will be set for all projects.
• deps: optional.
  Keys:
  • build: List of global build-time dependencies. Optional.

mapping.toml Specification

Tables:

• mapping: required. Contains any number of key-value mappings from the project name to the project path, either absolute or relative to build root.

conf.toml Specification

Tables:

• package: required.
  Keys:
  • name: name of this project. Required.
  • ver: version of this project. Required.
• env: optional. Contains any number of environmental variables which will be set for only this projects.
• deps: optional.
  Keys:
  • build: List of build-time dependencies. Optional.
  • req: List of dependencies on other projects. Optional.