Project file

NOTE: This page is not yet finished.

The project file is the most important file in Code::Blocks. It's what defines a project and rules how to build it. So, without further ado, let's see how it is formatted. The following is a simple console project. Don't be overwhelmed by its size... It just contains all possible elements for illustration purposes. Normally, when a project is saved by Code::Blocks, it only contains the elements whose values are different than the default values. The following XML text contains the default values for each element/attribute.

Sample project file

<?xml version="1.0" encoding="UTF-8" standalone="yes" ?>
<CodeBlocks_project_file>
	<FileVersion major="1" minor="6" />
	<Project>
		<Option title="TestConsole" />
		<Option platforms="All" />
		<Option makefile="Makefile" />
		<Option makefile_is_custom="0" />
		<Option pch_mode="2" />
		<Option default_target="" />
		<Option compiler="gcc" />
		<Option virtualFolders="" />
		<Option extended_obj_names="0" />
		<Option show_notes="0">
			<notes>
				<![CDATA[]]>
			</notes>
		</Option>
		<MakeCommands>
			<Build command="$make -f $makefile $target" />
			<CompileFile command="$make -f $makefile $file" />
			<Clean command="$make -f $makefile clean$target" />
			<DistClean command="$make -f $makefile distclean$target" />
		</MakeCommands>
		<Build>
			<Script file="" />
			<Target title="default">
				<Option platforms="All" />
				<Option output="default" prefix_auto="1" extension_auto="1" />
				<Option working_dir="." />
				<Option object_output=".objs" />
				<Option deps_output=".deps" />
				<Option external_deps="" />
				<Option additional_output="" />
				<Option type="1" />
				<Option compiler="gcc" />
				<Option use_console_runner="1" />
				<Option parameters="" />
				<Option host_application="" />
				<Option createDefFile="1" />
				<Option createStaticLib="1" />
				<Option projectCompilerOptionsRelation="3" />
				<Option projectLinkerOptionsRelation="3" />
				<Option projectIncludeDirsRelation="3" />
				<Option projectResourceIncludeDirsRelation="3" />
				<Option projectLibDirsRelation="3" />
				<Script file="" />
				<Compiler>
					<Add option="" />
					<Add directory="" />
				</Compiler>
				<ResourceCompiler>
					<Add directory="" />
				</ResourceCompiler>
				<Linker>
					<Add option="" />
					<Add directory="" />
					<Add library="" />
				</Linker>
				<ExtraCommands>
					<Add before=""/>
					<Add after=""/>
					<Mode after="always" />
				</ExtraCommands>
				<MakeCommands>
					<Build command="$make -f $makefile $target" />
					<CompileFile command="$make -f $makefile $file" />
					<Clean command="$make -f $makefile clean$target" />
					<DistClean command="$make -f $makefile distclean$target" />
				</MakeCommands>
			</Target>
		</Build>
		<VirtualTargets>
			<Add alias="" targets="" />
		</VirtualTargets>
		<Compiler>
			<Add option="" />
			<Add directory="" />
		</Compiler>
		<ResourceCompiler>
			<Add directory="" />
		</ResourceCompiler>
		<Linker>
			<Add option="" />
			<Add directory="" />
			<Add library="" />
		</Linker>
		<ExtraCommands>
			<Add before=""/>
			<Add after=""/>
			<Mode after="always" />
		</ExtraCommands>
		<Unit filename="BuildScripts/config.script">
			<Option compilerVar="CPP" />
			<Option compile="0" />
			<Option link="0" />
			<Option weight="50" />
			<Option virtualFolder="" />
			<Option target="default" />
		</Unit>
		<Unit filename="main.cpp">
			<Option compilerVar="CPP" />
			<Option compile="1" />
			<Option link="1" />
			<Option weight="50" />
			<Option virtualFolder="" />
			<Option target="" />
		</Unit>
	</Project>
</CodeBlocks_project_file>

Let's see the XML elements one by one.

Version

<FileVersion major="1" minor="6" />

This defines the project file's version. Code::Blocks can open previous versions of project files but always saves in the latest version format.

Project

<Project>

Starts defining the project.

Project options

Title

<Option title="TestConsole" />

Sets the project's title.

Platforms

<Option platforms="All" />

Defines which platforms this project is valid on. This setting can be redefined in target settings. But note that this setting here must be a superset of any platform specification per-target. Meaning that if we define here that the project is valid for Windows and Unix platforms only, we can't set the Mac platform in a target because that platform is not marked as supported in the project level.

