8000 GitHub - dangmoody/Builder: A simple and powerful C++ build tool that turns C++ code into compiler arguments · GitHub
[go: up one dir, main page]

Skip to content
dangmoodyPublic

About

A simple and powerful C++ build tool that turns C++ code into compiler arguments

Topics

Resources

Stars

12 stars

Watchers

3 watching

Forks

Repository files navigation

Builder

Distributed under the MIT License.

Intro

Builder is an alternative to the old ways of writing build instruct for C/C++ projects. Unlike Make/Premake/CMake or platform specific shell scripts, you write all your build instruction in native C/C++ and can take it anywhere.

Builder itself is not a separate program you install onto your system. It is just a header file you include into a custom C/C++ source file. In this source file, you will use builder.h to specify a list of build instructions for your project, then compile that as an isolated program using a supported compiler (see Choosing a Compiler below). When you then want to build your main project you just run your executable Builder binary you just compiled.

Installation

  1. Download the latest release.
  2. Put the header file(s) in your project.
  3. Write your own build instruction in a C/C++ file
  4. Compile your build exeuctable for your project
  5. Profit!!!

Quick Start Guide

As an example, here's a file called build.c which is just C/C++ code, into which you include builder. This is our equivalant of a custom .bat/.sh or MAKE/CMAKE file for your project:

#define BUILDER_IMPLEMENTATION // The main header for Builder follows the STB implementation strategy so you can isolate things if necessary
#include "builder.h"

int main( int argc, char **argv ) {
	BuilderOptions options = { 0 };

	// Lets create a main configuration for what our USER will be expected to run.
	BuildConfig *mainConfig = CreateBuildConfig( &options );
	*mainConfig = (BuildConfig) {
		.name			= "main", // This is the name of this configuration - which we can invoke from the terminal wtih '--config='
		.binaryName		= "hello", // On windows this will be "hello.exe", on UNIX just "hello"
		.sourceFiles	= MakeStringList( "hello_world.c" ),
	};

	// This is how builder can know to re-trigger builds for itself if you alter this build.c file. This config allows you to tell your build executable how to rebuild itself.
	options.selfRebuildConfig = CreateBuildConfig( &options );
	*options.selfRebuildConfig = (BuildConfig) {
		.name			= "self",
		.sourceFiles	= MakeStringList( "build.c" ), // The name of the file we're in goes here as we're targeting ourselves. If you rename this file, update this too!
	};

	// Prior to calling the Build function is where you setup all your different configuration information. When you call Build, Builder will start doing all it's magic.
	return Build( &options, argc, argv );
}

Now you just need to compile your Builder program for your project.

You only need to do this once because after that it will catch when you alter the build.c file and recompile itself.

clang -o build.exe build.c	# Windows
clang -o build build.c		# Linux

Now that you've turned your build instructions into an executable called build.exe you can just run that and you'll get your app:

build.exe

It will rebuild itself (if BuilderOptions::selfRebuildConfig is set) if another builder instance spots this in it's dependency chain. Additionally - Builder sets the working directory to the folder containing your build executable, so all relative paths in your build script are relative to that.

Multiple Build Configs

If you have multiple BuildConfigs, you must tell Builder which one you want to build with, specifically.

You can do this by passing --config=<name> at the command line where <name> is the name of the BuildConfig, specified via BuildConfig::name.

Using the above example, if you wanted to build "my_awesome_program" instead of the other configs you'd need to pass at the command line:

build.exe --config=my_awesome_program

If you have multiple BuildConfigs but don't specify which one to build at the command line, Builder will error asking you to tell it which one you want to build.

You can also use BuilderOptions::defaultConfig to tell Builder to build a specific BuildConfig by default:

options.defaultConfig = config;

BuildConfig Dependencies

BuildConfigs can be built before/after other BuildConfigs through explicit ordering via BuildConfig::dependsOn:

#define BUILDER_IMPLEMENTATION
#include "builder.h"

int main( int argc, char **argv ) {
	BuilderOptions options = { 0 };

	BuildConfig *mathlib = CreateBuildConfig( &options );
	*mathlib = (BuildConfig) {
		.name			= "mathlib",
		.binaryName		= "mathlib",	// the file extension is automatically appended for you
		.binaryType		= BINARY_TYPE_DYNAMIC_LIBRARY,
		.binaryFolder	= "bin",
		.sourceFiles	= MakeStringList( "src/mathlib/lib.c" ),
	};

	BuildConfig *app = CreateBuildConfig( &options );
	*app = (BuildConfig) {
		.name				= "app",
		.binaryFolder		= "bin",
		.binaryName			= "app",
		.dependsOn			= MakeDependencies( mathlib ),
		.sourceFiles		= MakeStringList( "src/app/program.c" ),
		.additionalIncludes	= MakeStringList( "src/mathlib" ),
		.additionalLibPaths	= MakeStringList( "bin" ),
		.additionalLibs		= MakeStringList( "mathlib" ),
		.binaryType			= BINARY_TYPE_EXE,
	};

	return Build( &options, argc, argv );
}

