Project file

From Code::Blocks
Revision as of 14:06, 1 March 2007 by Mandrav (talk | contribs) (Added TBC message)

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="Debug">
				<Option platforms="All" />
				<Option output="Debug/TestConsole" prefix_auto="1" extension_auto="1" />
				<Option working_dir="." />
				<Option object_output="Debug/obj/" />
				<Option deps_output=".deps" />
				<Option external_deps="../TestLib/Debug/libTestLib.a;" />
				<Option additional_output="" />
				<Option type="1" />
				<Option compiler="gcc" />
				<Option use_console_runner="0" />
				<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="../BuildScripts/debug.script" />
				<Script file="../BuildScripts/base.script" />
				<Compiler>
					<Add option="-g" />
				</Compiler>
				<ResourceCompiler />
				<Linker />
				<ExtraCommands>
					<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="All" targets="Debug;" />
		</VirtualTargets>
		<Compiler>
			<Add option="-Wall" />
			<Add option="-fexceptions" />
		</Compiler>
		<ResourceCompiler />
		<Linker />
		<ExtraCommands>
			<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="Debug" />
		</Unit>
		<Unit filename="main.cpp">
			<Option compilerVar="CPP" />
			<Option compile="1" />
			<Option link="1" />
			<Option weight="50" />
			<Option virtualFolder="" />
			<Option target="Debug" />
		</Unit>
		<Extensions>
			<code_completion />
		</Extensions>
	</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
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="Debug">

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="Debug/TestConsole" 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="Debug/obj/" />

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
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="0" />

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).

To be continued...

Mandrav 14:06, 1 March 2007 (UTC)

Retrieved from "https://wiki.codeblocks.org/index.php?title=Project_file&oldid=4468"