Value	Platform
Windows	Microsoft Windows (tm)
Unix	Any Unix/Linux
Mac	Any Mac platform
All	Any platform

The value can either be "All" or a semi-colon separated list of the supported platforms' values in the table above

Makefile

<Option makefile="Makefile" />

Sets the makefile filename to use when building the project. This is only used when the project is set up to use an external makefile to build (see next element). It is not used when building using Code::Blocks' build system.

<Option makefile_is_custom="0" />

If this option's value is set to "1", the internal build system is effectively disabled and an external makefile is used to build the project.

PCH mode

<Option pch_mode="2" />

Sets the PCH (precompiled headers) mode. This can have one of the following values:

Value	Description
0	Generate PCH in a directory alongside original header.
1	Generate PCH in the object output dir.
2	Generate PCH alongside original header (default).

Default target

<Option default_target="" />

Sets the default target to "Run". When clicking on the "Build->Run" menu item, Code::Blocks "runs" the default target of the project. This entry defines which is this target.

Compiler

<Option compiler="gcc" />

The compiler used to build this project (can be overridden by targets). The internal compiler names used by Code::Blocks are the following:

Compiler	Internal name
GNU GCC	gcc
Cygwin GCC	cygwin
Borland C++ Compiler 5.5	bcc
Digital Mars Compiler	dmc
Digital Mars D Compiler	dmd
GDC D Compiler	gdc
GNU ARM GCC Compiler	arm-elf-gcc
GNU AVR GCC Compiler	avr-gcc
GNU TriCore GCC Compiler	tricoregcc
GNU PowerPC GCC Compiler	ppcgcc
GNU MSP430 GCC Compiler	msp430gcc
Intel C/C++ Compiler	icc
Microsoft Visual C++ Toolkit 2003	msvctk
Microsoft Visual C++ 2005	msvc8
OpenWatcom (W32) Compiler	ow
SDCC Compiler	sdcc
Tiny C Compiler	tcc

Note that not all of the above are present in all platforms.

Virtual folders

<Option virtualFolders="" />

Defines virtual folders for the project tree display. If present, it contains a semi-colon separated list of virtual relative paths, e.g. "Sources/C++;Sources/Python". If virtual folders are used, each project file contains info on what virtual folder it appears in.

Extended object names

<Option extended_obj_names="0" />

If this option's value equals to "1", then the generated object filenames contain the source file's extension too.

Source filename	Object filename (extended_obj_names="0")	Object filename (extended_obj_names="1")
foo.cpp	foo.o	foo.cpp.o

This is especially useful in source trees where there are more than one files with the same basename (i.e. without extension) exist in the same directory.

Notes

<Option show_notes="0">
	<notes>
		<![CDATA[]]>
	</notes>
</Option>

Project specific notes. If "show_notes" equals "1", then the notes contained in the "notes" element are automatically displayed by Code::Blocks when it opens the project. If, on the other hand, "show_notes" equals "0", then the notes are not displayed automatically by Code::Blocks but can be read by the user in the project properties dialog.

"Make" commands

<MakeCommands>
	<Build command="$make -f $makefile $target" />
	<CompileFile command="$make -f $makefile $file" />
	<Clean command="$make -f $makefile clean$target" />
	<DistClean command="$make -f $makefile distclean$target" />
</MakeCommands>

Define how to invoke "make" when using an external makefile for the build.

Build

<Build>

Starts defining the build properties.

Scripts

<Script file="" />

Adds a build script file in the project level (e.g. "BuildScripts/config.script").

Target

<Target title="default">

Starts defining a new target. It also sets the target's name.

Target options

Platforms

<Option platforms="All" />

Defines which platforms this target is valid on. This setting further refines the relevant project setting. But note that this setting here must be a subset of any platform specification in the project level. Meaning that if we define that the project is valid for Windows and Unix platforms only, we can't set the Mac platform here because that platform is not marked as supported in the project level.

Value	Platform
Windows	Microsoft Windows (tm)
Unix	Any Unix/Linux
Mac	Any Mac platform
All	Any platform

The value can either be "All" or a semi-colon separated list of the supported platforms' values in the table above

Output

<Option output="default" prefix_auto="1" extension_auto="1" />

Defines the output filename for this target. The attributes "prefix_auto" and "extension_auto" need only be present if there value equals "1". They tell Code::Blocks that the filename should be automatically adjusted for the platform Code::Blocks is running on. For example, if the target generates the static library "libfoo.a" for gcc, the "output" would be "Debug/foo". The "lib" prefix and ".a" extension would automatically be added by Code::Blocks, if required by the current platform.

Working directory

<Option working_dir="." />

