API Reference | IncludeBuild

Core Functions

ib_init

Initializes IncludeBuild with default settings.

void ib_init(void)

Example:

ib_init();

ib_build

Builds the project. Automatically finds source files, resolves dependencies, and compiles what's needed.

bool ib_build(void)

Returns:

true if the build was successful, false otherwise.

Example:

if (!ib_build()) {
    printf("Build failed!\n");
    return 1;
}

ib_clean

Cleans up all build artifacts.

void ib_clean(void)

Example:

ib_clean();

ib_add_target

Adds a specific build target with a main source file.

void ib_add_target(const char* name, const char* main_source)

Parameters:

name: Name of the target (output executable name).
main_source: Path to the main source file.

Example:

ib_add_target("my_app", "main.c");

Configuration

ib_add_include_dir

Adds a directory to the include search path.

void ib_add_include_dir(const char* dir)

Parameters:

dir: Path to the directory to include.

Example:

ib_add_include_dir("include");

ib_exclude_file

Excludes a file or pattern from the build.

void ib_exclude_file(const char* file)

Parameters:

file: File path or pattern (e.g., "test_*.c") to exclude.

Example:

ib_exclude_file("test_*.c");  // Exclude all test files
ib_exclude_file("build.c");   // Exclude the build script itself

ib_reset_config

Resets the build configuration to default values.

void ib_reset_config(void)

Example:

ib_reset_config();  // Reset to defaults

Libraries

ib_add_library

Adds a library to link with.

void ib_add_library(const char* library)

Parameters:

library: Name of the library to link with (without "lib" prefix or file extension)

Example:

ib_add_library("m");      // Link with the math library
ib_add_library("pthread"); // Link with the pthread library

ib_add_libraries

Adds multiple libraries to link with in a single call.

void ib_add_libraries(const char* first, ...)

Parameters:

first: Name of the first library to link with
...: Additional libraries (must end with NULL)

Example:

ib_add_libraries("m", "pthread", "dl", NULL);

ib_add_library_path

Adds a directory to search for libraries.

void ib_add_library_path(const char* path)

Parameters:

path: Path to the directory containing libraries

Example:

ib_add_library_path("lib");
ib_add_library_path("/usr/local/lib");

Logging

ib_set_log_level

Sets the logging verbosity level.

void ib_set_log_level(ib_log_level level)

Parameters:

level: The log level to set (IB_LOG_ERROR, IB_LOG_WARN, IB_LOG_INFO, or IB_LOG_DEBUG)

Example:

ib_set_log_level(IB_LOG_DEBUG); // Most verbose

ib_set_verbose

Enables or disables verbose output.

void ib_set_verbose(bool verbose)

Parameters:

verbose: Whether to enable verbose output (true) or not (false)

Example:

ib_set_verbose(true); // Enable detailed build information

Log Levels

Enumeration of available log levels.

typedef enum {
    IB_LOG_ERROR = 0,  // Only error messages 
    IB_LOG_WARN = 1,   // Warnings and errors
    IB_LOG_INFO = 2,   // Info, warnings, and errors (default)
    IB_LOG_DEBUG = 3   // All messages including debug information
} ib_log_level;

Library Building

ib_build_library

Automatic "magic" function that builds a complete library project including static lib, shared lib, and tests.

bool ib_build_library(const char* library_name, int argc, char** argv)

Parameters:

library_name: Base name of the library (e.g., "logger" creates "liblogger.a/so")
argc: Number of command line arguments (from main)
argv: Command line arguments (from main)

Returns:

true if the build was successful, false otherwise.

Example:

int main(int argc, char** argv) {
    ib_init();
    
    // Build the library with all its components
    return ib_build_library("logger", argc, argv) ? 0 : 1;
}

ib_build_static_library

Builds a static library (.a) from the specified source.

bool ib_build_static_library(const char* name, const char* main_source, const char* exclude_file)

Parameters:

name: Name of the library (without "lib" prefix or ".a" extension)
main_source: Path to the main source file
exclude_file: File pattern to exclude (or NULL)

Returns:

true if the build was successful, false otherwise.

Example:

ib_build_static_library("math", "src/math.c", "test_*.c");

ib_build_dynamic_library

Builds a dynamic/shared library (.so/.dll) from the specified source.

bool ib_build_dynamic_library(const char* name, const char* main_source, const char* exclude_file)

Parameters:

name: Name of the library (without "lib" prefix or extension)
main_source: Path to the main source file
exclude_file: File pattern to exclude (or NULL)

Returns:

true if the build was successful, false otherwise.

Example:

ib_build_dynamic_library("math", "src/math.c", "test_*.c");

Advanced

ib_init_with_config

Initializes IncludeBuild with a custom configuration.

void ib_init_with_config(const ib_config* config)

Parameters:

config: Pointer to a custom configuration structure

Example:

ib_config custom_config = {0};
strcpy(custom_config.compiler, "clang");
strcpy(custom_config.compiler_flags, "-Wall -O3");
ib_init_with_config(&custom_config);

ib_version

Gets the version string of IncludeBuild.

const char* ib_version(void)

Returns:

String with the version of IncludeBuild.

Example:

printf("Using IncludeBuild version: %s\n", ib_version());

Customizable Limits

Constants that can be defined before including build.h to customize limits.

#define IB_MAX_PATH 1024      // Maximum path length
#define IB_MAX_CMD 4096        // Maximum command length
#define IB_MAX_FILES 1000      // Maximum number of files
#define IB_MAX_DEPS 100        // Maximum dependencies per file
#define IB_MAX_INCLUDE_DIRS 50 // Maximum include directories

Example:

// Define custom limits before including build.h
#define IB_MAX_FILES 2000     // Support more files
#define IB_MAX_DEPS 200       // Support more dependencies
#define IB_MAX_INCLUDE_DIRS 100 // Support more include dirs

#include "build.h"