CCCC Build System — builder API injected in –build mode. More...

Macros
#define	BuildRoot(ctx) __builtin_build_root(ctx)
	Absolute path of the directory the build was launched from.

#define	BuildOutDir(ctx) __builtin_build_out_dir(ctx)
	Output directory for build artifacts (default `build/`).

#define	BuildHost(ctx) __builtin_build_host(ctx)
	Host platform name (`"darwin"`, `"linux"`, ...).

#define	BuildVerbose(ctx) __builtin_build_verbose(ctx)
	Non-zero when verbose output was requested.

#define	Watch(ctx, path) __builtin_build_watch(ctx, path)
	Under `--watch`, also rebuild when this file (or directory) changes. The sources, `AddInput` files and headers of every target are watched automatically; use this for files the build reads in other ways.

#define	WatchGlob(ctx, pat) __builtin_build_watch_glob(ctx, pat)
	Under `--watch`, also rebuild when a file matching `pat` changes or appears.

#define	IgnoreWatch(ctx, pat) __builtin_build_ignore_watch(ctx, pat)
	Under `--watch`, never rebuild for paths matching `pat`.

#define	BuildWatching(ctx) __builtin_build_watching(ctx)
	Non-zero when the build runs under `--watch`.

#define	CcccPath(ctx) __builtin_build_cccc_path(ctx)
	Absolute path of the running `cccc` — for a `RunCustom` command that needs to invoke the same `cccc`.

#define	Executable(ctx, name) __builtin_build_executable(ctx, name)
	Create an executable target (output `bin/<name>`).

#define	StaticLib(ctx, name) __builtin_build_static_lib(ctx, name)
	Create a static-library target (output `lib/lib<name>`.a).

#define	DynamicLib(ctx, name) __builtin_build_dynamic_lib(ctx, name)
	Create a dynamic-library target (output `lib/lib<name>`.{so,dylib}).

#define	CcccExecutable(ctx, name) __builtin_build_cccc_executable(ctx, name)
	Create an executable compiled by the running `cccc` itself via `"cccc –compile=native"` — whole-program, no host `cc`, sources may contain [[cccc::comptime]]. Set `CCCC_NATIVE_CC` with `SetTargetEnv` to pick the host compiler that links the emitted C. `AddCFlag` / `SetProfile` / `SetTargetTriple` are rejected on this kind.

#define	CcccObject(ctx, name) __builtin_build_cccc_object(ctx, name)
	Create an object file (output `obj/<name>`.o) compiled by the running `cccc` via `"cccc –compile=object"`, for other targets to `LinkWith`. Link options are rejected on this kind.

#define	SetOutput(t, p) __builtin_build_set_output(t, p)
	Override the target's output path (relative to the out dir).

#define	TargetOutput(t) __builtin_build_target_output(t)
	On-disk output path for `t`.

#define	DeclareOutput(t, p) __builtin_build_declare_output(t, p)
	Record a file path a `RunCustom` target (only) produces.

#define	AddSource(t, p) __builtin_build_add_source(t, p)
	Add a C source file to the target.

#define	AddSourcesGlob(t, pat) __builtin_build_add_sources_glob(t, pat)
	Expand a glob pattern and add each match as a source file, immediately.

#define	AddSourcesGlobDeferred(t, pat) __builtin_build_add_sources_glob_deferred(t, pat)
	Like `AddSourcesGlob`, but expansion happens at build time, after `t's` dependencies have already been built.

#define	AddSourceStr(t, n, c) __builtin_build_add_source_str(t, n, c)
	Write `c` to `<out_dir>/gen/<n>` and add it as a source.

#define	AddInput(t, p) __builtin_build_add_input(t, p)
	Record a file path a target reads but does not list as a source.

#define	ExcludeSource(t, pat) __builtin_build_exclude_source(t, pat)
	Exclude sources matching `pat` from compilation.

#define	AddInclude(t, p) __builtin_build_add_include(t, p)
	Add an include search path (-I) to the target's compiles.

#define	AddSystemInclude(t, p) __builtin_build_add_system_include(t, p)
	Add a system include search path (`-isystem`) to the target's compiles.

#define	AddDefine(t, n, v) __builtin_build_add_define(t, n, v)
	Add a preprocessor define (-D).

#define	AddUndef(t, n) __builtin_build_add_undef(t, n)
	Add a preprocessor undefine (-U).

#define	AddCFlag(t, f) __builtin_build_add_cflag(t, f)
	Add a raw compiler flag (e.g. "-O2").

#define	AddLdFlag(t, f) __builtin_build_add_ldflag(t, f)
	Add a raw linker flag.

#define	SetTargetEnv(t, n, v) __builtin_build_set_target_env(t, n, v)
	Set an environment variable for `t's` compiler/linker child process only.

#define	LinkWith(t, dep) __builtin_build_link_with(t, dep)
	Declare that `t` links against (and is built after) `dep`.

#define	DependsOn(t, dep) __builtin_build_depends_on(t, dep)
	Ordering-only dependency: `t` is built after `dep` but does not add a linker flag.

#define	AddLib(t, n) __builtin_build_add_lib(t, n)
	Add a system library to link against (`-l<name>`).

#define	AddLibPath(t, p) __builtin_build_add_libpath(t, p)
	Add a library search path (-L<path>).

#define	GetEnv(ctx, name) __builtin_build_get_env(ctx, name)
	Return the value of environment variable `name`.

#define	CaptureCommand(ctx, cmd) __builtin_build_capture_command(ctx, cmd)
	Run `cmd` via `sh` `-c` and return its stdout.

#define	FileExists(ctx, path) __builtin_build_file_exists(ctx, path)
	Check whether a path exists.

#define	DirExists(ctx, path) __builtin_build_dir_exists(ctx, path)
	Check whether a path exists and is a directory.

#define	GlobFiles(ctx, pattern) __builtin_build_glob_files(ctx, pattern)
	Expand `pattern` and return the matching paths.

#define	ReadFile(ctx, path) __builtin_build_read_file(ctx, path)
	Read the file at `path` into a string.

#define	WriteFile(ctx, path, c) __builtin_build_write_file(ctx, path, c)
	Write `c` to `path`, creating parent directories as needed.

#define	SetCwd(ctx, path) __builtin_build_set_cwd(ctx, path)
	Change the process working directory to `path`.

#define	GetCwd(ctx) __builtin_build_get_cwd(ctx)
	Return the current process working directory.

#define	CopyFile(ctx, src, dst) __builtin_build_copy_file(ctx, src, dst)
	Copy file `src` to `dst`.

#define	MoveFile(ctx, src, dst) __builtin_build_move_file(ctx, src, dst)
	Move (rename) file `src` to `dst`.

#define	DeleteFile(ctx, path) __builtin_build_delete_file(ctx, path)
	Delete the file at `path` (`unlink`).

#define	MkDir(ctx, path) __builtin_build_mkdir(ctx, path)
	Create `path` and all intermediate directories (`mkdir` `-p` semantics).

#define	DeleteDir(ctx, path) __builtin_build_delete_dir(ctx, path)
	Recursively delete `path` and all contents (`rm` `-rf` semantics).

#define	HaveTool(ctx, name) __builtin_build_have_tool(ctx, name)
	Check whether a named tool is available.

#define	FindTool(ctx, name) __builtin_build_find_tool(ctx, name)
	Return the full path of a named tool.

#define	PkgConfig(t, pkg) __builtin_build_pkg_config(t, pkg)
	Run `pkg-config` to obtain compile and link flags for `pkg` and add them to `t`.

#define	RunCustom(ctx, name, cmd) __builtin_build_run_custom(ctx, name, cmd)
	Register a custom shell-command target that runs `cmd` when reached in the build graph.

#define	GetBuildOption(ctx, name) __builtin_build_get_build_option(ctx, name)
	Return the value of a `--build-option=key=value` option passed on the command line.

#define	HaveBuildOption(ctx, name) __builtin_build_have_build_option(ctx, name)
	Check whether a `--build-option` was passed on the command line.

