CBP file format: elements

The Code::Blocks wiki’s project file page is unfinished, so this page is taken from the code that reads and writes the files: projectloader.cpp and workspaceloader.cpp in the Code::Blocks source, with the constants in its headers. Options are written as one Option element per attribute (e.g. <Option title="app" />). Booleans are "1" and "0".

Root and version

Element	Attributes	Meaning
`CodeBlocks_project_file`	–	The root. The older name `Code::Blocks_project_file` is still read.
`FileVersion`	`major`, `minor`	The format version; current versions write 1.6. Files with no `FileVersion` are converted from the format before 1.1.
`Project`	–	Required; holds everything below.

Project options

Project/Option elements:

Attribute	Meaning
`title`	The project’s name (empty becomes “untitled”).
`platforms`	Platforms the project is for.
`makefile`	Makefile name; written only when not `Makefile`.
`makefile_is_custom`	`1`: build with the project’s own makefile.
`execution_dir`	Directory to run in; written only when it differs from the project folder.
`default_target`	The default target’s name (a number in files before 1.5).
`compiler`	The compiler’s ID, e.g. `gcc`.
`extended_obj_names`	`1`: extended object file names.
`pch_mode`	Where precompiled headers go: `0` in a folder beside the header (named after the header), `1` in the object output folder (the default; not written), `2` in a file beside the header with `.gch` added.
`virtualFolders`	The virtual folders, separated by semicolons.
`show_notes`	`1`: show the project notes when it opens; the notes are in a child `notes` element (CDATA).
`check_files`	`0`: do not check files on load; written only when off.

The project may also hold Compiler, ResourceCompiler and Linker lists, ExtraCommands, MakeCommands, Build, VirtualTargets, Unit and UnitsGlob elements, and Extensions.

Build and targets

Build holds Script elements (attribute file, a build script), Target elements (attribute title) and an Environment. Each Target has its own options, lists, extra commands, make commands and environment. Target/Option attributes:

Attribute	Meaning
`platforms`	Platforms the target is built on.
`output`	The output file.
`imp_lib`, `def_file`	Import library and `.def` file, written for dynamic libraries.
`prefix_auto`, `extension_auto`	`1`: add the platform’s usual prefix (such as `lib`) or extension; otherwise the name is used as written.
`working_dir`	Working directory when running; written when not `.`.
`object_output`	Object file folder; written when not `.objs`.
`deps_output`	Dependency folder; written when not `.deps`.
`external_deps`	Extra files the target depends on.
`additional_output`	Extra files the target produces.
`type`	The target type (below); required.
`compiler`	The compiler’s ID for this target.
`use_console_runner`	`0`: do not use the console runner; written only for console targets with it turned off.
`parameters`	Arguments when running.
`host_application`	The host application to run the target with.
`run_host_application_in_terminal`	`1`: run the host application in a terminal.
`createDefFile`, `createStaticLib`	Flags for library targets, named for creating a `.def` file and a static (import) library.
`projectCompilerOptionsRelation`	How the target’s options combine with the project’s (below); written only when not 3. Out-of-range values become 3.
`projectLinkerOptionsRelation`
`projectIncludeDirsRelation`
`projectLibDirsRelation`
`projectResourceIncludeDirsRelation`
`includeInTargetAll`	Files before 1.5 only: include the target in “all”.

Target types

Value	Name	Meaning
0	`ttExecutable`	A program (a GUI program on Windows).
1	`ttConsoleOnly`	A console program; differs from 0 only on Windows.
2	`ttStaticLib`	A static library.
3	`ttDynamicLib`	A dynamic library.
4	`ttCommandsOnly`	Runs only its pre-build and post-build commands.
5	`ttNative`	A native binary.

Option relations

Value	Name	Meaning
0	`orUseParentOptionsOnly`	Use the project’s options only.
1	`orUseTargetOptionsOnly`	Use the target’s options only.
2	`orPrependToParentOptions`	Target options, then the project’s.
3	`orAppendToParentOptions`	Project options, then the target’s (the default).

Compiler, resource compiler and linker lists

At project level and inside a target, each list holds Add elements:

Element	`Add` attributes	Meaning
`Compiler`	`option`, `directory`	A compiler option, or an include directory.
`ResourceCompiler`	`option`, `directory`	A resource compiler option or include directory.
`Linker`	`option`, `library`, `directory`	A linker option, a library to link, or a library directory.

Linker may also hold LinkerExe with value CCompiler (1), CppCompiler (2) or Linker (3): which program links. Without it (0) the choice is automatic. Files before 1.1 used IncludeDirs and LibDirs lists with Add option, which are still read. Empty lists are not written.

Extra commands

Element	Attributes	Meaning
`ExtraCommands/Add`	`before` or `after`	A command run before or after the build.
`ExtraCommands/Mode`	`after="always"`	Run the after-build commands even when nothing was rebuilt.

Make commands

MakeCommands (project or target) holds elements Build, CompileFile, Clean, DistClean, AskRebuildNeeded and SilentBuild, each with a command attribute.

Environment

Environment (in Build or a Target) holds Variable elements with name and value, written in name order.

Virtual targets

VirtualTargets holds Add elements with alias (the virtual target’s name) and targets (real targets, separated by semicolons).

Units

Each source file is a Unit with a filename attribute and optional Option children:

Attribute	Meaning
`compilerVar`	The compiler variable used for the file (e.g. `CPP`, the default in files before 1.6).
`compile`	`0`/`1`: compile the file.
`link`	`0`/`1`: link its object file.
`weight`	Build order weight; 50 when not written.
`virtualFolder`	The virtual folder it is shown in.
`glob`	The ID of the `UnitsGlob` that added it.
`compiler`, `buildCommand`, `use`	A custom build command for one compiler; `use` `0`/`1` turns it on. New lines are written as a literal `\n`.
`target`	A target the file belongs to (one element per target); `<{~None~}>` means none.

UnitsGlob adds files by pattern: attributes directory, wildcard, id (a 64-bit number), recursive (1) and addToProject (1), with Option target children.

Extensions

Extensions is free-form: each plugin reads and writes its own child elements there. Empty ones without attributes are dropped on saving, and the rest are sorted by name.

Workspace files (.workspace)

Element	Attributes	Meaning
`CodeBlocks_workspace_file`	–	The root (`Code::Blocks_workspace_file` is still read).
`Workspace`	`title`	The workspace.
`Project`	`filename`	A project, relative to the workspace file, with `/` separators.
`Depends`	`filename`	Inside a `Project`: another project it depends on.

A separate layout file (root CodeBlocks_workspace_layout_file) keeps the active project (ActiveProject path), preferred target (PreferredTarget name) and editor tabs; it has its own FileVersion.

Sources

Code::Blocks source (read from a public mirror of its SourceForge repository): src/sdk/projectloader.cpp (every project element and attribute), src/sdk/workspaceloader.cpp (workspaces), src/include/projectloader.h (file version 1.6), src/include/compiletargetbase.h (target types, option relations, file name policy) and src/include/cbproject.h (precompiled header modes). The Project file wiki page describes itself as unfinished. Meanings of a few attributes (such as external_deps, weight and platforms) are taken from their names and how the loader uses them.

.CBP File Format – Elements