Creating a new project

This page is a guide to many of the beginning (and some intermediate) features of the creation and modification of a Code::Blocks project. If this is your first experience with Code::Blocks, here is a good starting point.

The project wizard

Launch the Project Wizard through File->New->Project... to start a new project. Here there are many pre-configured templates for various types of projects, including the option to create custom templates. Select Console application, as this is the most common for general purposes, an click Go.

Note: red text instead of black text below any of the icons signifies it is using a customized wizard script.

The console application wizard will appear next. Continue through the menus, selecting C++ when prompted for a language. In the next screen, give the project a name and type or select a destination folder. As seen below, Code::Blocks will generate the remaining entries from these two.

Finally, the wizard will ask if this project should use the default compiler (normally GCC) and the two default builds: Debug and Release. All of these settings are fine. Press finish and the project will be generated. The main window will turn gray, but that is not a problem, the source file needs only to be opened. In the Projects tab of the Management pane on the left expand the folders and double click on the source file main.cpp to open it in the editor.

This file contains the following standard code.

main.cpp

#include <iostream>

using namespace std;

int main()
{
    cout << "Hello world!" << endl;
    return 0;
}

Changing file composition

A single source file is of little uses in programs of any useful complexity. In order to handle this, Code::Blocks has several very simple methods of adding additional files to the project.

Adding a blank file

In this example, we will be splitting the function

main.cpp

    cout << "Hello world!" << endl;

into a separate file.

Note: it is generally improper programming style to create a function this small; it is done here to give a simple example.

To add the new file to the project, bring up the file template wizard through either File->New->File... or Main Toolbar->New file (button)->File...

Select C/C++ source and click Go. Continue through the following dialogs very much like the original project creation, selecting C++ when prompted for a language. On the final page, you will be presented with several options. The first box will determine the new filename and location (as noted, the full path is required). You may optionally use the ... button to bring up a file browser window to save the file's location. Checking Add file to active project will store the filename in the Sources folder of the Projects tab of the Management panel. Checking any of the build targets will alert Code::Blocks that the file should be compiled and linked into the selected target(s). This can be useful if, for example, the file contains debug specific code, as it will allow the inclusion to (or exclusion from) the appropriate build target(s). In this example, however, the hello function is of key importance, and is required in each target, so select all the boxes and click Finish to generate the file.

The newly created file should open automatically; if it does not, open it by double clicking on its file in the Projects tab of the Management panel. Now add in code for the function main.cpp will call.

hello.cpp

#include <iostream>

using namespace std;

void hello()
{
    cout << "Hello world!" << endl;
}

Adding a pre-existing file

Now that the hello() function is in a separate file, the function must be declared for main.cpp to use it. Launch a plain text editor (for example Notepad or Gedit), and add the following code.

hello.h

#ifndef HELLO_H_INCLUDED
#define HELLO_H_INCLUDED

void hello();

#endif // HELLO_H_INCLUDED

Save this file as a header (hello.h) in the same directory as the other source files in this project. Back in Code::Blocks, click Project->Add files... to open a file browser. Here you may select one or multiple files (using combinations of Ctrl and Shift). (The option Project->Add files recursively... will search through all the subdirectories in the given folder, selecting the relevant files for inclusion.) Select hello.h, and click Open to bring up a dialog requesting to which build targets the file(s) should belong. For this example, select both targets.

Note: if the current project has only one build target, this dialog will be skipped.

Returning to the main source (main.cpp) include the header file and replace the cout function to match the new setup of the project.

main.cpp

#include "hello.h"

int main()
{
    hello();
    return 0;
}

Press Ctrl-F9, Build->Build, or Compiler Toolbar->Build (button - the gear) to compile the project. If the following output is generated in the build log (in the bottom panel) then all steps were followed correctly.

-------------- Build: Debug in HelloWorld ---------------

Compiling: main.cpp
Compiling: hello.cpp
Linking console executable: bin\Debug\HelloWorld.exe
Output size is 923.25 KB
Process terminated with status 0 (0 minutes, 0 seconds)
0 errors, 0 warnings (0 minutes, 0 seconds)

The executable may now be run by either clicking the Run button or hitting Ctrl-F10.