#define	AddFramework(t, name) __builtin_build_add_framework(t, name)
	Add a macOS `-framework` `Name` linker flag.

#define	AddFrameworkPath(t, p) __builtin_build_add_framework_path(t, p)
	Add a macOS framework search path (`-F`, or `--iframework` for a `CcccExecutable` / `CcccObject` target).

#define	UseSystemHeaders(t) __builtin_build_use_system_headers(t)
	Compile a `CcccExecutable` / `CcccObject` target against the host's own system headers (`--use-system-headers`); an error on other kinds.

#define	BuildArgc(ctx) __builtin_build_argc(ctx)
	Number of positional arguments forwarded via `--` on the CLI.

#define	BuildArgv(ctx, i) __builtin_build_argv(ctx, i)
	Return the `i` -th positional argument forwarded via `--` on the CLI.

#define	SetInstallPrefix(ctx, path) __builtin_build_set_install_prefix(ctx, path)
	Override the install prefix for `InstallArtifact`.

#define	InstallArtifact(ctx, t) __builtin_build_install_artifact(ctx, t)
	Register `t` for installation when `--build-install` is active.

#define	BuildWantsInstall(ctx) __builtin_build_wants_install(ctx)
	Check whether install was requested.

#define	SetProfile(t, p) __builtin_build_set_profile(t, p)
	Set the build profile for target `t`, overriding any global `--build-profile` default.

#define	BuildProfile(ctx) __builtin_build_profile(ctx)
	Return the global build profile name.

#define	SetToolchain(t, cc) __builtin_build_set_toolchain(t, cc)
	Override the compiler binary for `t` (e.g. `"aarch64-linux-gnu-gcc"`).

#define	SetTargetTriple(t, triple) __builtin_build_set_target_triple(t, triple)
	Set a clang-style target triple for `t` (e.g. `"aarch64-linux-gnu"`).

#define	BuildTargetTriple(ctx) __builtin_build_target_triple(ctx)
	Return the global cross-compilation triple.

#define	BuildTargetCount(ctx) __builtin_build_target_count(ctx)
	Return the number of [[cccc::build_target]] factory functions declared in the current build script.

#define	BuildTargetName(ctx, i) __builtin_build_target_name(ctx, i)
	Return the name of the `i` -th [[cccc::build_target]] factory.

#define	Build(ctx, t) __builtin_build_run(ctx, t)
	Build `t` and its transitive dependencies.

#define	BuildAll(ctx) __builtin_build_run_all(ctx)
	Build every declared target in topological order.

#define	BuildDefault(ctx) __builtin_build_run_default(ctx)
	Build every declared target and print a summary.

Typedefs
typedef struct __cccc_Builder	Builder
	Opaque build context; passed to the entry and forwarded to macros.

typedef struct __cccc_BuildTarget	BuildTarget
	Opaque handle to a declared build target.

Functions
const char *	__builtin_build_root (Builder *ctx)
	Absolute path of the directory the build was launched from.

const char *	__builtin_build_out_dir (Builder *ctx)
	Output directory for build artifacts (default `build/`).

const char *	__builtin_build_host (Builder *ctx)
	Host platform name (`"darwin"`, `"linux"`, ...).

int	__builtin_build_verbose (Builder *ctx)
	Non-zero when verbose output was requested.

void	__builtin_build_watch (Builder ctx, const char path)
	Adds a file, or a directory (recursively), to the `--watch` set.

void	__builtin_build_watch_glob (Builder ctx, const char pattern)
	Adds an `fnmatch` glob to the `--watch` set.

void	__builtin_build_ignore_watch (Builder ctx, const char pattern)
	Drops `--watch` events for paths matching an `fnmatch` glob.

int	__builtin_build_watching (Builder *ctx)
	Non-zero under `--watch`.

const char *	__builtin_build_cccc_path (Builder *ctx)
	Absolute path of the running `cccc` executable.

BuildTarget *	__builtin_build_executable (Builder ctx, const char name)
	Create an executable target named `name` (output `bin/<name>`).

BuildTarget *	__builtin_build_static_lib (Builder ctx, const char name)
	Create a static-library target (output `lib/lib<name>`.a).

BuildTarget *	__builtin_build_dynamic_lib (Builder ctx, const char name)
	Create a dynamic-library target (output `lib/lib<name>`.{so,dylib}).

BuildTarget *	__builtin_build_cccc_executable (Builder ctx, const char name)
	Create an executable compiled by the running `cccc` itself (output `bin/<name>`).

BuildTarget *	__builtin_build_cccc_object (Builder ctx, const char name)
	Create an object file compiled by the running `cccc` itself (output `obj/<name>`.o).

void	__builtin_build_set_output (BuildTarget t, const char path)
	Override the target's output path (relative to the out dir).

const char *	__builtin_build_target_output (BuildTarget *t)
	On-disk output path for `t`.

void	__builtin_build_declare_output (BuildTarget t, const char path)
	Record a file path a `RunCustom` target (only) produces.

void	__builtin_build_add_input (BuildTarget t, const char path)
	Record a file path a `RunCustom` or `CcccExecutable` target reads.

void	__builtin_build_add_source (BuildTarget t, const char path)
	Add a C source file to the target.

void	__builtin_build_add_sources_glob (BuildTarget t, const char pattern)
	Expand a glob pattern relative to the build root and add each match as a source file, immediately.

void	__builtin_build_add_sources_glob_deferred (BuildTarget t, const char pattern)
	Like `AddSourcesGlob`, but expansion happens at build time, after `t's` dependencies have already been built.

void	__builtin_build_add_source_str (BuildTarget t, const char name, const char *content)
	Write `content` to `<out_dir>/gen/<name>` and add it as a source.

void	__builtin_build_exclude_source (BuildTarget t, const char pattern)
	Exclude sources matching `pattern` from compilation.

void	__builtin_build_add_include (BuildTarget t, const char path)
	Add an include search path (-I) to the target's compiles.

void	__builtin_build_add_system_include (BuildTarget t, const char path)
	Add a system include search path (`-isystem`) to the target's compiles.

void	__builtin_build_add_define (BuildTarget t, const char name, const char *value)
	Add a preprocessor define (-D).

void	__builtin_build_add_undef (BuildTarget t, const char name)
	Add a preprocessor undefine (-U).

void	__builtin_build_add_cflag (BuildTarget t, const char flag)
	Add a raw compiler flag (e.g. "-O2").

void	__builtin_build_add_ldflag (BuildTarget t, const char flag)
	Add a raw linker flag.

void	__builtin_build_set_target_env (BuildTarget t, const char name, const char *value)
	Set an environment variable for `t's` compiler/linker child process only (e.g. `AFL_USE_ASAN=1` for an afl-asan target).

void	__builtin_build_link_with (BuildTarget t, BuildTarget dep)
	Declare that `t` links against (and is built after) `dep`.

void	__builtin_build_depends_on (BuildTarget t, BuildTarget dep)
	Ordering-only dependency: `t` is built after `dep` but does not add a `-l<dep>` linker flag.

void	__builtin_build_add_lib (BuildTarget t, const char name)
	Add a system library to link against (`-l<name>`).

void	__builtin_build_add_libpath (BuildTarget t, const char path)
	Add a library search path (-L<path>).

const char *	__builtin_build_get_env (Builder ctx, const char name)
	Return the value of environment variable `name`.

const char *	__builtin_build_capture_command (Builder ctx, const char cmd)
	Run `cmd` via `sh` `-c` and return its stdout.

int	__builtin_build_file_exists (Builder ctx, const char path)
	Check whether a path exists.

int	__builtin_build_have_tool (Builder ctx, const char name)
	Check whether a named tool is available.

int	__builtin_build_pkg_config (BuildTarget t, const char pkg)
	Run `pkg-config` to obtain compile and link flags for `pkg` and add them to `t`.

BuildTarget *	__builtin_build_run_custom (Builder ctx, const char name, const char *cmd)
	Register a custom shell-command target named `name` that runs `cmd` when the target is reached in the build graph.

void	__builtin_build_set_profile (BuildTarget t, const char profile)
	Set the build profile for target `t`, overriding any global `--build-profile` default.