You can then build the "app" config through the command line like normal:

build.exe --config=app

Building "app" builds "mathlib" first, since it's listed in dependsOn. You only ever need to tell Builder to build the top-level config.

dependsOn only controls build order, it does not link anything for you. "app" links against "mathlib" because it lists it in additionalLibs and additionalLibPaths.

Custom Command Line Arguments

Builder allows you to create your own command line arguments for your builds.

You can use the HasCommandLineArg function to check if the argument was passed at the command line:

#define BUILDER_IMPLEMENTATION
#include "builder.h"

int main( int argc, char **argv ) {
	BuilderOptions options = { 0 };

	BuildConfig *config = CreateBuildConfig( &options );
	*config = (BuildConfig) {
		.name			= "my_awesome_program",
		.sourceFiles	= MakeStringList( "src/my_code.c" ),
	};

	if ( HasCommandLineArg( argc, argv, "--release" ) ) {
		config->optimization = OPTIMIZATION_PROGRAM_SPEED;
	}

	return Build( &options, argc, argv );
}

You can then pass that command line argument through as normal:

build.exe --release

For arguments of the form --key=value, use GetCommandLineArgValue to get the value. It returns NULL if the argument wasn't passed:

const char *version = GetCommandLineArgValue( argc, argv, "--version" );	// "1.2.3" for --version=1.2.3

Choosing a Compiler

By default, Builder will generate compiler arguments for Clang.

If you want to use a different compiler you can do this via BuilderOptions::compilerPath and BuilderOptions::compilerVersion:

options.compilerPath = "C:/path/to/gcc";
options.compilerVersion = "15.1.0";	// this one is optional and warns you on a mismatch

For MSVC it's recommended you just set your compiler path to "cl" and Builder will locate the MSVC toolchain and Windows SDK automatically.

Visual Studio

Builder can be used to generate Visual Studio Solutions (.sln and .vcxproj). These are also compatible with Rider:

#define BUILDER_IMPLEMENTATION
#include "builder.h"

#define BUILDER_VISUAL_STUDIO_IMPLEMENTATION
#include "builder_visual_studio.h"

int main( int argc, char **argv ) {
	BuilderOptions options = { 0 };

	BuildConfig *config = CreateBuildConfig( &options );
	*config = (BuildConfig) {
		.name			= "my_awesome_program",
		.sourceFiles	= MakeStringList( "src/my_code.c" ),
	};

	options.defaultConfig = config;

	if ( HasCommandLineArg( argc, argv, "--sln" ) ) {
		VisualStudioConfig vsConfigs[] = {
			{ .name = "Debug",   .config = config },
			{ .name = "Release", .config = config, .additionalBuildArgs = MakeStringList( "--release" ) },
		};

		VisualStudioProject vsProjects[] = {
			{
				.name			= "my_awesome_program",
				.configs		= vsConfigs,
				.configsCount	= BUILDER_COUNT_OF( vsConfigs ),
			},
		};

		VisualStudioSolution solution = {
			.name			= "my_awesome_program",
			.platforms		= MakeStringList( "x64" ),
			.projects		= vsProjects,
			.projectsCount	= BUILDER_COUNT_OF( vsProjects ),
		};

		return Builder_GenerateVisualStudioSolution( &options, &solution, argc, argv ) ? 0 : 1;
	}

	return Build( &options, argc, argv );
}

You'd then generate the solution with:

build.exe --sln

Generated projects will call to your build.exe.

VS Code

Builder can be used to generate VS Code's c_cpp_properties.json, tasks.json, and launch.json files:

#define BUILDER_IMPLEMENTATION
#include "builder.h"

#define BUILDER_VS_CODE_IMPLEMENTATION
#include "builder_vs_code.h"

int main( int argc, char **argv ) {
	BuilderOptions options = { 0 };

	BuildConfig *config = CreateBuildConfig( &options );
	*config = (BuildConfig) {
		.name			= "my_awesome_program",
		.sourceFiles	= MakeStringList( "src/my_code.c" ),
	};

	options.defaultConfig = config;

	if ( HasCommandLineArg( argc, argv, "--vscode" ) ) {
		VSCodeCppPropertiesConfig cppPropertiesConfigs[] = {
			{ .config = config, .intelliSenseMode = VSCODE_INTELLISENSE_MODE_LINUX_CLANG_X64 },
		};

		VSCodeTaskConfig taskConfigs[] = {
			{ .config = config },
		};

		VSCodeLaunchConfig launchConfigs[] = {
			{ .binaryName = "bin/my_awesome_program", .debuggerType = VSCODE_DEBUGGER_TYPE_CPPDBG_GDB },
		};

		VSCodeJSONOptions vsCodeOptions = {
			.cppPropertiesConfigs		= cppPropertiesConfigs,
			.cppPropertiesConfigsCount	= BUILDER_COUNT_OF( cppPropertiesConfigs ),
			.taskConfigs				= taskConfigs,
			.taskConfigsCount			= BUILDER_COUNT_OF( taskConfigs ),
			.launchConfigs				= launchConfigs,
			.launchConfigsCount			= BUILDER_COUNT_OF( launchConfigs ),
		};

		return Builder_GenerateVSCodeJSONFiles( &options, &vsCodeOptions, argc, argv ) ? 0 : 1;
	}

	return Build( &options, argc, argv );
}

