std.build

The build script's view of its build.

A package's build.lyr is an ordinary program that lyric5 runs before it compiles the package: it does things — writes modules into gen/, names C to compile, libraries to link and where to find them, and files to put beside the program — and defines nothing. What it asks of the toolchain goes back as directives, a line each, into the file the toolchain names; what the build is comes from the environment the toolchain sets.

Panics

Every function of this module panics outside a build script, where the toolchain's environment is not set, and where a directive cannot be written.

Examples

Compiles; not run here

import std.build;

build.cLibrary("fast").sources("native/fast.c").define("LEVEL", "2").flags("-O3").compile();
build.linkLib("m");
if (build.target().os == .MacOS) {
    build.linkFramework("Accelerate");
}
build.rerunIfChanged("native/fast.c");

A library from an SDK outside the package — SDL3 on Windows, its directory in SDL3_DIR — is linked from where the SDK lies, and its DLL goes beside the program:

Compiles; not run here

import std.build;
import std.os;

build.rerunIfEnvChanged("SDL3_DIR");
if (let sdk = os.env("SDL3_DIR")) {
    build.linkSearch(f"{sdk}/x86_64-w64-mingw32/lib");
    build.linkLib("SDL3");
    build.besideBinary(f"{sdk}/x86_64-w64-mingw32/bin/SDL3.dll");
} else {
    build.warn("set SDL3_DIR to the SDL3 SDK");
}

Types

BuildTarget struct — What a package is built for: its triple, such as x86_64-linux-gnu, its system and its machine as the prelude names them, and whether it is the machine the script runs on.

CLibrary class — A C library a build script compiles with the program (see cLibrary).

Functions

pub fn target(): BuildTarget

Returns the target the package is built for: build.target().os == .Windows.

The script itself runs on the host; isHost says whether the build is for it too.

pub fn profile(): string

Returns the profile the package is built in: debug, release, or one of the manifest's.

pub fn outDir(): string

Returns the path of the package's out/, for what the script keeps between its runs.

pub fn genDir(): string

Returns the path of the package's gen/.

A module the script writes there, gen/schema.lyr, is the package's module <package>.gen.schema. The toolchain makes the directory before the script runs.

pub fn rerunIfChanged(paths: string...): void

Asks the toolchain to run the script again when one of these files has changed.

The paths are relative to the package's root. While none of them changes, the toolchain keeps what the last run left. A script that names no file runs again where it changed itself.

pub fn rerunIfEnvChanged(names: string...): void

Asks the toolchain to run the script again when one of these environment variables has another value than in the script's last run, or is set where it was not, or not where it was.

A script that reads where a library lies from the environment names the variable here: else a changed value keeps what the last run asked.

pub fn linkLib(name: string): void

Links the C library name into the program: linkLib("m") is -lm.

pub fn linkSearch(dir: string): void

Adds a directory the link searches for the libraries of linkLib and of [native], before the linker's own: linkSearch("C:/Libs/SDL3/x86_64-w64-mingw32/lib") is -L with it.

The path is relative to the package's root, or absolute. The directory is never written into the binary: a shared library found there is found again when the program starts where the system looks, or beside the program — name it with besideBinary. For a Windows target a MinGW SDK's import library libX.dll.a is found as well.

pub fn besideBinary(paths: string...): void

Puts files beside every binary the build makes of the program — of build, run, test and bench, and a library --lib makes — when it has linked it: a shared library the program loads when it starts, most of all. Such a binary searches its own directory for shared libraries first. A file is copied only where the bytes beside the binary differ.

The paths are relative to the package's root, or absolute. A file that is not there when the script has ended, and two files of one name, stop the build (LYR-BLD0006).

pub fn linkArchive(path: string): void

Links a prebuilt static library by its path, as [native]'s archives does: a path of the package, or of a source tree (@name/…).

pub fn linkFramework(name: string): void

Links the macOS framework name, as [native.macos]'s frameworks does: -framework Cocoa.

A framework comes from the macOS SDK: a build for macOS from another system stops (LYR-BLD0004).

pub fn pkgConfig(name: string): void

Links a library of the system as pkg-config knows it, as [native]'s pkgConfig does: its include directories and definitions go to the package's C sources, the rest to the link.

The system is the host's: a build for another target stops (LYR-BLD0004).

pub fn vendorDir(name: string): string

Returns the directory of the package's source tree name ([native.vendor]), fetched where it is not yet.

The tree is read when the script asks for it: the script stops, the build fetches the tree, and the script runs again from its start with the tree there — so a script that asks for a tree asks before it does anything it would not do twice.

pub fn cLibrary(name: string): CLibrary

Returns a C library this script compiles with the program: its sources, its include directories, its definitions and its own flags, added by CLibrary.compile.

build.cLibrary("lua").sources("@lua/src/*.c").include("@lua/src").define("LUA_USE_POSIX").compile();

pub fn cEnv(): (string, string)[]

Returns the environment under which another build system — CMake, a configure script, make — compiles C for the build's target with the toolchain's C compiler: CC, AR and CFLAGS, to hand to a std.process.Command as its env.

pub fn warn(message: string): void

Emits a warning the toolchain shows with the build's diagnostics.