const char *	__builtin_build_profile (Builder *ctx)
	Return the global build profile name.

void	__builtin_build_set_toolchain (BuildTarget t, const char cc)
	Override the compiler binary for `t` (e.g. `"aarch64-linux-gnu-gcc"`).

void	__builtin_build_set_target_triple (BuildTarget t, const char triple)
	Set a clang-style target triple for `t` (e.g. `"aarch64-linux-gnu"`).

const char *	__builtin_build_target_triple (Builder *ctx)
	Return the global cross-compilation triple.

int	__builtin_build_target_count (Builder *ctx)
	Return the number of [[cccc::build_target]] factory functions declared in the current build script.

const char *	__builtin_build_target_name (Builder *ctx, int i)
	Return the name of the `i` -th [[cccc::build_target]] factory.

const char *	__builtin_build_find_tool (Builder ctx, const char name)
	Return the full path of a named tool.

const char *	__builtin_build_get_build_option (Builder ctx, const char name)
	Return the value of a `--build-option=key=value` option passed on the command line.

int	__builtin_build_have_build_option (Builder ctx, const char name)
	Check whether a `--build-option` was passed on the command line.

void	__builtin_build_add_framework (BuildTarget t, const char name)
	Add a macOS `-framework` `Name` linker flag.

void	__builtin_build_add_framework_path (BuildTarget t, const char path)
	Add a macOS framework search path (`-F`, or `--iframework` for a cccc-compiled target).

void	__builtin_build_use_system_headers (BuildTarget *t)
	Compile a cccc-compiled target against the host's own system headers (`--use-system-headers`).

int	__builtin_build_argc (Builder *ctx)
	Number of positional arguments forwarded via `--` on the CLI.

const char *	__builtin_build_argv (Builder *ctx, int i)
	Return the `i` -th positional argument forwarded via `--` on the CLI.

void	__builtin_build_set_install_prefix (Builder ctx, const char path)
	Override the install prefix for `InstallArtifact`.

void	__builtin_build_install_artifact (Builder ctx, BuildTarget t)
	Register `t` for installation when `--build-install` is active.

int	__builtin_build_wants_install (Builder *ctx)
	Check whether install was requested.

int	__builtin_build_dir_exists (Builder ctx, const char path)
	Check whether a path exists and is a directory.

const char **	__builtin_build_glob_files (Builder ctx, const char pattern)
	Expand `pattern` and return the matching paths.

const char *	__builtin_build_read_file (Builder ctx, const char path)
	Read the file at `path` into a string.

int	__builtin_build_write_file (Builder ctx, const char path, const char *content)
	Write `content` to `path`, creating parent directories as needed.

int	__builtin_build_set_cwd (Builder ctx, const char path)
	Change the process working directory to `path`.

const char *	__builtin_build_get_cwd (Builder *ctx)
	Return the current process working directory.

int	__builtin_build_copy_file (Builder ctx, const char src, const char *dst)
	Copy file `src` to `dst`.

int	__builtin_build_move_file (Builder ctx, const char src, const char *dst)
	Move (rename) file `src` to `dst`.

int	__builtin_build_delete_file (Builder ctx, const char path)
	Delete the file at `path` (`unlink`).

int	__builtin_build_mkdir (Builder ctx, const char path)
	Create `path` and all intermediate directories (`mkdir` `-p` semantics).

int	__builtin_build_delete_dir (Builder ctx, const char path)
	Recursively delete `path` and all contents (`rm` `-rf` semantics).

int	__builtin_build_run (Builder ctx, BuildTarget t)
	Build `t` and its transitive dependencies.

int	__builtin_build_run_all (Builder *ctx)
	Build every declared target in topological order.

int	__builtin_build_run_default (Builder *ctx)
	Build every declared target and print a summary.

Detailed Description

CCCC Build System — builder API injected in –build mode.

This header is automatically injected when CCCC is invoked with the –build flag and should not be included directly. It declares the opaque build types, the underlying __builtin_build_* FFI-callable functions, and PascalCase macro wrappers that forward an explicit build context parameter.

A build script is an ordinary .c file containing a build entry — a function tagged [[cccc::build]] (or named build_main). The entry receives the build context as its first parameter, uses it to create targets, wires their dependencies, and calls one of the Build* functions. The host-side runner then compiles and links the declared targets with the system toolchain (cc / ar / ld).

Usage

[[cccc::build]]
int build_main(Builder *ctx) {
    BuildTarget *core = StaticLib(ctx, "core");
    AddSource(core, "src/lib/sum.c");
    AddInclude(core, "include");
 
    BuildTarget *app = Executable(ctx, "app");
    AddSource(app, "src/main.c");
    LinkWith(app, core);
 
    return BuildDefault(ctx);
}

A non-zero return from the entry signals build failure.

Macro Definition Documentation

◆ AddCFlag

#define AddCFlag	(	t,
		f
	)	__builtin_build_add_cflag(t, f)

Add a raw compiler flag (e.g. "-O2").

Parameters

t	Target to modify.
f	Flag to append.

◆ AddDefine

#define AddDefine	(	t,
		n,
		v
	)	__builtin_build_add_define(t, n, v)

Add a preprocessor define (-D).

Parameters

t	Target to modify.
n	Macro name.
v	Macro value, or `NULL` for a bare define.

◆ AddFramework

#define AddFramework	(	t,
		name
	)	__builtin_build_add_framework(t, name)

Add a macOS -framework Name linker flag.

Parameters

t	Target to modify.
name	Framework name.

◆ AddFrameworkPath

#define AddFrameworkPath	(	t,
		p
	)	__builtin_build_add_framework_path(t, p)

Add a macOS framework search path (-F, or --iframework for a CcccExecutable / CcccObject target).

Parameters

t	Target to modify.
p	Framework search path.

◆ AddInclude

#define AddInclude	(	t,
		p
	)	__builtin_build_add_include(t, p)

Add an include search path (-I) to the target's compiles.

Parameters

t	Target to modify.
p	Include search path.

◆ AddInput

#define AddInput	(	t,
		p
	)	__builtin_build_add_input(t, p)

Record a file path a target reads but does not list as a source.

On a RunCustom target, with DeclareOutput, this drives the "up to date" skip check. On a CcccExecutable target it is the only way to make a header — or a comptime data file read via -D, which has no #include for a depfile to see — invalidate the target's cache; its contents fold into the cache key. On an Executable, StaticLib or DynamicLib target it names a file the host compiler's depfile never reports (such as an assembler .incbin); every object of the target recompiles when it changes.

Parameters

t	Target to record against.
p	Input path the target reads.

◆ AddLdFlag

#define AddLdFlag	(	t,
		f
	)	__builtin_build_add_ldflag(t, f)

Add a raw linker flag.

Parameters

t	Target to modify.
f	Flag to append.

◆ AddLib

#define AddLib	(	t,
		n
	)	__builtin_build_add_lib(t, n)

Add a system library to link against (-l<name>).

Parameters

t	Target to modify.
n	Library name, without the `lib` prefix or extension.

◆ AddLibPath

#define AddLibPath	(	t,
		p
	)	__builtin_build_add_libpath(t, p)

Add a library search path (-L<path>).

Parameters

t	Target to modify.
p	Library search path.

◆ AddSource

#define AddSource	(	t,
		p
	)	__builtin_build_add_source(t, p)

Add a C source file to the target.

Parameters

t	Target to add the source to.
p	Source file path, relative to the build root.

◆ AddSourcesGlob

#define AddSourcesGlob	(	t,
		pat
	)	__builtin_build_add_sources_glob(t, pat)

Expand a glob pattern and add each match as a source file, immediately.

Parameters

t	Target to add the matched sources to.
pat	Glob pattern, relative to the build root.

◆ AddSourcesGlobDeferred

#define AddSourcesGlobDeferred	(	t,
		pat
	)	__builtin_build_add_sources_glob_deferred(t, pat)

Like AddSourcesGlob, but expansion happens at build time, after t's dependencies have already been built.

Parameters

