#include "build.h"

API Reference v3.0.0

This is the entire public API: one macro, one struct, eleven functions. Define IB_IMPLEMENTATION in exactly one translation unit before including the header.

Lifecycle

ib_init(argc, argv);   // must be first; parses the command line
int ib_build(void);    // executes the requested verb; returns main's exit code
const char* ib_version(void);

ib_init is a macro (it captures __FILE__ for self-rebuild). ib_build may be called once; on the run verb its return value is the program's exit code.

Targets

ib_target* ib_executable(const char* name);
ib_target* ib_static_lib(const char* name);   // libname.a
ib_target* ib_shared_lib(const char* name);   // libname.so / .dylib / name.dll

Target names must be portable file names. Reserved Windows names, leading dots, and <>:"/\|?* are rejected. Executables gain .exe on Windows.

Describing a Target

void ib_sources(ib_target* t, const char* pattern);
void ib_include(ib_target* t, const char* dir);
void ib_cflags (ib_target* t, const char* flags);
void ib_ldflags(ib_target* t, const char* flags);
void ib_use    (ib_target* t, ib_target* library);

• ib_sources: a path or a glob (*, ? within a segment, ** across directories). Call repeatedly; results are sorted and deduplicated. Empty matches are an error.
• ib_include: adds -I; propagates to targets that ib_use this one.
• ib_cflags / ib_ldflags: appended after the global and mode flags, so target flags win.
• ib_use: links a library target into another target: transitive, cycle-checked, correct link order, automatic -fPIC for static code that ends up in shared libraries.

The Configuration Struct

extern ib_env ib;

const char* root;            // project root            "."
const char* out_dir;         // artifacts               root
const char* state_dir;       // incremental state       ".ibuild"
const char* cc, *cxx, *ar;   // tools                   $CC/cc, $CXX/c++, $AR/ar
const char* cflags;          // every compile           ""
const char* cflags_debug;    //                         "-g -O0 -DDEBUG"
const char* cflags_release;  //                         "-O2 -DNDEBUG"
const char* ldflags;         // every exe/shared link   ""
int jobs;                    // 0 = CPU count
int verbose, quiet;          // CLI -v / -q override these
int color;                   // -1 auto, 0 off, 1 on
int self_rebuild;            // 1 = ./build rebuilds itself when build.c changes
const char* mode;            // read-only: "debug" or "release"

Assign fields between ib_init and ib_build; strings must outlive the build. String literals are suitable. Command-line options override the struct.

The Command Line

./build [debug|release] [verb] [options] [-- program args]

build           compile and link everything (default)
run [target]    build one executable and its libraries, then run it
clean           remove outputs and state
compdb          write compile_commands.json (auto-refreshed afterwards)
help            usage plus this project's targets
version         print the IncludeBuild version

-jN             parallel jobs (default: CPU count)
-v, --verbose   print commands and why each action runs
-q, --quiet     errors only
--color, --no-color   (NO_COLOR is also honored)

Error Handling

Configuration errors print build.h: error: ... and exit nonzero. Compiler and linker failures include the command and its output. ib_build returns nonzero on failure.

On Disk

.ibuild/obj/<mode>/<target>/path/to/file.c.o     objects (plus .d and .cmd records)
.ibuild/link/<mode>/<target>.cmd                 remembered link commands

Delete .ibuild or run ./build clean to clear the build cache.