Defines the working directory when "running" this target.

Objects output

<Option object_output=".objs" />

Defines the directory where all the object files will be generated under, when building this target,

Dependencies output

<Option deps_output=".deps" />

Defines the directory where all the dependency files will be generated under, when building this target, This setting is obsolete and not used anymore. It will be removed in a future version of the project file's format.

External dependencies

<Option external_deps="../TestLib/Debug/libTestLib.a;" />

Sets an external dependency that will force a re-link of the target's output file whenever that dependency changes. For example, we could force a target to re-link if it uses a static library and that static library is updated: "../TestLib/Debug/libTestLib.a;". The value entered here is a semi-colon separated list of external filenames whose modification time will be monitored by Code::Blocks' build system.

Additional outputs

<Option additional_output="" />

This is a semi-colon separated list of filenames that their modification times are also checked against the target's output modification time. If any of these is updated, the target's output is forced to re-link. Useful for generated files which Code::Blocks doesn't otherwise know about.

Output type

<Option type="1" />

Defines what kind of output this target produces. Possible values are:

Value	Kind of output
0	GUI application (no console)
1	Console application
2	Static library
3	Dynamic library (dll/so)
4	Commands only (doesn't generate any output, just executes pre/post build steps)
5	Native executable (valid only under windows where it produces a .sys file)

Compiler

<Option compiler="gcc" />

The compiler used to build this target (overrides the project-level compiler). The internal compiler names used by Code::Blocks are the following:

Compiler	Internal name
GNU GCC	gcc
Cygwin GCC	cygwin
Borland C++ Compiler 5.5	bcc
Digital Mars Compiler	dmc
Digital Mars D Compiler	dmd
GDC D Compiler	gdc
GNU ARM GCC Compiler	arm-elf-gcc
GNU AVR GCC Compiler	avr-gcc
Intel C/C++ Compiler	icc
Microsoft Visual C++ Toolkit 2003	msvctk
Microsoft Visual C++ 2005	msvc8
OpenWatcom (W32) Compiler	ow
SDCC Compiler	sdcc
Tiny C Compiler	tcc

Note that not all of the above are present in all platforms.

Console runner

<Option use_console_runner="1" />

Valid for targets producing console applications. If value equals "1", the console executable runs through another Code::Blocks utility program which, when the console executable ends, displays a "Press any key to continue" message. This option is useful if the user wants the console to stay open so he/she can examine his/hers program's output.

Execution parameters

<Option parameters="" />

Any command-line parameters that should be passed to the executable when executing it from inside Code::Blocks.

Host application

<Option host_application="" />

If the target's output is not an executable, this element defines which executable to launch when "running" this target. Useful for dynamic library targets (dll/so) where we can set the host application to launch.

Create DEF file

<Option createDefFile="1" />

If value equals "1", a DEF file will be generated. Valid only for Windows DLLs compiled with GCC (ignored in other configurations).

Create import library

<Option createStaticLib="1" />

If value equals "1", an import library will be generated. Valid only for Windows DLLs compiled with GCC (ignored in other configurations).

Compiler options relation

<Option projectCompilerOptionsRelation="3" />

Defines the relative order this target's compiler options are applied, regarding the project's compiler options. Possible values are:

Value	Relative order
0	Ignore target's compiler options and only use project's compiler options
1	Ignore project's compiler options and only use target's compiler options
2	Apply target's compiler options before project's compiler options (project settings take precedence)
3	Apply target's compiler options after project's compiler options (target settings take precedence)

Linker options relation

<Option projectLinkerOptionsRelation="3" />

Defines the relative order this target's linker options are applied, regarding the project's linker options. Possible values are:

Value	Relative order
0	Ignore target's linker options and only use project's linker options
1	Ignore project's linker options and only use target's linker options
2	Apply target's linker options before project's linker options (project settings take precedence)
3	Apply target's linker options after project's linker options (target settings take precedence)

Include directories relation

<Option projectIncludeDirsRelation="3" />

Defines the relative order this target's include dirs are searched, regarding the project's include dirs. Possible values are:

Value	Relative order
0	Ignore target's include dirs and only use project's include dirs
1	Ignore project's include dirs and only use target's include dirs
2	Apply target's include dirs before project's include dirs (target settings take precedence)
3	Apply target's include dirs after project's include dirs (project settings take precedence)

Resource include directories relation

<Option projectResourceIncludeDirsRelation="3" />

Defines the relative order this target's resource include dirs are applied, regarding the project's resource include dirs. Possible values are:

Value	Relative order
0	Ignore target's resource include dirs and only use project's resource include dirs
1	Ignore project's resource include dirs and only use target's resource include dirs
2	Apply target's resource include dirs before project's resource include dirs (project settings take precedence)
3	Apply target's resource include dirs after project's resource include dirs (target settings take precedence)

Library directories relation

<Option projectLibDirsRelation="3" />

Defines the relative order this target's library dirs are searched, regarding the project's library dirs. Possible values are:

Value	Relative order
0	Ignore target's library dirs and only use project's library dirs
1	Ignore project's library dirs and only use target's library dirs
2	Apply target's library dirs before project's library dirs (target settings take precedence)
3	Apply target's library dirs after project's library dirs (project settings take precedence)

Scripts

<Script file="" />

Adds a build script file at the target level (e.g. "BuildScripts/config.script").

Compiler settings

<Compiler>

Starts defining the compiler settings at target level.

<Add option="">

Adds a compiler option (e.g. "-g").

<Add directory="">

Adds a compiler search directory (includes).

Resource compiler settings

<ResourceCompiler>

Starts defining the resource compiler settings at target level.

<Add directory="">

Adds a resource compiler search directory (resource includes).

Linker settings

<Linker>

Starts defining the linker settings at target level.

<Add option="">

Adds a linker option (e.g. "-Wl,--export-all-symbols").

<Add directory="">

Adds a linker search directory.

<Add library="">

Adds a link library (e.g. "-ljpeg").

Pre/post build steps

<ExtraCommands>

Starts defining extra commands to run before/after compilation (aka pre/post build steps) at target level.

<Add before="" />

Adds a pre-build step.

<Add after="" />

Adds a post-build step.

<Mode after="always" />

Defines if the post-build steps for this target will run each time a build is made, regardless if the target is actually built (or was already up-to-date and no build was needed for it).

"Make" commands

<MakeCommands>
	<Build command="$make -f $makefile $target" />
	<CompileFile command="$make -f $makefile $file" />
	<Clean command="$make -f $makefile clean$target" />
	<DistClean command="$make -f $makefile distclean$target" />
</MakeCommands>

Define how to invoke "make" when using an external makefile for the build. These settings override the relevant settings at the project level.

Virtual targets

<VirtualTargets>

Starts defining virtual targets. These are sets (or groups) of "real" targets.

<Add alias="" targets="" />

Adds a virtual target. The attribute "alias" defines the virtual target's name and the attribute "targets" is a semi-colon separated list of "real" target names.

Compiler settings

<Compiler>

Starts defining the compiler settings at project level.

<Add option="">

Adds a compiler option (e.g. "-g").

<Add directory="">

Adds a compiler search directory (includes).

Resource compiler settings

<ResourceCompiler>

Starts defining the resource compiler settings at project level.

<Add directory="">

Adds a resource compiler search directory (resource includes).

Linker settings

<Linker>

Starts defining the linker settings at project level.

<Add option="">

Adds a linker option (e.g. "-Wl,--export-all-symbols").

<Add directory="">

Adds a linker search directory.

<Add library="">

Adds a link library (e.g. "-ljpeg").

Pre/post build steps

<ExtraCommands>

Starts defining extra commands to run before/after compilation (aka pre/post build steps) at project level.

<Add before="" />

Adds a pre-build step.

<Add after="" />

Adds a post-build step.

<Mode after="always" />

Defines if the post-build steps for this project will run each time a build is made, regardless if the project is actually built (or was already up-to-date and no build was needed for it).

Project files

<Unit filename="">

Adds a single file (aka unit). The filename attribute contains the relative (to the project file) name of the file.

Options

<Option compilerVar="CPP" />

The tool to use to build this file. Code::Blocks automatically assigns the correct tool for each file based on its extension. Valid tool names are "CPP", "C" and "WINDRES".

<Option compile="1" />

If the "compile" attribute equals "1" then this file is part of the compilation stage, else it's not.

<Option link="1" />

If the "link" attribute equals "1" then this file is part of the linking stage, else it's not.

<Option weight="50" />

By adjusting file weights we can change the order the files are compiled. Files with lower weight are compiled earlier (higher the priority).

<Option virtualFolder="" />

If this file should appear inside a virtual folder, this is where it is defined. The "virtualFolder" attribute must contain a relative "virtual" path, already present in the global virtual folders setting (described earlier).

<Option target="" />

The name of the target this file belongs in. The file can be part of more than one targets by using multiple such XML elements. If the file belongs to all the targets in the project, this element is not needed.

To be continued...

Mandrav 13:19, 2 March 2007 (UTC)