t	Target to add the matched sources to.
pat	Glob pattern, relative to the build root.

◆ AddSourceStr

#define AddSourceStr	(	t,
		n,
		c
	)	__builtin_build_add_source_str(t, n, c)

Write c to <out_dir>/gen/<n> and add it as a source.

Parameters

t	Target to add the generated source to.
n	Generated file name; must end in .c (or another compilable extension).
c	File contents to write.

◆ AddSystemInclude

#define AddSystemInclude	(	t,
		p
	)	__builtin_build_add_system_include(t, p)

Add a system include search path (-isystem) to the target's compiles.

Parameters

t	Target to modify.
p	System include search path.

◆ AddUndef

#define AddUndef	(	t,
		n
	)	__builtin_build_add_undef(t, n)

Add a preprocessor undefine (-U).

Parameters

t	Target to modify.
n	Macro name to undefine.

◆ Build

#define Build	(	ctx,
		t
	)	__builtin_build_run(ctx, t)

Build t and its transitive dependencies.

Parameters

ctx	Build context.
t	Target to build.

◆ BuildAll

#define BuildAll ( ctx ) __builtin_build_run_all(ctx)

Build every declared target in topological order.

Parameters

ctx	Build context.

◆ BuildArgc

#define BuildArgc ( ctx ) __builtin_build_argc(ctx)

Number of positional arguments forwarded via -- on the CLI.

Parameters

ctx	Build context.

◆ BuildArgv

#define BuildArgv	(	ctx,
		i
	)	__builtin_build_argv(ctx, i)

Return the i -th positional argument forwarded via -- on the CLI.

Parameters

ctx	Build context.
i	Zero-based argument index.

◆ BuildDefault

#define BuildDefault ( ctx ) __builtin_build_run_default(ctx)

Build every declared target and print a summary.

Parameters

ctx	Build context.

◆ BuildHost

#define BuildHost ( ctx ) __builtin_build_host(ctx)

Host platform name ("darwin", "linux", ...).

Parameters

ctx	Build context.

◆ BuildOutDir

#define BuildOutDir ( ctx ) __builtin_build_out_dir(ctx)

Output directory for build artifacts (default build/).

Parameters

ctx	Build context.

◆ BuildProfile

#define BuildProfile ( ctx ) __builtin_build_profile(ctx)

Return the global build profile name.

Parameters

ctx	Build context.

◆ BuildRoot

#define BuildRoot ( ctx ) __builtin_build_root(ctx)

Absolute path of the directory the build was launched from.

Parameters

ctx	Build context.

◆ BuildTargetCount

#define BuildTargetCount ( ctx ) __builtin_build_target_count(ctx)

Return the number of [[cccc::build_target]] factory functions declared in the current build script.

Parameters

ctx	Build context.

◆ BuildTargetName

#define BuildTargetName	(	ctx,
		i
	)	__builtin_build_target_name(ctx, i)

Return the name of the i -th [[cccc::build_target]] factory.

Parameters

ctx	Build context.
i	Zero-based factory index.

◆ BuildTargetTriple

#define BuildTargetTriple ( ctx ) __builtin_build_target_triple(ctx)

Return the global cross-compilation triple.

Parameters

ctx	Build context.

◆ BuildVerbose

#define BuildVerbose ( ctx ) __builtin_build_verbose(ctx)

Non-zero when verbose output was requested.

Parameters

ctx	Build context.

◆ BuildWantsInstall

#define BuildWantsInstall ( ctx ) __builtin_build_wants_install(ctx)

Check whether install was requested.

Parameters

ctx	Build context.

◆ BuildWatching

#define BuildWatching ( ctx ) __builtin_build_watching(ctx)

Non-zero when the build runs under --watch.

Parameters

ctx	Build context.

◆ CaptureCommand

#define CaptureCommand	(	ctx,
		cmd
	)	__builtin_build_capture_command(ctx, cmd)

Run cmd via sh -c and return its stdout.

Parameters

ctx	Build context.
cmd	Shell command to run.

◆ CcccExecutable

#define CcccExecutable	(	ctx,
		name
	)	__builtin_build_cccc_executable(ctx, name)

Create an executable compiled by the running cccc itself via "cccc –compile=native" — whole-program, no host cc, sources may contain [[cccc::comptime]]. Set CCCC_NATIVE_CC with SetTargetEnv to pick the host compiler that links the emitted C. AddCFlag / SetProfile / SetTargetTriple are rejected on this kind.

Parameters

ctx	Build context.
name	Target name.

◆ CcccObject

#define CcccObject	(	ctx,
		name
	)	__builtin_build_cccc_object(ctx, name)

Create an object file (output obj/<name>.o) compiled by the running cccc via "cccc –compile=object", for other targets to LinkWith. Link options are rejected on this kind.

Parameters

ctx	Build context.
name	Target name.

◆ CcccPath

#define CcccPath ( ctx ) __builtin_build_cccc_path(ctx)

Absolute path of the running cccc — for a RunCustom command that needs to invoke the same cccc.

Parameters

ctx	Build context.

◆ CopyFile

#define CopyFile	(	ctx,
		src,
		dst
	)	__builtin_build_copy_file(ctx, src, dst)

Copy file src to dst.

Parameters

ctx	Build context.
src	Source file path.
dst	Destination file path.

◆ DeclareOutput

#define DeclareOutput	(	t,
		p
	)	__builtin_build_declare_output(t, p)

Record a file path a RunCustom target (only) produces.

Parameters

t	Target to record against.
p	Output path, taken verbatim.

◆ DeleteDir

#define DeleteDir	(	ctx,
		path
	)	__builtin_build_delete_dir(ctx, path)

Recursively delete path and all contents (rm -rf semantics).

Parameters

ctx	Build context.
path	Directory path to delete.

◆ DeleteFile

#define DeleteFile	(	ctx,
		path
	)	__builtin_build_delete_file(ctx, path)

Delete the file at path (unlink).

Parameters

ctx	Build context.
path	File path to delete.

◆ DependsOn

#define DependsOn	(	t,
		dep
	)	__builtin_build_depends_on(t, dep)

Ordering-only dependency: t is built after dep but does not add a linker flag.

Parameters

t	Target that depends on `dep`.
dep	Target that must build first.

◆ DirExists

#define DirExists	(	ctx,
		path
	)	__builtin_build_dir_exists(ctx, path)

Check whether a path exists and is a directory.

Parameters

ctx	Build context.
path	Path to check.

◆ DynamicLib

#define DynamicLib	(	ctx,
		name
	)	__builtin_build_dynamic_lib(ctx, name)

Create a dynamic-library target (output lib/lib<name>.{so,dylib}).

Parameters

ctx	Build context.
name	Target name.

◆ ExcludeSource

#define ExcludeSource	(	t,
		pat
	)	__builtin_build_exclude_source(t, pat)

Exclude sources matching pat from compilation.

Parameters

t	Target to exclude the source from.
pat	Exact path or `fnmatch` glob to match against.

◆ Executable

#define Executable	(	ctx,
		name
	)	__builtin_build_executable(ctx, name)

Create an executable target (output bin/<name>).

Parameters

ctx	Build context.
name	Target name.

◆ FileExists

#define FileExists	(	ctx,
		path
	)	__builtin_build_file_exists(ctx, path)

Check whether a path exists.

Parameters

ctx	Build context.
path	Path to check (file, directory, or any other filesystem node).

◆ FindTool

#define FindTool	(	ctx,
		name
	)	__builtin_build_find_tool(ctx, name)

Return the full path of a named tool.

Parameters

ctx	Build context.
name	Tool name to look up in `PATH`.

◆ GetBuildOption

#define GetBuildOption	(	ctx,
		name
	)	__builtin_build_get_build_option(ctx, name)

Return the value of a --build-option=key=value option passed on the command line.

Parameters

ctx	Build context.
name	Option key.

◆ GetCwd

#define GetCwd ( ctx ) __builtin_build_get_cwd(ctx)

Return the current process working directory.

Parameters

ctx	Build context.

◆ GetEnv

#define GetEnv	(	ctx,
		name
	)	__builtin_build_get_env(ctx, name)

