User Guide | IncludeBuild

Installation

IncludeBuild is designed to be extremely simple to install. As a header-only library, you only need a single file to get started.

Option 1: Copy to Your Project

The simplest way to use IncludeBuild is to copy the build.h file directly into your project:

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

This allows you to include the file directly in your build script:

#include "build.h"

Option 2: System-wide Installation

For more convenient use across multiple projects, you can install IncludeBuild system-wide:

git clone https://github.com/korzewarrior/includebuild.git
cd includebuild
sudo cp build.h /usr/local/include/includebuild/build.h

You might need to create the directory first if it doesn't exist:

sudo mkdir -p /usr/local/include/includebuild

This will install the header to your system's include path, allowing you to include it as:

#include <includebuild/build.h>

Getting Started

Let's start with a simple "Hello, World!" project using IncludeBuild.

Project Structure

Create a basic project structure:

hello_world/
├── build.c      # Build script
├── build.h      # IncludeBuild header
└── main.c       # Source code

Source Code (main.c)

Create a simple C program:

#include <stdio.h>

int main() {
    printf("Hello, World from IncludeBuild!\n");
    return 0;
}

Build Script (build.c)

Create a build script using IncludeBuild:

#include "build.h"

int main() {
    // Initialize IncludeBuild
    ib_init();
    
    // Enable verbose output for more detailed build information
    ib_set_verbose(true);
    
    // Build the project
    ib_build();
    
    return 0;
}

Building and Running

Compile and run your build script:

gcc -o build build.c
./build

This will compile your project and create the executable. Now run it:

./hello_world
Hello, World from IncludeBuild!

Creating a Build Script

Build scripts are regular C programs that use the IncludeBuild API. This section covers the essential components of a build script.

Basic Structure

Every build script follows this basic structure:

#include "build.h"

int main() {
    // 1. Initialize IncludeBuild
    ib_init();
    
    // 2. Configure your build
    // Add include dirs, libraries, customize compiler settings, etc.
    
    // 3. Perform the build
    ib_build();
    
    return 0;
}

Error Handling

It's good practice to check for errors during the build process:

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

Using Command Line Arguments

You can make your build script flexible by using command line arguments:

#include "build.h"
#include <string.h>

int main(int argc, char* argv[]) {
    // Initialize IncludeBuild
    ib_init();
    
    // Check for command line arguments
    if (argc > 1 && strcmp(argv[1], "clean") == 0) {
        // Clean build artifacts
        ib_clean();
        return 0;
    }
    
    // Normal build process
    ib_build();
    
    return 0;
}

This allows you to run ./build clean to clean build artifacts.

Managing Source Files

IncludeBuild automatically scans and manages source files for you.

Automatic Source Detection

By default, IncludeBuild automatically finds all C/C++ source files in your project. You don't need to specify them individually:

#include "build.h"

int main() {
    ib_init();
    
    // That's it! IncludeBuild will find all .c/.cpp files automatically
    
    ib_build();
    return 0;
}

Adding Targets

For more complex projects, you can define specific targets and their main source files:

// Create a target named "my_app" with main.c as the entry point
ib_add_target("my_app", "main.c");

// Create a second target for a utility program
ib_add_target("utils", "tools/utils.c");

Include Directories

Specify include directories for header files:

// Add the 'include' directory to the include path
ib_add_include_dir("include");

// Add multiple include directories
ib_add_include_dir("third_party/lib1/include");
ib_add_include_dir("third_party/lib2/include");

Excluding Files

You can exclude specific files from the build:

// Exclude a test file from the main build
ib_exclude_file("src/tests/test_main.c");

// Exclude any file containing a specific string
ib_exclude_file("_test.c");

Working with Libraries

IncludeBuild makes it easy to link your project against external libraries.

Adding System Libraries

Link against system libraries:

// Link against the math library
ib_add_library("m");

// Link against pthread
ib_add_library("pthread");

Adding Multiple Libraries

You can add multiple libraries at once using the variadic function:

// Add multiple libraries (must end with NULL)
ib_add_libraries("m", "pthread", "dl", NULL);

Custom Library Paths

Specify paths for non-standard library locations:

// Add a library search directory
ib_add_library_path("/usr/local/lib");
ib_add_library_path("third_party/libs");

Building Your Own Libraries

You can build your own libraries with IncludeBuild using the library builder:

#include "build.h"

int main(int argc, char** argv) {
    // Initialize IncludeBuild
    ib_init();
    
    // Use the library builder to create static and dynamic libraries
    // This also builds any tests in the test/ directory
    return ib_build_library("mylib", argc, argv) ? 0 : 1;
}

The ib_build_library function handles everything for you, including static and dynamic library builds, and finding/compiling tests.

Compilation and Linking

IncludeBuild gives you fine-grained control over the compilation process.

Compiler Flags

Add compiler flags to customize compilation:

// Enable warnings
ib_add_compiler_flag("-Wall");
ib_add_compiler_flag("-Wextra");

// Set optimization level
ib_add_compiler_flag("-O2");

Setting the Compiler

Choose which compiler to use:

// Use clang instead of gcc
ib_set_compiler("clang");

Linker Flags

Add linker flags for more control over the linking process:

// Add a linker flag
ib_add_linker_flag("-static");

// Specify a custom linker script
ib_add_linker_flag("-T custom_linker.ld");

Verbose Output

Enable verbose output to see detailed build information:

// Show detailed build information
ib_set_verbose(true);

Advanced Customization

IncludeBuild offers advanced customization options for complex projects.

Customizing Internal Limits

For larger projects, you may need to customize internal limits. Define these before including build.h:

// Increase the maximum number of source files to 2000
#define IB_MAX_FILES 2000

// Increase maximum dependencies per file to 200
#define IB_MAX_DEPS 200

// Increase maximum include directories to 100
#define IB_MAX_INCLUDE_DIRS 100

// Now include IncludeBuild
#include "build.h"

Custom Build Directories

You can set custom directories for source code, object files, and final executables:

// Set the source directory
ib_set_source_dir("src");

// Set the directory for object files
ib_set_obj_dir("build/obj");

// Set the directory for final executables
ib_set_build_dir("build/bin");

Logging and Debugging

Enable detailed logging for debugging:

// Set log level to debug for maximum verbosity
ib_set_log_level(IB_LOG_DEBUG);

// Show colorized output
ib_set_color_output(true);

Troubleshooting

Here are some common issues and their solutions when using IncludeBuild.

Missing Libraries

If you're getting errors about missing libraries, make sure you've correctly specified the library name and path:

// Ensure library search paths are correct
ib_add_library_path("/usr/local/lib");

// Make sure the library name is correct
ib_add_library("mylib");

Compiler Errors

For detailed compiler error messages, increase the log level:

ib_set_log_level(IB_LOG_DEBUG);

Check that you've added all necessary include directories:

ib_add_include_dir("include");
ib_add_include_dir("third_party/include");

Resource Limits

If you're hitting resource limits, increase them as described in the Advanced Customization section:

#define IB_MAX_FILES 2000
#define IB_MAX_DEPS 200
#include "build.h"

Getting Help

If you're still having trouble, check out these resources:

Consult the API Reference for detailed function documentation
Look at the Examples for working code samples
Check the FAQ for answers to common questions
Visit the GitHub Issues page to see if others have had similar problems
Join the Discord community for real-time help