Note: the option F9 (for build and run) combines these commands, and may be more useful in some situations.

See the build process of Code::Blocks for what occurs behind the scenes during a compile.

Removing a file

Using the above steps, add a new C++ source file, useless.cpp, to the project. Removing this unneeded file from the project is straightforward. Simply right-click on useless.cpp in the Projects tab of the Management pane and select Remove file from project.

Note: removing a file from a project does not physically delete it; Code::Blocks only removes it from the project management.

Modifying build options

Build targets have come up several times so far. Changing between the two default generated ones - Debug and Release - can simply be done through the drop-down list on the Compiler Toolbar. Each of these targets has the ability to be a different type (for example: static library; console application), contain a different set of source files, custom variables, different build flags (for example: debug symbols -p; size optimization -Os; link time optimization -flto), and several other options.

Open Project->Properties... to access the main properties of the active project, HelloWorld. Most of the settings on the first tab, Project settings, are rarely changed. Title: allows the name of the project to be changed. If Platforms: is changed to something other than its default All, Code:Blocks will only allow the project to build on the selected targets. This is useful if, for example, the source code contains Windows API, and would therefore be invalid anywhere but Windows (or any other operating system specific situations). The Makefile: options are used only if the project should use a makefile instead of Code::Blocks' internal build system (see Code::Blocks and Makefiles for further details).

Adding a new build target

Switch to the Build targets tab. Click Add to create a new build target and name it Release Small. The highlight in the left hand column should automatically switch to the new target (if not, click on it to change the focus). As the default setting for Type: - "GUI application" - is incorrect for the HelloWorld program, change it to "Console application" via the drop-down list. The output filename HelloWorld.exe is fine except in that it will cause the executable to be output in the main directory. Add the path "bin\ReleaseSmall\" (Windows) or "bin/ReleaseSmall/" (Linux) in front of it to change the directory (it is a relative path from the root of the project). The Execution working dir: refers to where the program will be executed when Run or Build and run are selected. The default setting "." is fine (it refers to the project's directory). The Objects output dir: needs to be changed to "obj\ReleaseSmall\" (Windows) or "obj/ReleaseSmall/" (Linux) in order to be consistent with the remainder of the project. The Build target files: currently has nothing selected. This is a problem, as nothing will be compiled if this target is built. Check all the boxes.

The next step is to change the target's settings. Click Build options... to access the settings. The first tab the comes up has a series of compiler flags accessible through check boxes. Select "Strip all symbols from binary" and "Optimize generated code for size". The flags here contain many of the more common options, however, custom arguments may be passed. Switch to the Other options sub-tab and add the following switches.

-fno-rtti
-fno-exceptions
-ffunction-sections
-fdata-sections
-flto

Now switch to the Linker settings tab. The Link libraries: box provides a spot to add various libraries (for example, wxmsw28u for the Windows Unicode version of the wxWidgets monolithic dll). This program does not require any such libraries. The custom switches from the previous step require their link-time counterparts. Add

-flto
-Os
-Wl,--gc-sections
-shared-libgcc
-shared-libstdc++

to the Other linker options: tab. (For further details on what these switches do, see the GCC documentation on optimization options and linker options.)

Virtual Targets

Click OK to accept these changes and return to the previous dialog. Now that there are two release builds, it will take two separate runs of Build or Build and run to compile both. Fortunately, Code::Blocks provides the option to chain multiple builds together. Click Virtual targets..., then Add. Name the virtual target Releases and click OK. In the right-hand Build targets contained box, select both Release and Release small. Close out of this box and hit OK on the main window.

The virtual target Releases will now be available from the Compiler Toolbar; building this should result in the following output.

-------------- Build: Release in HelloWorld ---------------

Compiling: main.cpp
Compiling: hello.cpp
Linking console executable: bin\Release\HelloWorld.exe
Output size is 457.50 KB

-------------- Build: Release Small in HelloWorld ---------------

Compiling: main.cpp
Compiling: hello.cpp
Linking console executable: bin\ReleaseSmall\HelloWorld.exe
Output size is 8.00 KB
Process terminated with status 0 (0 minutes, 1 seconds)
0 errors, 0 warnings (0 minutes, 1 seconds)