Return the value of environment variable name.

Parameters

ctx	Build context.
name	Environment variable name.

◆ GlobFiles

#define GlobFiles	(	ctx,
		pattern
	)	__builtin_build_glob_files(ctx, pattern)

Expand pattern and return the matching paths.

Parameters

ctx	Build context.
pattern	Glob pattern.

◆ HaveBuildOption

#define HaveBuildOption	(	ctx,
		name
	)	__builtin_build_have_build_option(ctx, name)

Check whether a --build-option was passed on the command line.

Parameters

ctx	Build context.
name	Option key.

◆ HaveTool

#define HaveTool	(	ctx,
		name
	)	__builtin_build_have_tool(ctx, name)

Check whether a named tool is available.

Parameters

ctx	Build context.
name	Tool name to look up in `PATH`.

◆ IgnoreWatch

#define IgnoreWatch	(	ctx,
		pat
	)	__builtin_build_ignore_watch(ctx, pat)

Under --watch, never rebuild for paths matching pat.

Parameters

ctx	Build context.
pat	`fnmatch` glob matched against the full path, the path from the working directory and the file name.

◆ InstallArtifact

#define InstallArtifact	(	ctx,
		t
	)	__builtin_build_install_artifact(ctx, t)

Register t for installation when --build-install is active.

Parameters

ctx	Build context.
t	Target to install.

◆ LinkWith

#define LinkWith	(	t,
		dep
	)	__builtin_build_link_with(t, dep)

Declare that t links against (and is built after) dep.

Parameters

t	Target that links against `dep`.
dep	Target being linked against.

◆ MkDir

#define MkDir	(	ctx,
		path
	)	__builtin_build_mkdir(ctx, path)

Create path and all intermediate directories (mkdir -p semantics).

Parameters

ctx	Build context.
path	Directory path to create.

◆ MoveFile

#define MoveFile	(	ctx,
		src,
		dst
	)	__builtin_build_move_file(ctx, src, dst)

Move (rename) file src to dst.

Parameters

ctx	Build context.
src	Source file path.
dst	Destination file path.

◆ PkgConfig

#define PkgConfig	(	t,
		pkg
	)	__builtin_build_pkg_config(t, pkg)

Run pkg-config to obtain compile and link flags for pkg and add them to t.

Parameters

t	Target to add the flags to.
pkg	Package name to query.

◆ ReadFile

#define ReadFile	(	ctx,
		path
	)	__builtin_build_read_file(ctx, path)

Read the file at path into a string.

Parameters

ctx	Build context.
path	File path to read.

◆ RunCustom

#define RunCustom	(	ctx,
		name,
		cmd
	)	__builtin_build_run_custom(ctx, name, cmd)

Register a custom shell-command target that runs cmd when reached in the build graph.

Parameters

ctx	Build context.
name	Target name.
cmd	Shell command to run.

◆ SetCwd

#define SetCwd	(	ctx,
		path
	)	__builtin_build_set_cwd(ctx, path)

Change the process working directory to path.

Parameters

ctx	Build context.
path	Directory to change into.

◆ SetInstallPrefix

#define SetInstallPrefix	(	ctx,
		path
	)	__builtin_build_set_install_prefix(ctx, path)

Override the install prefix for InstallArtifact.

Parameters

ctx	Build context.
path	Install prefix path.

◆ SetOutput

#define SetOutput	(	t,
		p
	)	__builtin_build_set_output(t, p)

Override the target's output path (relative to the out dir).

Parameters

t	Target to modify.
p	Output path.

◆ SetProfile

#define SetProfile	(	t,
		p
	)	__builtin_build_set_profile(t, p)

Set the build profile for target t, overriding any global --build-profile default.

Parameters

t	Target to modify.
p	Profile name: `"debug"`, `"release"`, `"relwithdebinfo"`, or `"minsizerel"`.

◆ SetTargetEnv

#define SetTargetEnv	(	t,
		n,
		v
	)	__builtin_build_set_target_env(t, n, v)

Set an environment variable for t's compiler/linker child process only.

Parameters

t	Target to modify.
n	Environment variable name.
v	Environment variable value.

◆ SetTargetTriple

#define SetTargetTriple	(	t,
		triple
	)	__builtin_build_set_target_triple(t, triple)

Set a clang-style target triple for t (e.g. "aarch64-linux-gnu").

Parameters

t	Target to modify.
triple	Target triple.

◆ SetToolchain

#define SetToolchain	(	t,
		cc
	)	__builtin_build_set_toolchain(t, cc)

Override the compiler binary for t (e.g. "aarch64-linux-gnu-gcc").

Parameters

t	Target to modify.
cc	Compiler binary name or path.

◆ StaticLib

#define StaticLib	(	ctx,
		name
	)	__builtin_build_static_lib(ctx, name)

Create a static-library target (output lib/lib<name>.a).

Parameters

ctx	Build context.
name	Target name.

◆ TargetOutput

#define TargetOutput ( t ) __builtin_build_target_output(t)

On-disk output path for t.

Parameters

t	Target to query.

◆ UseSystemHeaders

#define UseSystemHeaders ( t ) __builtin_build_use_system_headers(t)

Compile a CcccExecutable / CcccObject target against the host's own system headers (--use-system-headers); an error on other kinds.

Parameters

t	Target to modify.

◆ Watch

#define Watch	(	ctx,
		path
	)	__builtin_build_watch(ctx, path)

Under --watch, also rebuild when this file (or directory) changes. The sources, AddInput files and headers of every target are watched automatically; use this for files the build reads in other ways.

Parameters

ctx	Build context.
path	File or directory.

◆ WatchGlob

#define WatchGlob	(	ctx,
		pat
	)	__builtin_build_watch_glob(ctx, pat)

Under --watch, also rebuild when a file matching pat changes or appears.

Parameters

ctx	Build context.
pat	`fnmatch` glob, for example every .png under `assets`.

◆ WriteFile

#define WriteFile	(	ctx,
		path,
		c
	)	__builtin_build_write_file(ctx, path, c)

Write c to path, creating parent directories as needed.

Parameters

ctx	Build context.
path	File path to write.
c	Content to write.

Typedef Documentation

◆ Builder

typedef struct __cccc_Builder Builder

Opaque build context; passed to the entry and forwarded to macros.

◆ BuildTarget

typedef struct __cccc_BuildTarget BuildTarget

Opaque handle to a declared build target.

Function Documentation

◆ __builtin_build_add_cflag()

void __builtin_build_add_cflag	(	BuildTarget *	t,
		const char *	flag
	)

Add a raw compiler flag (e.g. "-O2").

Parameters

t	Target to modify.
flag	Flag to append.

◆ __builtin_build_add_define()

void __builtin_build_add_define	(	BuildTarget *	t,
		const char *	name,
		const char *	value
	)

Add a preprocessor define (-D).

Parameters

t	Target to modify.
name	Macro name.
value	Macro value, or `NULL` for a bare define.

◆ __builtin_build_add_framework()

void __builtin_build_add_framework	(	BuildTarget *	t,
		const char *	name
	)

Add a macOS -framework Name linker flag.

Shorthand for AddLdFlag(t, "-framework Name").

Parameters

t	Target to modify.
name	Framework name.

◆ __builtin_build_add_framework_path()

void __builtin_build_add_framework_path	(	BuildTarget *	t,
		const char *	path
	)

Add a macOS framework search path (-F, or --iframework for a cccc-compiled target).

Parameters

t	Target to modify.
path	Framework search path.

◆ __builtin_build_add_include()

void __builtin_build_add_include	(	BuildTarget *	t,
		const char *	path
	)

Add an include search path (-I) to the target's compiles.

Parameters

t	Target to modify.
path	Include search path.

◆ __builtin_build_add_input()

void __builtin_build_add_input	(	BuildTarget *	t,
		const char *	path
	)

Record a file path a RunCustom or CcccExecutable target reads.