You'd then generate the JSON files with:

build.exe --vscode

By default, if you call Builder_GenerateVSCodeJSONFiles() without filling in any other settings Builder will generate a JSON entry for each BuildConfig you created.

Zed

Builder can be used to generate Zed's tasks.json and debug.json files:

#define BUILDER_IMPLEMENTATION
#include "builder.h"

#define BUILDER_ZED_IMPLEMENTATION
#include "builder_zed.h"

int main( int argc, char **argv ) {
	BuilderOptions options = { 0 };

	BuildConfig *config = CreateBuildConfig( &options );
	*config = (BuildConfig) {
		.name			= "my_awesome_program",
		.sourceFiles	= MakeStringList( "src/my_code.c" ),
	};

	options.defaultConfig = config;

	if ( HasCommandLineArg( argc, argv, "--zed" ) ) {
		ZedTaskConfig taskConfigs[] = {
			{ .config = config },
		};

		ZedDebugConfig debugConfigs[] = {
			{
				.label		= "Debug my_awesome_program",
				.binaryName	= "bin/my_awesome_program",
				.adapter	= ZED_DEBUGGER_ADAPTER_CODELLDB,
				.request	= ZED_DEBUGGER_REQUEST_LAUNCH,
			},
		};

		ZedJSONOptions zedOptions = {
			.taskConfigs		= taskConfigs,
			.taskConfigsCount	= BUILDER_COUNT_OF( taskConfigs ),
			.debugConfigs		= debugConfigs,
			.debugConfigsCount	= BUILDER_COUNT_OF( debugConfigs ),
		};

		return Builder_GenerateZedJSONFiles( &options, &zedOptions, argc, argv ) ? 0 : 1;
	}

	return Build( &options, argc, argv );
}

You'd then generate the JSON files with:

build.exe --zed

By default, if you call Builder_GenerateZedJSONFiles() without filling in any other settings Builder will generate a JSON entry for each BuildConfig you created.

Compilation Database

Builder can be used to generate a compile_commands.json file (a JSON Compilation Database).

Clangd, CLion, VS Code, and anything else that supports the format can use it for code completion and navigation: https://clang.llvm.org/docs/JSONCompilationDatabase.html

#define BUILDER_IMPLEMENTATION
#include "builder.h"

#define BUILDER_COMPILATION_DATABASE_IMPLEMENTATION
#include "builder_compilation_database.h"

int main( int argc, char **argv ) {
	BuilderOptions options = { 0 };

	BuildConfig *config = CreateBuildConfig( &options );
	*config = (BuildConfig) {
		.name			= "my_awesome_program",
		.sourceFiles	= MakeStringList( "src/my_code.c" ),
	};

	options.defaultConfig = config;

	if ( HasCommandLineArg( argc, argv, "--compile-commands" ) ) {
		CompilationDatabaseOptions compilationDatabaseOptions = { 0 };

		return Builder_GenerateCompilationDatabase( &options, &compilationDatabaseOptions, argc, argv ) ? 0 : 1;
	}

	return Build( &options, argc, argv );
}

You'd then generate the compile_commands.json file with:

build.exe --compile-commands

By default, if you call Builder_GenerateCompilationDatabase() without filling in any other settings Builder will generate an entry for every source file of every BuildConfig you created.

Nothing gets compiled - the commands are the same ones Builder would run, minus the output file.

Motivation

C/C++ has no standard build system, so at some point every C/C++ programmer has to pick one and every option asks the same thing of you: learn a new language. CMake has its own DSL, Makefiles have their own syntax and rules, Premake uses Lua, Meson uses Python. Even if you learn one well, the knowledge doesn't transfer to the next project that uses a different one and you have to learn a project's build system all over again.

You already know C/C++. Why should configuring a C/C++ build require learning anything else?

Builder's answer is to not require it. Your build config is just a C/C++ source file. The types are C structs. The logic is C/C++. If you can write C/C++, you already know how to use Builder.

Contributing

Yes!

Please see Contributing.md.

Credits

Builder would not have been possible without the following people who deserve, at the very least, a special thanks:

  • Dale Green
  • Aiden Knight (File globbing, better incremental compilation, Windows dynamic runtime, and lots of other small things)
  • Ed Owen (Compilation database support, QoL improvements)
  • Yann Richeux (Bug fixes)
  • Tom Whitcombe (Visual Studio project generation)
  • Mike Young (Linux platform code)

About

A simple and powerful C++ build tool that turns C++ code into compiler arguments

Topics

Resources

Stars

12 stars

Watchers

3 watching

Forks

Releases

Used by

Contributors

Languages

0