About

Copper uses a single configuration file named copper.toml to define how your C/C++ project is structured and built. This file includes global project settings as well as per-unit (executable or library) configuration. This page describes all available options in that file.

A Copper project consists of two main sections:

• Project: Global settings for the whole project
• Unit: One or more buildable units (executables, libraries, etc)

About TOML

TOML (Tom's Obvious Minimal Language) is a configuration file format that's easy to read and write due to its simplicity and clear semantics. Copper uses this file format to define its project configuration.

You can learn more about TOML at the official website.

---

copper.toml Reference

Global Project Configuration

The project section defines settings that apply to the entire build, including compiler choice, default directories, and global flags. This is similar to defining a Solution in an IDE like Visual Studio.

Field	Type	Required	Default Value	Description
name	string	yes	-	Name of the project
language	"c" / "c++"	yes	-	Primary language of the project
compiler	string	yes	-	Name of the compiler to use ("gcc", "msvc", etc)
default-build-directory	string	no	"build"	Base directory for all unit output
default-binary-directory	string	no	"bin"	Directory for final binaries (executables)
default-library-directory	string	no	"lib"	Directory for static libraries
default-object-directory	string	no	"obj"	Directory for intermediate object files
global-include-paths	array of string	no	-	Additional include paths shared across all units
global-additional-compiler_args	string	no	-	Global extra compiler flags
Unit	array of object	yes	-	List of project units (see below)

Unit Configuration

Each Unit defines a build target - either a binary or a library. Units are similar to projects in Visual Studio.

Field	Type	Required	Default Value	Description
name	string	yes	-	Name of the unit (must be unique)
type	"binary" / "static-library"	yes	-	Type of target to build
source	string	yes	-	Path to the unit's source directory. All source files will be compiled from here
output-directory	string	no	project default	Overrides the default binary/library path for this unit
intermediate-directory	string	no	project default	Overrides the default object file path for this unit
include-paths	array of string	no	-	Additional include paths for this unit
additional-compiler-args	string	no	-	Per-unit additional compiler flags

Behavior Defaults:

• If a unit omits output_directory or intermediate_directory Copper will generate the path using the project's set default values
• Unit-specific values for include_paths and additional_compiler_args are added on top of global values instead of replacing them
• All source files (.c, .cpp, etc) are automatically collected from the unit's source directory recursively

Examples

Example copper.toml

An example of properly configured copper project

[project]
name = "my_project"
language = "c++"
compiler = "g++"                                           # Optionally gcc can also be used for c++ projects
default-binary-directory = "binary"                        # Overrides default "bin" name
global-include-paths = ["src/include"]
global-additional-compiler-args = "-Wall -Wextra"          # Enable compiler warnings for the whole project

[Unit](/duckysmacky/copper/wiki/Unit)
name = "core"
type = "static-library"                                    # Will compile into a .lib file (if on Windows)
source = "src/core"                                        # Directory of the unit's source code (*.cpp files)

[Unit](/duckysmacky/copper/wiki/Unit)
name = "app"
type = "binary"
source = "src/app"
include-paths = ["src/app/include"]                        # Only the 'app' unit will include these headers
additional-compiler-args = "-O3"                           # Enable compiler optimizations for this unit

Example project structure

This is just an example of how your project could be structured

my_project/
│
|-- copper.toml         # Configuration file on the project's root level
|-- src/
|   |-- include/        # Project-wide include paths
│   |-- core/
|   |   |-- include/    # Include paths for the 'core' unit
│   │   |-- *.cpp       # Source files for the 'core' unit
│   |-- app/
|   |   |-- include/    # Include paths for the 'app' unit
│   |   |-- *.cpp       # Source files for the 'core' unit
|-- build/
|   |-- bin/            # Binary output
|   |-- lib/            # Library output
|   |-- obj/            # Temp object files

---

Use this page as a reference while configuring your Copper-based projects. For practical setup guidance, see the Getting Started page.