On a RunCustom target, combined with DeclareOutput, gives build_target() a real "up to date" skip check: if the target has at least one declared input and one declared output, and every output exists and is at least as new as every input, the command is skipped. A target with no AddInput calls always runs, as before. On a CcccExecutable target the declared paths' contents fold into the cache key — the only way to make a header, or a comptime data file read via -D, invalidate the target (there is no depfile under --compile=native). No-op with a diagnostic on any other target kind.

Parameters

t	Target to record against (`RunCustom` or `CcccExecutable`).
path	Input path the target reads.

◆ __builtin_build_add_ldflag()

void __builtin_build_add_ldflag	(	BuildTarget *	t,
		const char *	flag
	)

Add a raw linker flag.

Parameters

t	Target to modify.
flag	Flag to append.

◆ __builtin_build_add_lib()

void __builtin_build_add_lib	(	BuildTarget *	t,
		const char *	name
	)

Add a system library to link against (-l<name>).

Parameters

t	Target to modify.
name	Library name, without the `lib` prefix or extension.

◆ __builtin_build_add_libpath()

void __builtin_build_add_libpath	(	BuildTarget *	t,
		const char *	path
	)

Add a library search path (-L<path>).

Parameters

t	Target to modify.
path	Library search path.

◆ __builtin_build_add_source()

void __builtin_build_add_source	(	BuildTarget *	t,
		const char *	path
	)

Add a C source file to the target.

Parameters

t	Target to add the source to.
path	Source file path, relative to the build root.

◆ __builtin_build_add_source_str()

void __builtin_build_add_source_str	(	BuildTarget *	t,
		const char *	name,
		const char *	content
	)

Write content to <out_dir>/gen/<name> and add it as a source.

Parameters

t	Target to add the generated source to.
name	Generated file name; must end in .c (or another compilable extension).
content	File contents to write.

◆ __builtin_build_add_sources_glob()

void __builtin_build_add_sources_glob	(	BuildTarget *	t,
		const char *	pattern
	)

Expand a glob pattern relative to the build root and add each match as a source file, immediately.

Requires POSIX glob(3). Matches are returned in sorted order.

Parameters

t	Target to add the matched sources to.
pattern	Glob pattern, relative to the build root.

◆ __builtin_build_add_sources_glob_deferred()

void __builtin_build_add_sources_glob_deferred	(	BuildTarget *	t,
		const char *	pattern
	)

Like AddSourcesGlob, but expansion happens at build time, after t's dependencies have already been built.

Lets the pattern match a file a RunCustom codegen dependency creates during this same build. AddSourcesGlob expands immediately and cannot see such files.

Parameters

t	Target to add the matched sources to.
pattern	Glob pattern, relative to the build root.

◆ __builtin_build_add_system_include()

void __builtin_build_add_system_include	(	BuildTarget *	t,
		const char *	path
	)

Add a system include search path (-isystem) to the target's compiles.

Parameters

t	Target to modify.
path	System include search path.

◆ __builtin_build_add_undef()

void __builtin_build_add_undef	(	BuildTarget *	t,
		const char *	name
	)

Add a preprocessor undefine (-U).

Parameters

t	Target to modify.
name	Macro name to undefine.

◆ __builtin_build_argc()

int __builtin_build_argc ( Builder * ctx )

Number of positional arguments forwarded via -- on the CLI.

Parameters

ctx	Build context.

Returns: The argument count, or 0 if no -- separator was given.

◆ __builtin_build_argv()

const char * __builtin_build_argv	(	Builder *	ctx,
		int	i
	)

Return the i -th positional argument forwarded via -- on the CLI.

Parameters

ctx	Build context.
i	Zero-based argument index.

Returns: The argument string, or NULL if i is out of range.

◆ __builtin_build_capture_command()

const char * __builtin_build_capture_command	(	Builder *	ctx,
		const char *	cmd
	)

Run cmd via sh -c and return its stdout.

Trailing whitespace is stripped. The returned pointer is valid until the build entry returns.

Parameters

ctx	Build context.
cmd	Shell command to run.

Returns: Stdout as a NUL-terminated string, or NULL on failure or on non-POSIX platforms.

◆ __builtin_build_cccc_executable()

BuildTarget * __builtin_build_cccc_executable	(	Builder *	ctx,
		const char *	name
	)

Create an executable compiled by the running cccc itself (output bin/<name>).

The target is built with a single "cccc –compile=native \<sources...\> -o bin/\<name\>" invocation — whole-program, no per-source object files, no host cc. Its sources may contain [[cccc::comptime]]. Set CCCC_NATIVE_CC via SetTargetEnv to choose the host compiler that links the emitted C (e.g. cosmocc for a portable binary).

Only AddSource / AddInclude / AddDefine / AddUndef / AddLib / AddLibPath / AddInput / LinkWith / DependsOn / SetOutput / SetTargetEnv apply, and AddLdFlag / AddFramework are sent as --link-arg. AddCFlag / SetProfile / SetTargetTriple are rejected: cccc --compile=native takes only -I/-D/-U/-L/-l/--std= and has no host-cc flag pass-through.

Parameters

ctx	Build context.
name	Target name.

Returns: The new target handle.

◆ __builtin_build_cccc_object()

BuildTarget * __builtin_build_cccc_object	(	Builder *	ctx,
		const char *	name
	)

Create an object file compiled by the running cccc itself (output obj/<name>.o).

The target is built with a single "cccc –compile=object \<sources...\> -o obj/\<name\>.o" invocation: no link step. Other targets consume the object with LinkWith (an Executable, DynamicLib or StaticLib links or archives it; a CcccExecutable passes it as --link-arg), and rebuild when it changes.

Only AddSource / AddInclude / AddDefine / AddUndef / AddInput / DependsOn / SetOutput / SetTargetEnv apply. Link options (AddLdFlag / AddFramework / AddLib / AddLibPath / LinkWith / PkgConfig) and AddCFlag / SetProfile / SetTargetTriple are rejected. It cannot be installed with InstallArtifact.

Parameters

ctx	Build context.
name	Target name.

Returns: The new target handle.

◆ __builtin_build_cccc_path()

const char * __builtin_build_cccc_path ( Builder * ctx )

Absolute path of the running cccc executable.

A CcccExecutable target uses this as its compiler automatically; this accessor exposes it to a RunCustom command that wants to invoke the same cccc (e.g. for -c=generated or -E).

Parameters

ctx	Build context.

Returns: The cccc path, as an interned string ("" if unresolved).

◆ __builtin_build_copy_file()

int __builtin_build_copy_file	(	Builder *	ctx,
		const char *	src,
		const char *	dst
	)

Copy file src to dst.

Parameters

ctx	Build context.
src	Source file path.
dst	Destination file path.

Returns: 0 on success, -1 on error.

◆ __builtin_build_declare_output()

void __builtin_build_declare_output	(	BuildTarget *	t,
		const char *	path
	)

Record a file path a RunCustom target (only) produces.

Taken verbatim, not joined onto out_dir, so TargetOutput() can resolve it, the dependency is documented for downstream consumers, and (combined with AddInput) build_target() can decide the step is already up to date. May be called more than once; each call appends rather than replacing, and TargetOutput() returns the first. On its own (no AddInput calls) this is invalidation metadata only — a RunCustom step with no declared inputs still runs every build regardless of whether path already exists. No-op with a diagnostic on non-RunCustom targets.

Parameters

t	Target to record against (must be a `RunCustom` target).
path	Output path, taken verbatim.

◆ __builtin_build_delete_dir()

int __builtin_build_delete_dir	(	Builder *	ctx,
		const char *	path
	)

Recursively delete path and all contents (rm -rf semantics).

Does not follow symlinks out of the tree.

Parameters

ctx	Build context.
path	Directory path to delete.

Returns: 0 on success, -1 on error.

◆ __builtin_build_delete_file()

int __builtin_build_delete_file	(	Builder *	ctx,
		const char *	path
	)

Delete the file at path (unlink).

Parameters

ctx	Build context.
path	File path to delete.

Returns: 0 on success, -1 on error.

◆ __builtin_build_depends_on()

void __builtin_build_depends_on	(	BuildTarget *	t,
		BuildTarget *	dep
	)

