Bootstrap and configure the package.
Usually one just calls build, which calls
The configuration of the package is influenced by command-line options, environment variables, and a build configuration file.
--disable-debug(default enabled): Enable/disable debug mode build. In debug mode, assertion checking is enabled for e.g. array bounds, and most compiler optimizations are disabled. This is recommended when developing code.
--disable-test(default disabled): Enable/disable test mode build. Test mode is similar to debug mode, but additionally tracks code coverage.
--disable-release(default disabled): Enable/disable release mode build. In release mode, all assertion checking is disabled and all compiler optimizations are enabled. This is recommended for running tested code when performance is critical. It offers substantial performance gains, usually several times faster than debug or test mode.
--disable-warnings(default enabled): Enable/disable compiler warnings.
--disable-notes(default disabled): Enable/disable compiler notes.
--disable-verbose(default enabled): Show compiler output on the terminal rather than in log files.
--prefix(default imputed): Installation prefix. Defaults to the same prefix used when installing the
--disable-openmp(default enabled): Enable/disable OpenMP. OpenMP is used for multi-threading. When running single-threaded, disabling OpenMP can have significant performance advantages, as it also disables the atomic operations used for thread synchronization.
--disable-static(default disabled): Enable/disable building of a static library.
--disable-shared(default enabled): Enable/disable building of a shared library.
Building a static library is not well tested, and at any rate should only
be tried for library packages, not end-user packages, which must be built
into a shared library in order to be dynamically loaded by
--arch(default empty, valid values
js): Target architecture for the build. If empty, then default settings are used. If
native, additional optimizations for the current architecture can be applied (e.g. SIMD instructions), if
dir, valid values
file): Set the compile unit when transpiling Birch to C++. This can significantly influence build times. If
unity, a single C++ source file is generated for all Birch source files. If
dir, a single C++ source file is generated for each directory of Birch source files. If
file, a C++ source file is generated for each Birch source file. Typically,
unitybuilds can provide the fastest build times from scratch but cannot be parallelized;
filebuilds can provide the fastest build times incrementally and can be parallelized, but for large projects can be very slow due to the overhead for each compile unit;
diroffers a good balance, and can be parallelized.
--jobs(default imputed): Number of parallel jobs when building. Defaults to twice the number of hardware threads.
The following environment variables influence the build:
release): Overrides the default build mode (which is otherwise
$BIRCH_PREFIX: Overrides the default installation prefix (which is otherwise the prefix used when installing the
$BIRCH_SHARE_PATH: Additional paths to search for shared files (those that typically install to
$BIRCH_INCLUDE_PATH: Additional paths to search for header files (those that typically install to
$BIRCH_LIBRARY_PATH: Additional path to search for libraries (those that typically install to
Birch will search for shared files in the following directories, in order,
$PREFIX is the prefix used when installing the
- paths given in
For header files:
- paths given in
.libsin the current directory,
- paths given in
Build configuration file
The build configuration file is a file named
birch.yml in the root
directory of the package. Alternative names that are supported include
The file is a YAML or JSON file with the following keys:
name: The name of the package.
version: The version of the package.
description: A short description of the package.
manifest: An object containing the following keys, listing the files to be included in the package.
source: A list of patterns identifying the Birch source files to be compiled. Each pattern is either the name of a file with a file extension of
.birch, or a glob pattern that expands to a list of such files. The glob patterns supported are as for C
man 3 glob).
data: A list of data files to be installed. These are typically config and input files provided by the package.
other: A list of other files to be distributed but not installed. These are typically meta files, such as
LICENSE, and the build configuration file itself.
require: An object containing the following keys, describing the dependencies of the package. These dependencies are checked by
package: A list of other Birch packages.
header: A list of external C/C++ header files.
library: A list of external libraries.
program: A list of external programs.