#include "build.h"

User Guide

IncludeBuild v2 is organized around explicit contexts, projects, and targets. There is no hidden global singleton and no implicit main.c guessing.

1. Copy the Header

$ cp path/to/includebuild/build.h your_project/

2. Create build.c

#define INCLUDEBUILD_IMPLEMENTATION
#include "build.h"

int main(void) {
    ib_context* ctx = ib_context_create();
    ib_project* project = ib_project_create(ctx, ".");
    ib_target* target = ib_project_add_target(project, "app", IB_TARGET_EXECUTABLE);
    ib_status status = IB_OK;

    if (target) {
        status = ib_target_set_entry(target, "main.c");
    }
    if (status == IB_OK) {
        status = ib_project_build(project, IB_MODE_DEBUG);
    }

    ib_project_destroy(project);
    ib_context_destroy(ctx);
    return status == IB_OK ? 0 : 1;
}

3. Compile and Run

$ cc -o build build.c
$ ./build

Projects and Targets

A project owns shared configuration and shared sources. Each target owns its own entry source, optional extra sources, include directories, compile flags, and link flags.

ib_target* app = ib_project_add_target(project, "app", IB_TARGET_EXECUTABLE);
ib_target_set_entry(app, "src/main.c");
ib_target_add_source(app, "src/app_only.c");

Shared Sources

Use project-level shared sources when multiple targets should compile the same source tree with their own target-local settings.

ib_project_scan_shared_dir(project, "src", true);

Include Directories and Flags

ib_project_add_include_dir(project, "include");
ib_target_add_include_dir(app, "vendor/something/include");
ib_target_add_cflags(app, "-Wall -Wextra");
ib_target_add_link_flags(app, "-lm");

Build Modes

IncludeBuild provides IB_MODE_DEBUG, IB_MODE_RELEASE, and IB_MODE_CUSTOM. You can override the flags used by each mode per project.

ib_project_set_mode_flags(project, IB_MODE_RELEASE, "-O2 -DNDEBUG", "-O2 -DNDEBUG");

Compilers and Tooling

Defaults are cc/c++ on Linux and macOS, and gcc/g++ on Windows. Override them when needed:

ib_project_set_c_compiler(project, "clang");
ib_project_set_cxx_compiler(project, "clang++");
ib_project_set_archiver(project, "llvm-ar");

compile_commands.json

Generate editor tooling metadata from the same compile plan used by the build itself:

ib_project_write_compile_commands(project, "compile_commands.json");

Cleaning

ib_project_clean(project);

Project Layout

project/
|-- build.c
|-- build.h
|-- include/
|   `-- app.h
`-- src/
    |-- main.c
    `-- app.c

Incremental Rebuilds

IncludeBuild v2 writes compiler depfiles and per-object command manifests. A source is rebuilt when its object file is missing, one of its tracked dependencies is newer, or its effective compile command changes.