Ordering-only dependency: t is built after dep but does not add a -l<dep> linker flag.

Use this to order a RunCustom codegen step before its consumer.

Parameters

t	Target that depends on `dep`.
dep	Target that must build first.

◆ __builtin_build_dir_exists()

int __builtin_build_dir_exists	(	Builder *	ctx,
		const char *	path
	)

Check whether a path exists and is a directory.

Parameters

ctx	Build context.
path	Path to check.

Returns: 1 if path exists and is a directory, 0 otherwise.

◆ __builtin_build_dynamic_lib()

BuildTarget * __builtin_build_dynamic_lib	(	Builder *	ctx,
		const char *	name
	)

Create a dynamic-library target (output lib/lib<name>.{so,dylib}).

Parameters

ctx	Build context.
name	Target name.

Returns: The new target handle.

◆ __builtin_build_exclude_source()

void __builtin_build_exclude_source	(	BuildTarget *	t,
		const char *	pattern
	)

Exclude sources matching pattern from compilation.

Applies after any AddSource / AddSourcesGlob calls, regardless of call order.

Parameters

t	Target to exclude the source from.
pattern	Exact path or `fnmatch` glob to match against.

◆ __builtin_build_executable()

BuildTarget * __builtin_build_executable	(	Builder *	ctx,
		const char *	name
	)

Create an executable target named name (output bin/<name>).

Parameters

ctx	Build context.
name	Target name.

Returns: The new target handle.

◆ __builtin_build_file_exists()

int __builtin_build_file_exists	(	Builder *	ctx,
		const char *	path
	)

Check whether a path exists.

Parameters

ctx	Build context.
path	Path to check (file, directory, or any other filesystem node).

Returns: 1 if path exists, 0 otherwise.

◆ __builtin_build_find_tool()

const char * __builtin_build_find_tool	(	Builder *	ctx,
		const char *	name
	)

Return the full path of a named tool.

The returned pointer is valid until the build entry returns.

Parameters

ctx	Build context.
name	Tool name to look up in `PATH`.

Returns: The tool's full path, or NULL if it is not executable in PATH or not permitted by the tool allowlist.

◆ __builtin_build_get_build_option()

const char * __builtin_build_get_build_option	(	Builder *	ctx,
		const char *	name
	)

Return the value of a --build-option=key=value option passed on the command line.

Parameters

ctx	Build context.
name	Option key.

Returns: The option's value, or NULL if name was not given.

◆ __builtin_build_get_cwd()

const char * __builtin_build_get_cwd ( Builder * ctx )

Return the current process working directory.

The pointer is valid until the build entry returns.

Parameters

ctx	Build context.

Returns: The current working directory as an interned string, or NULL on error.

◆ __builtin_build_get_env()

const char * __builtin_build_get_env	(	Builder *	ctx,
		const char *	name
	)

Return the value of environment variable name.

Parameters

ctx	Build context.
name	Environment variable name.

Returns: The variable's value, or NULL if unset.

◆ __builtin_build_glob_files()

const char ** __builtin_build_glob_files	(	Builder *	ctx,
		const char *	pattern
	)

Expand pattern and return the matching paths.

Uses POSIX glob(3). The array and its strings are valid until the build entry returns.

Parameters

ctx	Build context.
pattern	Glob pattern.

Returns: A NULL-terminated array of matching paths, or NULL on no match or non-POSIX platforms.

◆ __builtin_build_have_build_option()

int __builtin_build_have_build_option	(	Builder *	ctx,
		const char *	name
	)

Check whether a --build-option was passed on the command line.

Parameters

ctx	Build context.
name	Option key.

Returns: 1 if --build-option=key (or --build-option=key=...) was passed, 0 otherwise.

◆ __builtin_build_have_tool()

int __builtin_build_have_tool	(	Builder *	ctx,
		const char *	name
	)

Check whether a named tool is available.

Parameters

ctx	Build context.
name	Tool name to look up in `PATH`.

Returns: 1 if name is executable and permitted by the current tool allowlist, 0 otherwise.

◆ __builtin_build_host()

const char * __builtin_build_host ( Builder * ctx )

Host platform name ("darwin", "linux", ...).

Parameters

ctx	Build context.

Returns: The host platform name, as an interned string.

◆ __builtin_build_ignore_watch()

void __builtin_build_ignore_watch	(	Builder *	ctx,
		const char *	pattern
	)

Drops --watch events for paths matching an fnmatch glob.

◆ __builtin_build_install_artifact()

void __builtin_build_install_artifact	(	Builder *	ctx,
		BuildTarget *	t
	)

Register t for installation when --build-install is active.

A no-op if --build-install was not passed. The copy happens after the build entry returns and the build succeeded.

Parameters

ctx	Build context.
t	Target to install.

◆ __builtin_build_link_with()

void __builtin_build_link_with	(	BuildTarget *	t,
		BuildTarget *	dep
	)

Declare that t links against (and is built after) dep.

Adds a -l<dep> flag at link time.

Parameters

t	Target that links against `dep`.
dep	Target being linked against.

◆ __builtin_build_mkdir()

int __builtin_build_mkdir	(	Builder *	ctx,
		const char *	path
	)

Create path and all intermediate directories (mkdir -p semantics).

Parameters

ctx	Build context.
path	Directory path to create.

Returns: 0 on success, -1 on error.

◆ __builtin_build_move_file()

int __builtin_build_move_file	(	Builder *	ctx,
		const char *	src,
		const char *	dst
	)

Move (rename) file src to dst.

Falls back to copy + delete on cross-device moves.

Parameters

ctx	Build context.
src	Source file path.
dst	Destination file path.

Returns: 0 on success, -1 on error.

◆ __builtin_build_out_dir()

const char * __builtin_build_out_dir ( Builder * ctx )

Output directory for build artifacts (default build/).

Parameters

ctx	Build context.

Returns: The output directory, as an interned string.

◆ __builtin_build_pkg_config()

int __builtin_build_pkg_config	(	BuildTarget *	t,
		const char *	pkg
	)

Run pkg-config to obtain compile and link flags for pkg and add them to t.

Parameters

t	Target to add the flags to.
pkg	Package name to query.

Returns: 0 on success, non-zero if pkg-config is not found, not allowed, or reports an error.

◆ __builtin_build_profile()

const char * __builtin_build_profile ( Builder * ctx )

Return the global build profile name.

Parameters

ctx	Build context.

Returns: The profile set via --build-profile, or NULL if none is set.

◆ __builtin_build_read_file()

const char * __builtin_build_read_file	(	Builder *	ctx,
		const char *	path
	)

Read the file at path into a string.

The returned pointer is valid until the build entry returns.

Parameters

ctx	Build context.
path	File path to read.

Returns: The file contents as a NUL-terminated string, or NULL on error or if the file exceeds 4 MB.

◆ __builtin_build_root()

const char * __builtin_build_root ( Builder * ctx )

Absolute path of the directory the build was launched from.

Parameters

ctx	Build context.

Returns: The build root, as an interned string.

◆ __builtin_build_run()

int __builtin_build_run	(	Builder *	ctx,
		BuildTarget *	t
	)

Build t and its transitive dependencies.

Parameters

ctx	Build context.
t	Target to build.

Returns: 0 on success.

◆ __builtin_build_run_all()

int __builtin_build_run_all ( Builder * ctx )

Build every declared target in topological order.

Parameters

ctx	Build context.

Returns: 0 on success.

◆ __builtin_build_run_custom()

BuildTarget * __builtin_build_run_custom	(	Builder *	ctx,
		const char *	name,
		const char *	cmd
	)

Register a custom shell-command target named name that runs cmd when the target is reached in the build graph.

Fails (non-zero exit from BuildDefault) if cmd returns a non-zero exit code.

Parameters

ctx	Build context.
name	Target name.
cmd	Shell command to run.

Returns: The new target handle, so other targets may declare a dependency on it via DependsOn.

◆ __builtin_build_run_default()

int __builtin_build_run_default ( Builder * ctx )

Build every declared target and print a summary.

Parameters

ctx	Build context.

Returns: 0 on success.

