Iceforge

A build tool for C projects.

Build Tool - CLI and Configuration Specification

Table of Contents

1. CLI Interface
   1. General Commands
   2. Build Commands
   3. Run Commands
   4. Package and Versioning
   5. Project Initialization
2. TOML Configuration
   1. Build Section
   2. Dependencies Section
   3. Subprojects Section
   4. Custom Build Rules
   5. Overrides

CLI Interface

General Commands

• iceforge build [OPTIONS]

  • Description: Builds the entire project or a specified subproject.
  • Options:
    • --release : Build in release mode.
    • --debug : Build in debug mode (default).
    • --subproject <name> : Build only a specific subproject.
    • --parallel <N> : Specify the number of parallel jobs for the build.
    • --generate-compile-commands : Generate a compile_commands.json file.
    • --generate-vscode-config : Generate .vscode/c_cpp_properties.json.

• iceforge run [OPTIONS]

  • Description: Runs the built binary or a specified binary if there are multiple binaries in the project.
  • Options:
    • --binary <name> : Specify which binary to run if multiple exist.

• iceforge clean [OPTIONS]

  • Description: Cleans the build directory.
  • Options:
    • --subproject <name> : Clean only a specific subproject.

• iceforge refresh

  • Description: Refresh and update dependencies (like cargo update).

Build Commands

• iceforge build --release

  • Description: Builds the project in release mode.

• iceforge build --debug

  • Description: Builds the project in debug mode (default).

• iceforge build --subproject <name>

  • Description: Build a specific subproject by its name.

Run Commands

• iceforge run

  • Description: Runs the default or only binary.

• iceforge run --binary <name>

  • Description: Runs a specified binary if there are multiple binaries in the project.

Clean Commands

• iceforge clean

  • Description: Cleans the build directory.

• iceforge clean --subproject <name>

  • Description: Clean a specific subproject by its name.

Package and Versioning

• iceforge install

  • Description: Installs the current project or a specified remote iceforge repository for system-wide availability.

• iceforge publish [OPTIONS]

  • Description: Adds the current version in the config to the current commit as a git tag.
  • Options:
    • --remote <name> : Adds the git tag to the specified remote repository.

Project Initialization

• iceforge init [OPTIONS]
  • Description: Initializes a new iceforge project in the current directory or a new directory.
  • Options:
    • --name <name> : Specify the project name.
    • --dir <path> : Create a new directory for the project and initialize it there.

TOML Configuration

Specification

Iceforge Build Tool - TOML Configuration Table

The following table summarizes the fields available in the iceforge build tool's TOML configuration file, specifying the possible values, whether the field is optional or required, and a brief description.

Notes:

• Required fields must be provided for the build to work, while optional fields provide flexibility for advanced customization.

• Fields like build_method, dependencies, and cflags allow the configuration to be as simple or complex as needed for a given project.

• Multiple subprojects and remote dependencies can be defined, each with their own settings.

Build Section

This section defines the general build configuration, including compiler settings, optimization flags, and parallel job configurations.

[build]
c_standard = "c11"               # Specify the C standard (e.g., c99, c11, gnu11, etc.)
compiler = "gcc"                 # Compiler
global_cflags = "-Wall -Wextra"   # Global optimization flags
debug_flags = "-g"               # Debug flags for debug builds
release_flags = "-O3"            # Release flags for release builds
parallel_jobs = 4                # Number of parallel jobs for building

Dependencies Section

This section allows specifying external dependencies, both remote and local, fetched from Git or using pkg-config.

Example:

[dependencies]
[[dependencies.remote]]
name = "mylib_v1"
version = "v1.0.1"
source = "https://github.com/example/mylib.git"
include_name = "mylib"           # The folder prefix for the source includes
include_dirs = ["src/include"]    # Directories to include in the build

[[dependencies.remote]]
name = "glm"
source = "https://github.com/example/glm.git"
include_name = "glm"
include_dirs = ["src/include"]
build_method = "cmake"            # Specifies custom build method

[[dependencies.pkg_config]]
name = "freetype"
pkg_config_query = "freetype2"    # Queries pkg-config for `freetype2` library

[[dependencies.manual]]
name = "glfw"
ldflags = "-lglfw"                # Manually specifies linking flags for GLFW

Subprojects Section

Defines subprojects within the build configuration, allowing each subproject to have its own configuration, dependencies, and output.

Example:

[[subprojects]]
name = "core"
type = "library"                                 # Can be "binary", "library", or "header-only"
src_dir = "src/core"                             # Source directory
include_dirs = ["src/core/include"]              # Include directories
dependencies = ["mylib_v2.mylibA", "freetype"]   # Dependencies specific to this subproject
output_name = "libcore.a"                        # Output file (static library)

[[subprojects]]
name = "game"
type = "binary"
src_dir = "src/game"
include_dirs = ["src/game/include", "src/core/include"]
dependencies = ["core", "mylib_v2"]              # This binary depends on core and mylib_v2
output_name = "game_executable"                  # Final binary name

Custom Build Rules

Custom build rules allow the definition of additional build processes, such as asset compilation or custom source transformation, outside of regular compilation.

Example:

[[custom_build_rules]]
name = "vulkan_vertex_shaders"
description = "Compile vertex shaders to SPIR-V"
src_dir = "assets/shaders"
output_dir = "assets/compiled_shaders"
trigger_extensions = [".vert"]                  # Only files with this extension will trigger the rule
output_extension = ".spv"                       # Output file extension
command = "glslc -o $out -fshader-stage=vert $in" # Command to run for compilation
rebuild_rule = "if-changed"                     # Only rebuild if the source files change

[[custom_build_rules]]
name = "vulkan_fragment_shaders"
description = "Compile fragment shaders to SPIR-V"
src_dir = "assets/shaders"
output_dir = "assets/compiled_shaders"
trigger_extensions = [".frag"]
output_extension = ".spv"
command = "glslc -o ${out} -fshader-stage=frag ${in}"
rebuild_rule = "if-changed"

Overrides

The overrides section allows overriding specific build configurations for subprojects or specific builds (e.g., debugging, more strict compilation flags).

Example:

[[overrides]]
name = "core"
cflags = "-Werror"               # Treat warnings as errors for this subproject
parallel_jobs = 8                # Override parallel job count for this subproject

License

This project is licensed under the GNU General Public License v3.0. See the LICENSE file for details.