◆ __builtin_build_set_cwd()

int __builtin_build_set_cwd	(	Builder *	ctx,
		const char *	path
	)

Change the process working directory to path.

The original CWD is saved on the first call and automatically restored when the build entry returns.

Parameters

ctx	Build context.
path	Directory to change into.

Returns: 0 on success, -1 on error.

Note: cd inside a RunCustom shell script does not affect the parent CWD (RunCustom runs in a forked child); SetCwd changes the real process CWD and is visible to all subsequent build steps.

◆ __builtin_build_set_install_prefix()

void __builtin_build_set_install_prefix	(	Builder *	ctx,
		const char *	path
	)

Override the install prefix for InstallArtifact.

Default: PREFIX env var or /usr/local.

Parameters

ctx	Build context.
path	Install prefix path.

◆ __builtin_build_set_output()

void __builtin_build_set_output	(	BuildTarget *	t,
		const char *	path
	)

Override the target's output path (relative to the out dir).

Parameters

t	Target to modify.
path	Output path, relative to the out dir.

◆ __builtin_build_set_profile()

void __builtin_build_set_profile	(	BuildTarget *	t,
		const char *	profile
	)

Set the build profile for target t, overriding any global --build-profile default.

Profile flags are prepended before the target's own AddCFlag entries, so per-target flags can override them:

Profile	Compiler flags	Defines
debug	-g -O0	—
release	-O2	-DNDEBUG
relwithdebinfo	-O2 -g	-DNDEBUG
minsizerel	-Os	-DNDEBUG

Parameters

t	Target to modify.
profile	Profile name: `"debug"`, `"release"`, `"relwithdebinfo"`, or `"minsizerel"`.

◆ __builtin_build_set_target_env()

void __builtin_build_set_target_env	(	BuildTarget *	t,
		const char *	name,
		const char *	value
	)

Set an environment variable for t's compiler/linker child process only (e.g. AFL_USE_ASAN=1 for an afl-asan target).

Has no effect on a RunCustom target, whose command runs through the vendored build shell, not the host toolchain.

Parameters

t	Target to modify.
name	Environment variable name.
value	Environment variable value.

◆ __builtin_build_set_target_triple()

void __builtin_build_set_target_triple	(	BuildTarget *	t,
		const char *	triple
	)

Set a clang-style target triple for t (e.g. "aarch64-linux-gnu").

Appends --target=<triple> to both compile and link invocations.

Parameters

t	Target to modify.
triple	Target triple.

◆ __builtin_build_set_toolchain()

void __builtin_build_set_toolchain	(	BuildTarget *	t,
		const char *	cc
	)

Override the compiler binary for t (e.g. "aarch64-linux-gnu-gcc").

Takes precedence over --build-cc and the system default. Use for GCC-style cross-compilers that are identified by a prefixed name.

Parameters

t	Target to modify.
cc	Compiler binary name or path.

◆ __builtin_build_static_lib()

BuildTarget * __builtin_build_static_lib	(	Builder *	ctx,
		const char *	name
	)

Create a static-library target (output lib/lib<name>.a).

Parameters

ctx	Build context.
name	Target name.

Returns: The new target handle.

◆ __builtin_build_target_count()

int __builtin_build_target_count ( Builder * ctx )

Return the number of [[cccc::build_target]] factory functions declared in the current build script.

Useful for programmatic target enumeration from inside the build entry.

Parameters

ctx	Build context.

Returns: The number of declared [[cccc::build_target]] factories.

◆ __builtin_build_target_name()

const char * __builtin_build_target_name	(	Builder *	ctx,
		int	i
	)

Return the name of the i -th [[cccc::build_target]] factory.

Parameters

ctx	Build context.
i	Zero-based factory index.

Returns: The factory's name, or NULL if i is out of range.

◆ __builtin_build_target_output()

const char * __builtin_build_target_output ( BuildTarget * t )

On-disk output path for t.

Lets a RunCustom command reference the binary a dependency target just built instead of hardcoding a path. For EXE/STATIC/DYNAMIC/BYTECODE targets this is <out_dir>/<path> — the explicit SetOutput() path if given, else the kind-appropriate default (bin/<name>, lib/lib<name>.a, ...). For a RunCustom target it is the first path DeclareOutput() recorded (call order), returned verbatim (not joined onto out_dir, since a custom command can write anywhere).

Parameters

t	Target to query.

Returns: The output path, or "" if DeclareOutput() was never called (RunCustom targets only).

◆ __builtin_build_target_triple()

const char * __builtin_build_target_triple ( Builder * ctx )

Return the global cross-compilation triple.

Parameters

ctx	Build context.

Returns: The triple set via --build-triple, or NULL if none is set.

◆ __builtin_build_use_system_headers()

void __builtin_build_use_system_headers ( BuildTarget * t )

Compile a cccc-compiled target against the host's own system headers (--use-system-headers).

Parameters

t	A `CcccExecutable` or `CcccObject` target.

◆ __builtin_build_verbose()

int __builtin_build_verbose ( Builder * ctx )

Non-zero when verbose output was requested.

Parameters

ctx	Build context.

Returns: 1 if --build-verbose was passed, 0 otherwise.

◆ __builtin_build_wants_install()

int __builtin_build_wants_install ( Builder * ctx )

Check whether install was requested.

Parameters

ctx	Build context.

Returns: 1 if --build-install was passed on the command line, 0 otherwise.

◆ __builtin_build_watch()

void __builtin_build_watch	(	Builder *	ctx,
		const char *	path
	)

Adds a file, or a directory (recursively), to the --watch set.

◆ __builtin_build_watch_glob()

void __builtin_build_watch_glob	(	Builder *	ctx,
		const char *	pattern
	)

Adds an fnmatch glob to the --watch set.

◆ __builtin_build_watching()

int __builtin_build_watching ( Builder * ctx )

Non-zero under --watch.

◆ __builtin_build_write_file()

int __builtin_build_write_file	(	Builder *	ctx,
		const char *	path,
		const char *	content
	)

Write content to path, creating parent directories as needed.

Parameters

ctx	Build context.
path	File path to write.
content	Content to write.

Returns: 0 on success, -1 on error.

Macros

Typedefs

Functions

Detailed Description

Usage

Macro Definition Documentation

◆ AddCFlag

◆ AddDefine

◆ AddFramework

◆ AddFrameworkPath

◆ AddInclude

◆ AddInput

◆ AddLdFlag

◆ AddLib

◆ AddLibPath

◆ AddSource

◆ AddSourcesGlob

◆ AddSourcesGlobDeferred

◆ AddSourceStr

◆ AddSystemInclude

◆ AddUndef

◆ Build

◆ BuildAll

◆ BuildArgc

◆ BuildArgv

◆ BuildDefault

◆ BuildHost

◆ BuildOutDir

◆ BuildProfile

◆ BuildRoot

◆ BuildTargetCount

◆ BuildTargetName

◆ BuildTargetTriple

◆ BuildVerbose

◆ BuildWantsInstall

◆ BuildWatching

◆ CaptureCommand

◆ CcccExecutable

◆ CcccObject

◆ CcccPath

◆ CopyFile

◆ DeclareOutput

◆ DeleteDir

◆ DeleteFile

◆ DependsOn

◆ DirExists

◆ DynamicLib

◆ ExcludeSource

◆ Executable

◆ FileExists

◆ FindTool

◆ GetBuildOption

◆ GetCwd

◆ GetEnv

◆ GlobFiles

◆ HaveBuildOption

◆ HaveTool

◆ IgnoreWatch

◆ InstallArtifact

◆ LinkWith

◆ MkDir

◆ MoveFile

◆ PkgConfig

◆ ReadFile

◆ RunCustom

◆ SetCwd

◆ SetInstallPrefix

◆ SetOutput

◆ SetProfile

◆ SetTargetEnv

◆ SetTargetTriple

◆ SetToolchain

◆ StaticLib

◆ TargetOutput

◆ UseSystemHeaders

◆ Watch

◆ WatchGlob

◆ WriteFile

Typedef Documentation

◆ Builder