1  Code::Blocks Project Management

The instructions in several paragraphs (for example 2 or 3) are official documentations of the Code::Blocks Wiki site (eventually reviewed and amended) and available in english only. This documentation is an extension of the original version 1.1, compiled and/or written by Mario Cupelli.

The below illustration shows the design of the Code::Blocks user interface.

Management

This window contains the interface ’Projects’ which will in the following text be referred to as the project view. This view show all the projects opened in Code::Blocks at a certain time. The ’Symbols’ tab of the Management window shows symbols, variables etc..

Editor

In the above illustration, a source named hello.c is opened with syntax highlighting in the editor.

Open files list

shows a list of all files opened in the editor, in this example: hello.c.

CodeSnippets

can be displayed via the menu ’View’ →’CodeSnippets’ . Here you can manage text modules, links to files and links to urls.

Logs & others

This window is used for outputting search results, log messages of a compiler etc...

The status bar gives an overview of the following settings:

• Absolute path of an opened file in the editor.

• The editor uses the default character encoding of your host operating system. This setting will be displayed with default.

• Row and column number of the current cursor position in the editor.

• The configured keyboard mode for inserting text (Insert or Overwrite).

• Current state of a file. A modified file will be marked with Modified otherwise this entry is empty.

• The permission of a file. A file with read only settings will display Read only in the status bar. In the window ’Open files list’ these files will be emphasised with a lock as icon overlay.

  Note:
  In the active editor the user can select the context menu properties. In the appearing dialog in the tab ’General’ the option ’File is read-only’ can be selected. This option will result in a read-only access of the corresponding file within Code::Blocks, but the original read and write attributes of the file on the filesystem are not modified.

• If you start Code::Blocks with the command line option --personality=<profile> then the status bar will show the currently used profile, otherwise default will be shown. The settings of Code::Blocks are stored in the corresponding configuration file <personality>.conf.

Code::Blocks offers a very flexible and comprehensive project management. The following text will address only some of the features of the project management.

1.1  Project View

In Code::Blocks, the sources and the settings for the build process are stored in a project file <name>.cbp. C/C++ sources and the corresponding header files are the typical components of a project. The easiest way to create a new project is executing the command ’File’ →’Project’ and selecting a wizard. Then you can add files to the project via the context menu ’Add files’ in the Management window.

Code::Blocks governs the project files in categories according to their file extensions. These are the preset categories:

Sources

includes source files with the extensions *.c;*.cpp;.

ASM Sources

includes source files with the extensions *.s;*.S;*.ss;*.asm.

Headers

includes, among others, files with the extension *.h;.

Resources

includes files for layout descriptions for wxWidgets windows with the extensions *.res;*.xrc;. These file types are shown in the ’Resources’ tab of the Manangement window.

The settings for types and categories of files can be adjusted via the context menu ’Project tree’ →’Edit file types & categories’ . Here you can also define custom categories for file extensions of your own. For example, if you wish to list linker scripts with the *.ld extension in a category called Linkerscript, you only have to create the new category.

1.2  Notes for Projects

In Code::Blocks, so-called notes can be stored for a project. These notes should contain short descriptions or hints for the corresponding project. By displaying this information during the opening of a project, other users are provided with a quick survey of the project. The display of notes can be switched on or off in the Notes tab of the Properties of a project.

1.3  Project Templates

Code::Blocks is supplied with a variety of project templates which are displayed when creating a new project. However, it is also possible to store custom templates for collecting your own specifications for compiler switches, the optimisation to be used, machine-specific switches etc. in templates. These templates will be stored in the Documents and Settings∖<user>∖Application Data∖codeblocks∖UserTemplates directory in Windows 7, ∖Users∖<user>∖AppData∖Roaming∖CodeBlocks∖UserTemplates in Windows 10 or 11 (or an equivalent path to the user profile, adapted to each OS): <user> is your user name. If the templates are to be open to all users, they have to be copied to a corresponding directory of the Code::Blocks installation. These templates will then be displayed at the next startup of Code::Blocks under ’New’ →’ Project’ →’User templates’ .

1.4  Create Projects from Build Targets

In projects it is necessary to have different variants of the project available. Variants are called Build Targets. They differ with respect to their compiler options, debug information and/or choice of files. A Build Target can also be outsourced to a separate project. To do so, click ’Project’ →’Properties’ , select the variant from the tab ’Build Targets’ and click the ’Create project from target’ button (see Figure 1.2).

1.5  Virtual Targets

Projects can be further structured in Code::Blocks by so-called Virtual Targets. A frequently used project structure consists of two Build Targets, one ’Debug’ Target which contains debug information and one ’Release’ Target without this information. By adding Virtual Targets via ’Project’ →’Properties’ →’Build Targets’ individual Build Targets can be combined. For example, a Virtual Target ’All’ can create the Targets Debug and Release simultaneously. Virtual Targets are shown in the symbol bar of the compiler under Build Targets.

1.6  Pre- and Postbuild steps

Code::Blocks makes it possible to perform additional operations before or after compiling a project. These operations are called Prebuilt or Postbuilt Steps. Typical Postbuilt Steps are:

• Creating an Intel Hexformat from a finished object

• Manipulating objects by objcopy

• Generating dump files by objdump

Example

Creating a Disassembly from an object under Windows. Piping to a file requires calling cmd with the /c option.

cmd /c objdump -D name.elf > name.dis

Archiving a project can be another example for a Postbuilt Step. For this purpose, create a Build Target ’Archive’ and include the following instruction in the Postbuilt Step:

zip -j9 $(PROJECT_NAME)_$(TODAY).zip src h obj $(PROJECT_NAME).cbp

With this command, the active project and its sources, header and objects will be packed as a zip file. In doing so, the Built-in variables $(PROJECT_NAME) and $(TODAY), the project name and the current date will be extracted (see section 3.2). After the execution of the Target ’Archive’, the packed file will be stored in the project directory.

In the share/codeblocks/scripts directory you will find some examples for scripts. You can add a script via menu ’Settings’ →’Scripting’ and register in a menu. If you execute e.g. the script make_dist from the menu then all files belonging to a project will be compressed in an archive <project>.tar.gz.

1.7  Adding Scripts in Build Targets

Code::Blocks offers the possibility of using menu actions in scripts. The script represents another degree of freedom for controlling the generation of your project.

1.8  Workspace and Project Dependencies

In Code::Blocks, multiple projects can be open. By saving open projects via ’File’ →’Save workspace’ you can collect them in a single workspace under <name>.workspace. If you open <name>.workspace during the next startup of von Code::Blocks, all projects will show up again.

Complex software systems consist of components which are managed in different Code::Blocks projects. Furthermore, with the generation of such software systems, there are often dependencies between these projects.

Example

A project A contains fundamental functions which are made available to other projects in the form of a library. Now, if the sources of this project are modified, then the library has to be rebuilt. To maintain consistency between a project B which uses the functions and project A which implements the functions, project B has to depend on project A. The necessary information on the dependencies of projects is stored in the relevant workspace, so that each project can be created separately. The usage of dependencies makes it also possible to control the order in which the projects will be generated. The dependencies for projects can be set via the selecting the menu ’Project’ →’Properties’ and then clicking the ’Project’s dependencies’ button.

1.9  Including Assembler files

In the Management window of the Project View, Assembler files are shown in the ASM Sources category. The user can change the listing of files in categories (see section 1.1). Right-clicking one of the listed Assembler files will open a context menu. Select ’Properties’ to open a new window. Now select the ’Build’ tab and activate the two fields ’Compile file’ and ’Link file’. Then select the ’Advanced’ tab and execute the following steps:

1.

Set ’Compiler variable’ to CC

2.

Select the compiler under ’For this compiler’

3.

Select ’Use custom command to build this file’

4.

In the window, enter:

$compiler $options $includes <asopts> -c $file -o $object

The Code::Blocks variables are marked by $ (see section 3.4). They are set automatically so that you only have to replace the Assembler option <asopt> by your own settings.

1.10  Editor and Tools

This section describe tools in the éditor window.

1.10.1  Default Code

The company’s Coding Rules require source files to have a standard design. Code::Blocks makes it possible to include a predefined content at the beginning of a file automatically when creating new C/C++ sources and headers. This predefined content is called default code. This setting can be selected under ’Settings’ →’Editor’ Default Code. If you create a new file then a macro expansion of variables, e.g. defined via menu ’Settings’ →’Global variables’ , is performed. A new file can be created via the menu ’File’ →’New’ →’File’ .

Example

/*************************************************************** 
 *  Project: $(project) 
 *  Function: 
 *************************************************************** 
 *  $Author: mario $ 
 *  $Name:  $ 
 *************************************************************** 
 * 
 *  Copyright 2007 by company name 
 * 
 ***************************************************************/

1.10.2  Abbreviation

A lot of typing can be saved in Code::Blocks by defining abbreviation. This is done by selecting ’Settings’ →’Editor’ and defining the abbreviations under the name <name>, which can then be called by the keyboard shortcut Ctrl-J (see Figure 1.3).

Parametrisation is also possible by including variables $(NAME) in the abbreviations.

#ifndef $(Guard token) 
#define $(Guard token) 
#endif // $(Guard token)

When performing the abbreviation <name> in the source text and performing Ctrl-J, the content of the variable is requested and included.

1.10.3  Personalities

Code::Blocks settings are saved as application data in a file called <user>.conf in the codeblocks directory. This configuration file contains information such as the last opened projects, settings for the editor, display of symbol bars etc. By default, the ’default’ personality is set so that the configuration is stored in the file default.conf. If Code::Blocks is called from the command line with the parameter --personality=myuser, the settings will be stored in the file myuser.conf. If the profile does not exist already, it will automatically be created. This procedure makes it possible to create the corresponding profiles for different work steps. If you start Code::Blocks from the command line with the additional parameter--personality=ask, a selection box will be displayed for all the available profiles.

1.10.4  Configuration Files

The Code::Blocks settings are stored in the default.conf profile in the codeblocks directory of your Application Data. When using personalities (see section 1.10.3), the configuration details will be stored in the <personality>.conf file.

The tool cb_share_conf, which can be found in the Code::Blocks installation directory, is used for managing and storing these settings.

If you wish to define standard settings for several users of a computer, the configuration file default.conf has to be stored in the directory ∖Documents and Settings∖Default User∖Application Data∖codeblocks in Win 7, ∖Users∖Default∖AppData∖Roaming∖CodeBlocks in Windows 10 or 11, or an equivallent profile path for other OS. During the first startup, Code::Blocks will copy the presettings from ’Default User’ to the application data of the current users.

To create a portable version of Code::Blocks on a USB stick, proceed as follows. Copy the Code::Blocks installation to a USB stick and store the configuration file default.conf in this directory. The configuration will be used as a global setting. Please take care that the file is writeable, otherwise changes of the configuration cannot be stored.

1.10.5  Navigate and Search

In Code::Blocks there are different ways of quick navigation between files and functions. Setting bookmarks is a typical procedure. Via the shortcut Ctrl-B a bookmark is set or deleted in the source file. Via Alt-PgUp you can jump to the previous bookmark, and via Alt-PgDn you can jump to the next bookmark.

If you select the workspace or a project in the workspace in the project view you will be able to search for a file in the project. Just select ’Find file’ from the context menu, then type the name of the file and the file will be selected. If you hit return this file will be opened in the editor (see Figure 1.4).

In Code::Blocks you can easily navigate between header/source files like:

1.

Set cursor at the location where a header file is included and open this file via the context menu ’open include file’ (see Figure 1.5)

2.

Swap between header and source via the context menu ’Swap header/source’

3.

Select e.g. a define in the editor and choose ’Find declaration’ from the context menu to open the file with its declaration.

Code::Blocks offeres several ways of searching within a file or directory. The dialogue box for searching is opened via ’Search’ →’Find’ (Ctrl-F) or ’Find in Files’ (Ctrl-Shift-F).

Alt-G and Ctrl-Alt-G are another useful functions. The dialogue which will open on using this shortcut, lets you select files/functions and then jumps to the implementation of the selected function (see Figure 1.6) or opens the selected file in the editor. You may use wildcards like * or ? etc. for an incremental search in the dialog.

In the editor, you can open a new Open Files dialog via Ctrl-Tab and you can switch between the listed entries. If the Ctrl-key is pressed, then a file can be selected in different ways:

1.

If you select an entry with the left mouse button, then the selected file will be opened.

2.

If you press the Tab-key you will switch between the listed entries. Releasing the Crtl-key will open the selected file.

3.

If you move the mouse over the listed entries, then the current selection will be highlighted. Releasing the Crtl-key will open the selected file.

4.

If the mouse pointer is outside the highlighted selection, then you can use the mouse-wheel to switch between the entries. Releasing the Crtl-key will open the selected file.

A common procedure when developing software is to struggle with a set of functions which are implemented in different files. The Browse Tracker plugin will help you solve this problem by showing you the order in which the files were selected. You can then comfortably navigate the function calls (see section 2.4).

The display of line numbers in Code::Blocks can be activated via ’Settings’ →’General Settings’ in the field ’Show line numbers’. The shortcut Ctrl-G or the menu command ’Search’ →’Goto line’ will help you jump to the desired line.

1.10.6  Symbol view

The Code::Blocks Management window offers a tree view for symbols of C/C++ sources for navigating via functions or variables. As the scope of this view, you can set the current file or project, or the whole workspace.

The following categories exist for the symbols:

Global functions

Lists the implementation of global functions.

Global typedefs

Lists the use of typedef definitions.

Global variables

Displays the symbols of global variables.

Preprocessor symbols

Lists the pre-processor directives created by #define.

Global macros

Lists macros of pre-processor directives.

Structures and classes are displayed in the ’bottom tree’ and the sort sequence can be modified via the context menu. If a category is selected by mouse-click, the found symbols will be displayed in the lower part of the window (see Figure 1.7). Double-clicking the symbol will open the file in which the symbol is defined or the function implemented, and jumps to the corresponding line. An auto-refresh of the symbol browser without saving a file, can be activated via the menu ’Settings’ →’Editor’ →’Code Completion’ (see Figure 1.8). For projects with many symbols the performance within Code::Blocks will be affected.

1.10.7  Including external help files

Code::Blocks comes with just its own help file: normally, developers need much more help and reference for language, libraries, protocols, file formats and so on. The help plugin makes all the needed documentation available from within Code::Blocks itself. Virtually any document can be integrated in the Code::Blocks help system, since the help plugin has the ability to launch external programs, if necessary, to view the added documents.

Once added a new help file or document, there will be a new entry in the ”Help” menu to open it.

The Code::Blocks development environment supports the inclusion of external help files via the menu ’Settings’ →’Environment’ . Include the manual of your choice in the chm format in ’Help Files’ select ’this is the default help file’ (see Figure 1.9). The entry $(keyword) is a placeholder for a select item in your editor. Now you can select a function in an opened source file in Code::Blocks by mouse-click, and the corresponding documentation will appear while pressing F1.

If you have included multiple help files, you can select a term in the editor and choose a help file from the context menu ’Locate in’ for Code::Blocks to search in.

In Code::Blocks you can add even support for man pages. Just add a entry ’man’ and specify the path as follows.

man:/usr/share/man

On Linux, man pages are usually installed anyway, for Windows you might want to download them e.g. from here: https://www.win.tue.nl/~aeb/linux/man

Helpfile options

• You can tell Code::Blocks to use a file as the default helpfile, checking the ”This is the default help file” box. This way, that file will be shown whenever you press the ’F1’ key. Moreover, if you write the $(keyword) as default keyword (see below), this file will be searched for keywords (taking the word selected or the word below the cursor in the current surce file) and will be opened showing the corresponding topic, if present.

• You can tell Code::Blocks to open the helpfile on a topic of your choice, writing the correspondent keyword in the ”Default keyword value” textbox. If the helpfile is the default helpfile and you use $(keyword) as default keyword, the editor will use the word under the cursor (or currently selected) in the current opened file as keyword, opening the default help file at the relevant topic. This will be true, however, only for the default helpfile: any other helpfile or document will not be searched this way. For example, if you have the language reference as default helpfile and add the standard library helpfile, you will have the language keyword explained when hitting ’F1’ on them, but won’t have the library functions explained this way. Viceversa, setting the standard library helpfile as default will give you the F1 help on them but you will loose this feature for the language keywords.

• If your helpfile is an HTML file, you can tell Code::Blocks to open it with the embedded HTML viewer, checking the corresponding option.

Code::Blocks provides an ’Embedded HTML Viewer’, which can be used to display simple html file and find keywords within this file. Just configure the path to the html file, which should be parsed and enable the checkbox ’Open this file with embedded help viewer’ via the menu ’Settings’ →’Environment’ →’Help Files’ .

CHM Files

You can find c++ chm help files on the web. Just add them via the dialog.

For Linux you have to install a chm viewer to be able to open chm files. There are severals like gnochm, kchmviewer, xchm and so on.

1.10.8  Including external tools

Including external tools is possible in Code::Blocks via ’Tools’ →’Configure Tools’ →’Add’ . Built-in variables (see section 3.2) can also be accessed for tool parameters. Furthermore there are several kinds of launching options for starting external applications. Depending on the option, the externally started applications are stopped when Code::Blocks is quit. If the applications are to remain open after quitting Code::Blocks, the option ’Launch tool visible detached’ must be set.

1.11  Tips for working with Code::Blocks

In this chapter we will present some useful settings in Code::Blocks.

1.11.1  Tracking of Modifications

Code::Blocks provides a feature to track modifications within a source file and to show a bar in the margin for the changes. Modifications are marked with a yellow changebar and modifications that are already saved will use a green changebar (see Figure 1.11). You can navigate between your changes via the menu ’Search’ →’Goto next changed line’ or ’Search’ →’Goto previous changed line’ . The same functionality is also accessible via the shortcuts Ctrl-F3 and Ctrl-Shift-F3.

This feature can be enabled or disabled with the checkbox ’Use Changebar’ in the menu ’Settings’ →’Editor’ →’Margins and caret’ .

1.11.2  Data Exchange with other applications

Data can be exchanged between Code::Blocks and other applications. For this interprocess communication DDE (Dynamic Data Exchange) is used for windows and under different operating systems it is a TCP based communication.

With this interface different commands with the following syntax can be sent to a Code::Blocks instance.

[<command>("<parameter>")]

These commands are currently available:

Open

The command

[Open("d:\temp\test.txt")]

uses the parameter, in our case it is a file specified with an absolute path, and opens it in an existing Code::Blocks instance or starts a first instance if required.

OpenLine

This command opens a file at a given line number in a Code::Blocks instance. The line number is specified with :line.

[OpenLine("d:\temp\test.txt:10")]

Raise

Set the focus to the Code::Blocks instance. A parameter must not be passed.

1.11.3  Configuring environmental variables

See also ”Environment Variables Plugin” in section 2.10.

The configuration for an operating system is specified by so-called environmental variables. The environmental variable PATH for example contains the path to an installed compiler. The operating system will process this environmental variable from beginning to end, i.e. the entries at the end will be searched last. If different versions of a compiler or other applications are installed, the following situations can occur:

• An incorrect version of a software is called

• Installed software packages call each other

So it might be the case that different versions of a compilers or other tools are mandatory for different projects. One possibility in such a case is to change the environmental variables in the system control for every project. However, this procedure is error-prone and not flexible. For this requirement, Code::Blocks offers an elegant solution. Different configurations of environmental variables can be created which are used only internally in Code::Blocks. Additionally, you can switch between these configurations. The Figure 1.12 shows the dialogue which you can open via ’Environment Varibales’ under ’Settings’ →’Environment’ . A configuration is created via the ’Create’ button.

Access and scope of the environmental variables created here, is limited to Code::Blocks. You can expand these environmental variables just like other Code::Blocks variables via $(NAME).

Example

You can write the used environment into a postbuild Step (see section 1.6) in a file <project>.env and archive it within your project.

cmd /c echo \%PATH\%  > project.env

or under Linux

echo \$PATH > project.env

1.11.4  Switching between perspectives

Depending on the task in hand, it can be useful to have different configurations or views in Code::Blocks and to save these configurations/views. By default, the settings (e. g. show/hide symbol bars, layout, etc.) are stored in the default.conf configuration file. By using the command line option --personality=ask during the start of Code::Blocks, different settings can be selected. Apart from this global setting, a situation might occur where you wish to switch between different views of windows and symbol bars during a session. Editing files and debugging projects are two typical examples for such situations. Code::Blocks offers a mechanism for storing and selecting different perspectives to prevent the user from frequently having to open and close windows and symbol bars manually. To save a perspective, select the menu ’View’ →’Perspectives’ →’Save current’ and enter a name at <name>. The command ’Settings’ →’Editor’ →’Keyboard shortcuts’ →’View’ →’Perspectives’ →’<name>’ allows a keyboard shortcut to be defined for this process. This mechanism makes it possible to switch between different views by simply using hot keys.

1.11.5  Switching between projects

If several projects or files are opened at the same time, the user needs a way to switch quickly between the projects or files. Code::Blocks has a number of shortcuts for such situations.

Alt-F5

Activates the previous project from the project view.

Alt-F6

Activates the next project from the project view.

F11

Switches within the editor between a source file <name>.cpp and the corresponding header file <name>.h

1.11.6  Extended settings for compilers

During the build process of a project, the compiler messages are displayed in the Messages window in the Build Log tab. If you wish to receive detailed information, the display can be extended. For this purpose click ’Settings’ →’Compiler and Debugger’ and select ’Other Settings’ in the drop-down field.

Take care that the correct compiler is selected. The ’Full command line’ setting in the Compiler Logging field outputs the complete information in the Build Log. In addition, this output can be logged in a HTML file. For this purpose select ’Save build log to HTML file when finished’. Furthermore, Code::Blocks offers a progress bar for the build process in the Build Log window which can be activated via the ’Display build progress bar’ setting.

1.11.7  Zooming within the editor

Code::Blocks offers a very efficient editor. This editor allows you to change the size in which the opened text is displayed. If you use a mouse with a wheel, you only need to press the Ctrl key and scroll via the mouse wheel to zoom in and out of the text.

1.11.8  Wrap Mode

When editing text files, e. g. *.txt, within Code::Blocks, it might be useful to have the text wrapped, meaning long lines will be displayed in several lines on the screen so that they can be properly edited. The ’Word wrap’ function can be activated via ’Settings’ →’Editor’ →’Other Options’ or by setting the checkbox ’Word wrap’ . The Home and End keys position the cursor at the beginning or end of wrapped lines respectively. When setting ’Settings’ →’Editor’ →’Other Options’ and ’Home key always move to caret to first column’ , the cursor will be positioned at the beginning or end of the current line respectively, if the Home or End keys are pressed. If positioning the cursor at the beginning of the first line of the current paragraph is desired, the key combination ’Alt-Home’ is to be used. The same applies analogously for ’Alt-End’ for positioning the cursor at the end of the last line of the current paragraph.

1.11.9  Select modes in editor

Code::Blocks supports different modes for selecting or pasting of strings.

1.

With the left mouse button a text in the active editor can be selected and then the mouse button can be released. With the mouse wheel the user can scroll to a position. If the middle mouse button is pressed then the formerly selected text will be inserted. This feature is available per file and can be seen a clipboard per file.

2.

Pressing the ’ALT’ key will activate the so-called block-select mode and a rectangle selection can be raised with the left mouse button. If the Alt key is released this selection can be copied or pasted. This feature is helpful if you want to select some columns e.g. of an array and copy and paste the content.

3.

In the menu ’Settings’ →’Editor’ →’Margins and Caret’ so-called ’Virtual Spaces’ can be activated. This option enables that a selection in the block select mode can start or end within an empty line.

4.

In the menu ’Settings’ →’Editor’ →’Margins and Caret’ the ’Multiple Selection’ can be activated. While holding the Ctrl-key the user can select different lines in the active editor via the left mouse button. The selections will be appended in the clipboard via the shortcut Ctrl-C or Ctrl-X. Ctrl-V will insert the content at the current cursor position. An additional option called ’Enable typing (and deleting)’ can be activated for multiple selections. This feature is useful if you want to add a pre-processor directive like #ifdef at different source lines or if you want to overwrite or replace a text at several positions.

1.11.10  Code folding

Code::Blocks supports so called code folding. With this feature you can fold e.g. functions within the Code::Blocks editor. A folding point is marked by minus symbol in the left margin of the editor view. In the margin the beginning and the end of a folding point is visible as vertical line. If you click the minus symbol with the left mouse button the code snippet will be folded or unfolded. Via the menu ’Edit’ →’Folding’ you can select the folding. In the editor you see folded code as continous horizontal line.

Code::Blocks provides the folding feature also for preprocessor directives. To enable this feature select ’Fold preprocessor commands’ via the menu ’Settings’ →’Editor’ in the folding entry.

Another possibility is to set user defined folding points. The start of folding point is entered as comment with a opening bracket and the end is market with a comment with a closing bracket.

//{
code with user defined folding
//}

1.11.11  Auto complete

If you open a project in Code::Blocks the ’Search directories’ of your compiler and the project, the sources and headers of your project are parsed. In addition the keywords of the corresponding lexer file are parsed. The parse information is used for the auto complete feature in Code::Blocks. Please check the settings for the editor if this feature is enabled. The auto completion is accessible with the shortcut Ctrl-Space. Via the menu ’Settings’ →’Editor’ →’Syntax highlighting’ you can add user defined keywords to your lexer.

1.11.12  Find broken files

If a file is removed from disk, but is still included in the project file <project>.cbp, then this ’broken file’ will be shown a broken symbol in the project view. You should use the menu ’Remove file from project’ instead of deleting files.

In large projects with a lot of subdirectories the search for broken files can be time consuming. Code::Blocks offers with the plug-in ThreadSearch (see section 2.21) a simple solution for this problem. If you enter a search expression in ThreadSearch and select the option ’Project files’ or ’Workspace files’ , then ThreadSearch will parse all files that are included in a project or workspace. If a broken file is found ThreadSerch will issue an error with the missing file.

1.11.13  Including libraries

In the build options of a project, you can add the used libraries via the ’Add’ button in the ’Link libraries’ entry of the ’Linker Settings’. In doing so, you can either use the absolute path to the library or just give the name without the lib prefix and file extension.

Example

For a library called <path>∖libs∖lib<name>.a, just write <name>. The linker with the corresponding search paths will then include the libraries correctly.

1.11.14  Object linking order

During compiling, objects name.o are created from the sources name.c/cpp. The linker then binds the individual objects into an application name.exe or for the embedded systems name.elf. In some cases, it might be desirable to predefine the order in which the objects will be linked. In Code::Blocks, this can be achieved by assigning priorities. In the context menu ’Properties’ , you can define the priorities of a file in the Build tab. A low priority will cause the file to be linked earlier.

1.11.15  Autosave

Code::Blocks offers ways of automatically storing projects and source files, or of creating backup copies. This feature can be activated in the menu ’Settings’ →’Environment’ →’Autosave’ . In doing so, ’Save to .save file’ should be specified as the method for creating the backup copy.

1.11.16  Settings for file extensions

In Code::Blocks, you can choose between several ways of treating file extensions. The settings dialogue can be opened via ’Settings’ →’Files extension handling’ . You can either use the applications assigned by Windows for each file extension (open it with the associated application), or change the setting for each extensions in such a way that either a user-defined program will start (launch an external program), or the file will be opened in the Code::Blocks editor (open it inside Code::Blocks editor).

1.12  Code::Blocks at the command line

IDE Code::Blocks can be executed from the command line without a graphic interface. In such a case, there are several switches available for controlling the build process of a project. Since Code::Blocks is thus scriptable, the creation of executables can be integrated into your own work processes.

1.12.1  Using command line arguments

If your enter in a command line:
codeblocks /h
You will see a new window containing a list of arguments:

Usage: 
codeblocks [/h] [/?] [--safe-mode] [/na] [/nd] [/ni] [/ns] 
          [--multiple-instance] [/d] [/nc] [/v] [--prefix <str>] 
          [--user-data-dir <str>] [/p <str>] [--no-log] [--log-to-file] 
          [--debug-log-to-file] [--profile <str>] [/S] [/D] 
          [--rebuild] [--build] [--clean] [--target <str>] 
          [--no-batch-window-close] [--batch-build-notify] 
          [--script <str>] [--file <str>] 
          [--dbg-config <str>] [--dbg-attach <str>] 
          [filename(s)...]

Windows

1.

Find the Code::Blocks shortcut in the Desktop or Start menu.

2.

Right click on the icon and select Properties.

3.

Select the Shortcut tab.

4.

Append the command line arguments you want to use to the end of the Target text (behind the quote mark).

5.

Run Code::Blocks by using the shortcut you edited.

Example:
codeblocks /na /nd --no-splash-screen --build <name>.cbp --target=’Release’

*nix

1.

Launch a terminal client, such as XTerm, Gnome Terminal or Konsole.

2.

Type ”codeblocks” and then append the command line arguments you want to use.

Note: Code::Blocks can not run on a real console, X11 must be running and you must use a graphical terminal emulator.

Example:
codeblocks --no-splash-screen --debug-log

1.12.2  Command line arguments

1.13  Shortcuts

This section describes the shortcuts which are or can be used in Code::Blocks.

1.13.1  Introduction

This plugin can be used to bind one or more key shortcuts to the menu items.

Even if an IDE such as Code::Blocks is mainly handled by mouse, keyboard shortcuts are nevertheless a very helpful way of speeding up and simplifying work processes. In the below table, we have collected some of the available keyboard shortcuts.

1.13.2  Features

Includes a configuation panel and a complete system to view/remove/add/edit command shortcuts.

Supports multiple key profiles and a complete load/save system is present.

Allows the users to customize any menu command they want, and define multiple key-shortcut to each command.

1.13.3  Usage

The configuration page for the plugin can be accessed through the ’Settings’ →’Editor’ menu, and then selecting the Keyboard Shortcuts section.

Selecting a command, from the Commands tree, shows the current shortcuts for that command on the right. In the picture Open... is selected and the default shortcut Ctrl-O is displayed.

To add a new shortcut, for the selected command, follow these steps:

1.

Place the focus on the text box under New Shortcut and press the keys, for example F3 or Ctrl-A.

2.

Check Currently assigned to, if another command already has that shortcut you will see it’s name there. If the text says None it’s safe.

3.

Press Add to add the shortcut on the list.

4.

Press OK on the dialog to save changes and return to editor.

1.13.4  Editor

This is a list of shortcuts provided by the Code::Blocks editor component. These shortcuts cannot be rebound.

1.13.5  Files

This is a list of shortcuts provided by the Code::Blocks editor component. These shortcuts cannot be rebound.

1.13.6  View

1.13.7  Search

1.13.8  Build

1.13.9  Debug

1.14  Automatic source paths

A User Interface for project ”globs” aka automatic source directories. The intention is to mimic the glob feature of cmake.
This paragraph is copied from the C::B Wiki: https://wiki.codeblocks.org/index.php/Automatic_source_paths. You can also have a look at the discussion on the forum: https://forums.codeblocks.org/index.php/topic,25276.0.html.

1.14.1  Introduction

Automatic source paths is a feature of Code::Blocks to automatically mirror folders from the source directory to the Code::Blocks project file. A use case is for example if a external program creates source files that are used in Code::Blocks. With automatic source paths Code::Blocks automatically detects changes (addition and removal of source files) in the given directory and mirrors them to the project file.

1.14.2  User Interface

The functionality can be accessed over the ’Project’ →’Automatic source paths...’ menu entry:

This opens the overview dialog

Path

: The base path in which files are searched for automatic import

Recursive

: Search also in sub folders

Wildcard

: Filter files according this wildcard (for example *.cpp: import only files ending with .cpp

Add

: Add an new path

Delete

: Delete current selected path from the list

Edit

: Edit current selected path from the list

Adding or Editing a path opens the Edit path dialog

1.

The path to automatically overwatch

2.

Open the system path dialog to select the path to automatically overwatch

3.

Open the global variables dialog to select a global variable that is replaced and overwatched by Code::Blocks

4.

If this is checked all sub folder of this path are also overwatched

5.

A list of wildcards separated by ’;’ for file extension that are imported for this glob (ex. *.h to import only header files, *.cpp;*.h to import cpp and h files

6.

Select targets where the files found in Path are added

7.

Checkbox to select all/none targets

8.

When this box is checked files will be added to the project file. The project file will be modified every time a file is found. This allows to change properties of the file (like target, or linker flags). The properties are saved in the project file and reloaded when the project is reloaded. If this box is left unchecked the files are loaded when Code::Blocks is running, but not saved to project file. With this unchecked file properties can not be saved and will be lost.

1.14.3  Example

In this example we use the following folder structure:

Lets assume that files in src are added/removed automatically by a third party software. Adding now an automatic source folder in Code::Blocks will automatically add/remove files if they are changed on the file system.

2  Plugins

Most of the plugins described ib this chapter are also in the Wiki. Texts and figures have been copied from the Wiki but adapted to be included in Latex documents (Miktex 2.9).

2.1  General

Code::Blocks’ features can be extend by using plugins. There are generally three types of plugins:

Core plugins:

developed and maintained by the core C::B team.

Contrib plugins:

developed and maintained by the community and proven to be very valuable. So they are integrated into the C::B SVN.

3rd party plugins:

developed and maintained by the community but not (yet?) in the C::B repository. Theses plugins often have their own repository or are being posted (including the source code) in the forums.

If you are looking for plugins:

1.

Look in the official release. Notice that the installer / package manager might require you to enable some of the plugins specifically. So READ carefully.

2.

Search the forums for announcements, especially the forums at https://forums.codeblocks.org/index.php/board,14.0.html.

3.

There might be information on the Wiki concerning other plugins on this page and here : https://wiki.codeblocks.org/index.php/Announcement_for_plugins/patches.

For Windows users, the default behavior of the current installer does not install contrib plugins. You need to manually check the ”contrib plugin” checkbox when asked for selected components to install. There is no way to install them manually afterwards.

If you are developing plugins: Surely you can work with plugin as you like, but here are some suggestions:

  Announce them in the plugin development board in the forums - including the (initial) source code.

OR

  Setup your own webpage (or use a file sharing platform) and post the link to the sources/binaries/svn access in the plugin development board in the forums.

OR

  Setup a repository, probably at BerliOS or SourceForge, post the link to the sources/binaries/svn access in the plugin development board in the forums. Notice: This is very convenient as attachments in our forum might be deleted from time to time. So it is not safe to post source code in the forums.

THEN

  Enter the plugins description on this page.

  Announce the plugin using this template on https://wiki.codeblocks.org/index.php/Template_for_plugin_announcement

2.2  Astyle

Artistic Style is a source code indenter, source code formatter, and source code beautifier for the C, C++, C# programming languages. It can be used to select different styles of coding rules within Code::Blocks.

When indenting source code, we as programmers have a tendency to use both spaces and tab characters to create the wanted indentation. Moreover, some editors by default insert spaces instead of tabs when pressing the tab key, and other editors have the ability to prettify lines by automatically setting up the white space before the code on the line, possibly inserting spaces in a code that up to now used only tabs for indentation.

Since the number of space characters shown on screen for each tab character in the source code changes between editors, one of the standard problems programmers are facing when moving from one editor to another is that code containing both spaces and tabs that was up to now perfectly indented, suddenly becomes a mess to look at when changing to another editor. Even if you as a programmer take care to ONLY use spaces or tabs, looking at other people’s source code can still be problematic.

To address this problem, Artistic Style was created - a filter written in C++ that automatically re-indents and re-formats C / C++ / C# source files.

2.3  AutoVersioning

An application versioning plug in that increments the version and build number of your application every time a change has been made and stores it in version.h with easy to use variable declarations. Also have a feature for committing changes a la SVN style, a version scheme editor, a change log generator and more …

2.3.1  Introduction

The idea of the AutoVersioning plugin was made during the development of a pre-alpha software that required the version info and status. Been to busy coding, without time to maintain the version number, just decided to develop a plugin that could do the job with little intervention as possible.

2.3.2  Features

Here is the list of features the plugin covers summarized:

• Supports C and C++.

• Generates and auto increment version variables.

• Software status editor.

• Integrated scheme editor for changing the behavior of the auto incrementation of version values.

• Date declarations as month, date and year.

• Ubuntu style version.

• Svn revision check.

• Change log generator.

• Works on Windows and Linux.

2.3.3  Usage

Just go to ’Project’ →’Autoversioning’ menu. A pop up window like this will appear:

When hitting yes on the ask to configure message box, the main auto versioning configuration dialog will open, to let you configure the version info of your project.

After configuring your project for auto versioning, the settings that you entered on the configuration dialog will be stored on the project file, and a version.h file will be created. For now, every time that you hit the ’Project’ →’Autoversioning’ menu the configuration dialog will popup to let you edit your project version and versioning related settings, unless you don’t save the new changes made by the plugin to the project file.

2.3.4  Dialog notebook tabs

Version Values

Here you just enter the corresponding version values or let the auto versioning plugin increment them for you (see Figure 2.3).

Major

Increments by 1 when the minor version reaches its maximum

Minor

Increments by 1 when the build number pass the barrier of build times, the value is reset to 0 when it reach its maximum value.

Build Number

(also equivalent to Release) - Increments by 1 every time that the revision number is incremented.

Revision

Increments randomly when the project has been modified and then compiled.

Status

Some fields to keep track of your software status with a list of predefined values for convenience(see Figure 2.4).

Software Status

The typical example should be v1.0 Alpha

Abbreviation

Same as software status but like this: v1.0a

Scheme

Lets you edit how the plugin will increment the version values (see Figure 2.5).

Minor maximum

The maximum number that the Minor value can reach, after this value is reached the Major is incremented by 1 and next time project is compiled the Minor is set to 0.

Build Number maximum

When the value is reached, the next time the project is compiled is set to 0. Put a 0 for unlimited.

Revision maximum

Same as Build Number maximum. Put a 0 for unlimited

Revision random maximum

The revision increments by random numbers that you decide, if you put here 1, the revision obviously will increment by 1.

Build times before incrementing Minor

After successful changes to code and compilation the build history will increment, and when it reaches this value the Minor will increment.

Settings

Here you can set some settings of the auto versioning behavior (see Figure 2.6).

Autoincrement Major and Minor

Lets the plugin increments this values by you using the scheme. If not marked only the Build Number and Revision will increment.

Create date declarations

Create entries in the version.h file with dates and ubuntu style version.

Do Auto Increment

This tells the plugin to automatically increment the changes when a modification is made, this incrementation will occur before compilation.

Header language

Select the language output of version.h

Ask to increment

If marked, Do Auto Increment, it ask you before compilation (if changes has been made) to increment the version values.

svn enabled

Search for the svn revision and date in the current folder and generates the correct entries in version.h

Changes Log

This lets you enter every change made to the project to generate a ChangesLog.txt file (see Figure 2.7).

Show changes editor when incrementing version

Will pop up the changes log editor when incrementing the version.

Title Format

A format able title with a list of predefined values.

2.3.5  Including in your code

To use the variables generated by the plugin just #include <version.h>. An example code would be like the following:

#include <iostream> 
#include "version.h" 
 
void main(){ 
   std::cout<<AutoVersion::Major<<endl; 
}

Output of version.h

The generated header file. Here is a sample content of the file on c++ mode:

#ifndef VERSION_H 
#define VERSION_H 
 
namespace AutoVersion{ 
 
   //Date Version Types 
   static const char DATE[] = "15"; 
   static const char MONTH[] = "09"; 
   static const char YEAR[] = "2007"; 
   static const double UBUNTU_VERSION_STYLE = 7.09; 
 
   //Software Status 
   static const char STATUS[] = "Pre-alpha"; 
   static const char STATUS_SHORT[] = "pa"; 
 
   //Standard Version Type 
   static const long MAJOR = 0; 
   static const long MINOR = 10; 
   static const long BUILD = 1086; 
   static const long REVISION = 6349; 
 
   //Miscellaneous Version Types 
   static const long BUILDS_COUNT = 1984; 
   #define RC_FILEVERSION 0,10,1086,6349 
   #define RC_FILEVERSION_STRING "0, 10, 1086, 6349\0" 
   static const char FULLVERSION_STRING[] = "0.10.1086.6349"; 
 
} 
#endif //VERSION_h

On C mode is the same as C++ but without the namespace:

#ifndef VERSION_H 
#define VERSION_H 
 
   //Date Version Types 
   static const char DATE[] = "15"; 
   static const char MONTH[] = "09"; 
   static const char YEAR[] = "2007"; 
   static const double UBUNTU_VERSION_STYLE = 7.09; 
 
   //Software Status 
   static const char STATUS[] = "Pre-alpha"; 
   static const char STATUS_SHORT[] = "pa"; 
 
   //Standard Version Type 
   static const long MAJOR = 0; 
   static const long MINOR = 10; 
   static const long BUILD = 1086; 
   static const long REVISION = 6349; 
 
   //Miscellaneous Version Types 
   static const long BUILDS_COUNT = 1984; 
   #define RC_FILEVERSION 0,10,1086,6349 
   #define RC_FILEVERSION_STRING "0, 10, 1086, 6349\0" 
   static const char FULLVERSION_STRING[] = "0.10.1086.6349"; 
 
#endif //VERSION_h

2.3.6  Change log generator

This dialog is accessible from the menu ’Project’ →’Changes Log’ . Also if checked Show changes editor when incrementing version on the changes log settings, the window will open to let you enter the list of changes after a modification to the project sources or an incrementation event (see Figure 2.8).

Buttons Summary

Add

Appends a row in to the data grid

Edit

Enables the modification of the selected cell

Delete

Removes the current row from the data grid

Save

Stores into a temporary file (changes.tmp) the actual data for later processing into the changes log file

Write

Process the data grid data to the changes log file

Cancel

Just closes the dialog without taking any action

Here is an example of the output generated by the plugin to the ChangesLog.txt file:

03 September 2007 
   released version 0.7.34 of AutoVersioning-Linux 
 
    Change log: 
       -Fixed: pointer declaration 
       -Bug: blah blah 
 
02 September 2007 
   released version 0.7.32 of AutoVersioning-Linux 
 
    Change log: 
       -Documented some areas of the code 
       -Reorganized the code for readability 
 
01 September 2007 
   released version 0.7.30 of AutoVersioning-Linux 
 
    Change log: 
       -Edited the change log window 
       -If the change log windows is leave blank no changes.txt is modified

2.4  Browse Tracker

Browse Tracker is a plug-in that helps navigating between recently opened files in Code::Blocks.

The list of recent files is saved in a history. With the menu ’View’ →’Browse Tracker’ →’Clear All’ the history is cleared.

With the window ’Browsed Tabs’ you can navigate between the items of the recently opened files using the menu entry ’View’ →’Browse Tracker’ →’Backward Ed/Forward Ed’ or the shortcut Alt-Left/Alt-Right. The Browse Tracker menu is also accessible as context menu. The markers are saved in the layout file <projectName>.bmarks

A common procedure when developing software is to struggle with a set of functions which are implemented in different files. The BrowseTracks plug-in will help you solve this problem by showing you the order in which the files were selected. You can then comfortably navigate the function calls.

The plug-in allows even browse markers within each file in the Code::Blocks editor. The cursor position is memorized for every file. You can set this markers using the menu item ’View’ →’ Browse Tracker’ →’ Set BrowseMarks’ or with selecting a line with the left mouse button. A marker with … is shown in the left margin. With the menu ’View’ →’Browse Tracker’ →’Prev Mark/Next Mark’ or the shortcut Alt-up/Alt-down you can navigate through the markers within a file. If you want to navigate in a file between markers sorted by line numbers then just select the menu ’View’ →’Browse Tracker’ →’Sort BrowseMark’ .

With the ’Clear BrowseMark’ the marker in a selected line is removed. If a marker is set for a line, holding left-mouse button down for 1/4 second while pressing the Ctrl key will delete the marker for this line. Via the menu ’Clear All BrowseMarks’ or with a Ctrl-left click on any unmarked line will reset the markers within a file.

The settings of the plug-in can be configured via the menu ’Settings’ →’Editor’ →’Browse Tracker’ .

Mark Style

Browse Marks are displayed per default as … within the margin. With the setting ’Book_Marks’ they will be displayed like Bookmarks as blue arrow in the margin. With hide the display of Browse Marks is suppressed. Note : These options have been deleted recently from the plugin but are still present in older Code::Blocks versions. Only the blue arrow is still there.

Toggle Browse Mark key

Markers can be set or removed either by a click with the left mouse button or with a click while holding the Ctrl key.

Toggle Delay

The duration of holding the left mouse button to enter the Browse Marker mode.

Clear All BrowseMarks

while holding Ctrl key either by a simple or a double click with the left mouse button.

The configuration of the plug-in is stored in your application data directory in the file default.conf. If you use the personality feature of Code::Blocks the configuration is read from the file <personality>.conf.

2.5  CodeSnippets

The CodeSnippets plug-in makes it possible to structure text modules and links to files according to categories in a tree view. The modules are used for storing often used files and constructs in text modules and managing them in a central place. Imagine the following situation: A number of frequently used source files are stored in different directories of the file system. The CodeSnippets window provides the opportunity to create categories, and below the categories, links to the required files. With these features, you can control the access to the files independently from where they are stored within the file system, and you can navigate quickly between the files without the need to search the whole system.

The list of text modules and links can be stored in the CodeSnippets window by right-clicking and selecting ’Save Index’ from the context menu. The file codesnippets.xml which will be created by this procedure, can then be found in the codeblocks subdirectory of your Documents and Settings∖Application data directory in Win 7 (or an equivalent path in the user profile, adapted to each OS). Under Linux, this information is stored in the .codeblocks subdirectory of your HOME directory. The Code::Blocks configuration files will be loaded during the next start-up. If you wish to save the content of CodeSnippets at a different location, select the ’Save Index As’ entry. To load this file, select ’Load Index File’ during the next start-up of Code::Blocks or include the directory in the ’Settings’ context menu under ’Snippet Folder’. The settings are saved in the corresponding file codesnippets.ini in your application data.

For including a category, use the ’Add SubCategory’ menu. A category can contain Snippets (text modules) or File Links. A text module is created via the ’Add Snippet’ command in the context menu. The content is integrated into the text module as ’New snippet’ by selecting the text passage in the Code::Blocks editor and dragging and dropping it onto the module and the properties dialog pops up. Double-clicking the newly included entry or selecting ’Edit Text’ will open an editor for the content.

Output of a text module is handled in Code::Blocks via the context menu command ’Apply’ or by dragging and dropping into the editor. Under Windows, the contents of a Snippet can also be dragged and dropped into other applications. In the CodeSnippets Browser you can copy a selected item with drag and drop to a different category.

Beyond this, text modules can be parametrised by <name> variables which can be accessed via $(name) (see Figure 2.9). The values of the variables can be retrieved in an entry field if the text module is called via the context menu command ’Apply’.

Besides the text modules, links to files can also be created. If, after having created a text module, you click the context menu command ’Properties’, then you can select the link target by clicking the ’Link target’ button. This procedure will automatically convert the text module into a link to a file. In CodeSnippets, all text modules will be marked by a T symbol, links to a file by an F symbol and urls by an U symbol. If you want to open a selected file (link) in the codesnippets view just select the context menu ’Open File’ or hold the ’Alt’ key and make a double click on the file.

With this setting, if open a link to a pdf file from the codesnippets view a pdf viewer will be started automatically. This method makes it possible for a user to access files which are spread over the whole network, such as cad data, layouts, documentations etc., with the common applications, simply via the link. The content of the codesnippets is stored in the file codesnippets.xml, the configuration is stored in the file codesnippets.ini in your application data directory. This ini file will, for example, contain the path of the file codesnippets.xml.

Code::Blocks supports the usage of different profiles. These profiles are called personalities. Starting Code::Blocks with the command line option --personality=<profile> will create a new or use an existing profile. Then the settings will not be stored in the file default.conf, but in <personality>.conf in your application data directory instead. The Codesnippets plugin will then store its settings in a specific file named <personality>.codesnippets.ini. Now, if you load a new content <name.xml> in the Codesnippets settings via ’Load Index File’, this content will be stored in the corresponding ini file. The advantage of this method lies in the fact that in case of different profiles, different configurations for text modules and links can be managed.

The plug-in offers an additional search function for navigating between the categories and Snippets. The scope for searching Snippets, categories or Snippets and categories can be adjusted. By entering the required search expression, the corresponding entry is automatically selected in the view. Figure 2.10 shows a typical display in the CodeSnippets window.

2.6  Code Completion in Code::Blocks

Two plugins which provide code completion functionality and class browser. They are not compatible with each other. Only one of both can be activated.

2.6.1  Code Completion plugin

CodeCompletion provides a symbols browser for your projects and code-completion inside the editor. During code-completion, a system of symbols is used to identify the type associated with the suggested tokens; these symbols are defined in the following table.

Note: This is the user document of Code Completion plugin. Only C/C++ language is supported by this plugin (currently)...

2.6.2  CB Clangd Client

This plugin provides code completion functionality and class browser by Clangd through LSP (Language Server Protocol).

The home page of this plugin is: https://sourceforge.net/projects/cb-clangd-client/

The main developer is Pecan.

The related forum discussion is: Code completion using LSP and clangd
(https://forums.codeblocks.org/index.php/topic,24357.msg166136.html)

This documentation is extracted from the wiki: https://wiki.codeblocks.org/index.php/CB_Clangd_Client

2.6.2.1 What is Clangd

clangd understands your C++ code and adds smart features to your editor:

• code completion

• compile errors

• go-to-definition

• go-to-implementation

• find references

and more.

clangd is a language server that can work with your editor via a plugin.
Code::Blocks provides Clangd_client as the needed plugin.

Clangd_client additionally enhances the clangd server by providing:

• call tips

• function definitions

• parameter definitions

• previous and next function positioning

• symbols browser

• go-to-file

• go-to-function

• symbol renaming

2.6.2.2 Configuring clangd_client

Clangd_client requires the third-party binary clangd executable.

See Windows: Compiler Clangd/LLVM Package Installer below (2.6.2.5) to install it, or Linux: Clangd executable install process (see 2.6.2.6)

After a successful clangd executable install, perform the following:

• Disable the ”CodeCompletion” plugin.

• Navigate to ’Plugins’ →’ Manage Plugins’ and disable CodeCompletion.

• Navigate to ’Plugins’ →’ Manage Plugins’ and enable Clangd_client.

Restart Code::Blocks.

Tell (or verify) Code::Blocks where the clangd executable resides:

Navigate to ’Setting’ →’ Editor’ →’ Clangd_client’ →’ C/C++ parser(tab)’ and verify the location of the clangd executable in the box labeled ”Specify clangd executable to use”.

2.6.2.3 Installing Clangd_client from source or pre-built binary

1.

Install the LLVM or Clangd.exe as documented in the section below entitled:
Windows Clangd executable install process (see section 2.6.2.5)

2.

Disable the Code completion plugin as follows:

a)

Open the Plugin manager via Code::Blocks menu
’MainMenu’ →’ Plugins’ →’ Manage plugins...’

b)

In the Manage Plugin dialog do the following:

i.

Find and select the ”Code completion” plugin via it’s title

ii.

Press the ”Disable” button on the right near the top

iii.

If you get any errors please try again.

3.

Install the Clangd-Client Plugin using one of the following options, which are documented below:

a)

Install via the Plugin Manager

b)

Manually install the plugin files

4.

Configure the Clangd-Client Plugin for use as follows:

a)

Select the Code::Blocks menu item ’Settings’ →’ Editor...’

b)

In the list on the left click/select the ”clangd_client” option.

c)

In the ”C/C++ parser” tab change the ”Specify clangd executable to use” to reference the clangd.exe you installed via step 1) above.
Some examples of this could be:

               C:\msys64\clang64\bin\clangd.exe
               C:\msys64\clang32\bin\clangd.exe
               C:\LLVM\bin\clangd.exe
               C:\compilers\clang\clangd.exe
               

2.6.2.4 Manually Remove Clangd-Client Plugin

1.

Exit Code::Blocks!

2.

If you manually installed the files or used the Plugin manager then you can do the following:

a)

In the Code::Blocks ...∖share∖CodeBlocks folder delete the clangd_client.zip file

b)

In the Code::Blocks ...∖share∖CodeBlocks∖plugins folder delete the clangd_client.dll file

3.

If you installed via the Plugin manager then you can delete the files with the following commands:

a)

del %APPDATA%∖CodeBlocks∖share∖codeblocks∖plugins∖clangd_client.dll

b)

del %APPDATA%∖CodeBlocks∖share∖codeblocks∖clangd_client.zip

4.

If you want to reuse older code completion remember to re-enable the plugin

2.6.2.5 Windows: Clangd executable install process

There are three main options to install the clangd.exe:

1.

Install the LLVM compiler.

2.

Manully extract the required files from the LLVM compiler.

3.

Install the Clangd package for the Windows compiler you are using if it is available.

The process for the three options above are detailed below.

Windows: Install the LLVM compiler

1.

Download the latest (non RC/Beta) LLVM Windows executable for your OS (Win32 or Win64) from the following Github LLVM download page:
https://github.com/llvm/llvm-project/releases

As of Jan 2022 the Windows files are names as follows:

           LLVM-<version>-win64.exe
           LLVM-<version>-win32.exe
        

where <version> is the LLVM version, like 13.0.0 or 13.0.1.

2.

Run the LLVM-<version>-win<xx>.exe you downloaded to install the LLVM compiler.

Windows: Manually Extract File from LLVM compiler

1.

Download the latest (non RC/Beta) LLVM Windows executable for your OS (Win32 or Win64) from the following Github LLVM download page:
https://github.com/llvm/llvm-project/releases

As of Jan 2022 the Windows files are names as follows:

           LLVM-<version>-win64.exe
           LLVM-<version>-win32.exe
        

where <version> is the LLVM version, like 13.0.0 or 13.0.1.

2.

Unzip the LLVM-<version>-win<xx>.exe file you downloaded using 7ZIP or your prefered ZIP program into a sub-directory

3.

Create a new directory to put the clangd.exe and dll’s

4.

Copy the following files into a the new directory created from the unziped LLVM directory:

          bin\clangd.exe
          bin\msvcp140.dll
          bin\vcruntime140.dll
          bin\vcruntime140\_1.dll
          

Windows: Compiler Clangd/LLVM Package Installer i)
Due to the number of different compilers available for Windows not all of the compilers will have either/both the Clang or LLVM required files. If you want to install the specific package(s) for the Windows compiler you are using in order to use it’s clangd.exe file please follow the instructions below for the specific compiler you have installed:

MSYS2 Compiler - MinGW64
There are two main options to install the clangd.exe as follows:

1.

The first option in order to minimise disk space is to install the Clang extra tools using one of the following packages:

To intall the package do the following:

a)

Open the msys2.exe bash shell

b)

Run the following command:
pacman -S <Package name in the table above>

”OR”

2.

The second option is to intall the full Clang tool chain as follows:

a)

Open the msys2.exe bash shell

b)

Run the following command: pacman -S mingw-w64-clang-x86_64-toolchain

MSYS2 Compiler - MinGW32
There are two main options to install the clangd.exe as follows:

1.

The first option in order to minimise disk space is to install the Clang extra tools using one of the following packages:

To intall the package do the following:

a)

Open the msys2.exe bash shell

b)

Run the following command:
pacman -S <Package name in the table above>

”OR”

2.

The second option is to install the full Clang tool chain as follows:

a)

Open the msys2.exe bash shell

b)

Run the following command:
pacman -S mingw-w64-clang-i686-toolchain

_______________________________________________________________________________________
Notes from the Code::Blocks forum to avoid mixing incompatible gcc/clangd executables.
_______________________________________________________________________________________
https://forums.codeblocks.org/index.php/topic,24357.msg169412.html#msg169412

Don’t mix mingw64 with clang64.

If you are using the gcc from msys2, (the compilers in the folder ”msys64∖mingw64∖bin”), you should use ”mingw-w64-x86_64-clang-tools-extra”, (the clangd.exe is under the folder ”msys64∖mingw64∖bin”) the same folder as your gcc.exe.

If you are using the clang tool chain, (the folder ”msys64∖clang64∖bin”), you should use ”mingw-w64-clang-x86_64-clang-tools-extra”.

I found that I just make a big mistake: that is I use the gcc toolchain from ”msys64∖mingw64∖bin”, but I use the clangd.exe from ”msys64∖clang64∖bin”. The result is I got a lot of LSP diagnostics messages and errors.
Luckily I found the reason, and fix this issue. Hope this will help other guys.

2.6.2.6 Linux: Clangd executable install process

NOTE: Clangd_client plugin requires a clangd executable version 13 or greater.

Check your current clangd version by running clangd --version.
If the version is less than 13 you will have to install a newer version.

See https://clangd.llvm.org/installation.html

Installing the clangd package will usually give you a slightly older version.
Test this by issuing apt-get install --dry-run clangd

As of 2022/11/16, this suggest that clangd version 10 will be installed.
If the clangd version shows less than version 13, you’ll have to install a specific version as follows:

Install a packaged release (must be version 13 or greater):

sudo apt-get install clangd-13 (Must be version 13 or greater).

This will install clangd as /usr/bin/clangd-13.

You can now configure clangd_client plugin by following the above instructions at Configuring clangd_client (see section 2.6.2.2

If you prefer to install the entire LLVM/Clang package, for convenience, there is an automatic installation script available that installs LLVM for you.

To install the latest stable version: see https://apt.llvm.org/, Automatic installation script. Note that you can specify the version number with this script.

2.7  CScope

This paragraph is extracted from the cscope plugin in the wiki.

2.7.1  General information

This plugin integrates the source code searching features of Cscope into Code::Blocks (a Windows build is available at Cscope-win32). Cscope is especially useful on large projects, and can search for:

• all references to a symbol

• global definitions

• functions called by a function

• functions calling a function

• text string

• regular expression pattern

• a file

• files including a file

Although the parser within Cscope is targeted at C, it retains enough flexibility to provide functionality with C++ (and Java) code.

2.7.2  Installing CScope

These instructions are for Code::Blocks SVN Version >11828.

2.7.2.1 Linux

Under Linux installing cscope should be as easy as calling your favorite package manager and installing cscope. Code::Blocks should find the executable by default. If it can not find the cscope executable please set it in ’Settings’ →’Environment’ →’CScope’ . You can find the path to the cscope executable by typing locate cscope in your favorite terminal.

2.7.2.2 Windows

It is hard to find a precompiled binary for cscope on windows. The easiest solution is to install msys2. Follow the instruction on the website [ MSys2] to install msys2. After installing and updating as described open the msys terminal and type pacman -S cscope. This will install cscope from the global package repository.

Now you have to setup Code::Blocks:

• Open Code::Blocks

• ’Settings’ →’Environment’ →’CScope’

• Press the button with the ... dots

• Search the cscope.exe executable. It is probably under
  INSTALL_DIRECTORY_OF_MSYS2∖usr∖bin∖cscope.exe

• Close the dialog with OK

• Now you should be able to use the cscope functions in Code::Blocks (for ex. ”Find functions calling XXXX”).

2.8  Doxyblocks

DoxyBlocks is a plugin for Code::Blocks that integrates doxygen into the IDE. It allows you to create documentation, insert comment blocks and run HTML or CHM documents. It also provides configuration of some of the more commonly used settings and access to doxywizard for more detailed configuration.

The settings in the DoxyBlocks toolbar have the following meanings:

class="description">

Run doxywizard. Ctrl-Alt-D

class="description">

Extract documentation for the current project. Ctrl-Alt-E

class="description">

Insert a comment block at the current line. Additionally, DoxyBlocks will try to intelligently read if a method exists on the line for which a comment is being added. Ctrl-Alt-B

/** \brief 
 * 
 * \param bar bool 
 * \return void 
 * 
 */ 
void MyClass::Foo(bool bar) 
{ 
   fooBar(bar); 
}

class="description">

Insert a line comment at the current cursor position. Ctrl-Alt-L

void MyClass::Foo(bool bar) 
{ 
   fooBar(bar); /**<  */ 
}

class="description">

View generated HTML documentation. Ctrl-Alt-H

class="description">

View generated HTML Help documentation. Ctrl-Alt-C

class="description">

Open DoxyBlocks’ preferences. Ctrl-Alt-P

Doxyblocks works only if doxygen is installed on your system. You need at least the executables doxygen and doxywizard (available in official doxygen distribution at https://www.doxygen.nl/). Optionally you can have the executable ”dot” from the graphviz package (see https://graphviz.gitlab.io/. On Windows, the help compiler (hhc) may be used to generate chm files.

Notes

In the preferences you have a check box to allow or not allow DoxyBlocks to overwrite the doxyfile. By default, if a doxyfile already exists it is not overwritten to protect any changes that have been made outside DoxyBlocks however this behaviour prevents changes made within DoxyBlocks being written to an existing doxyfile.

If a text field is blank in ”Preferences”, DoxyBlocks will assume that the corresponding executable is available somewhere in your environment’s path. You can use macros such as $(CODEBLOCKS) in your path and they will be expanded automatically.

OUTPUT_DIRECTORY

Used to specify the (relative or absolute) base path where the generated documentation will be put. If a relative path is entered, it will be relative to the location where doxygen was started. If left blank the current directory will be used. DoxyBlocks will use the path name entered here to create a directory relative to <project dir>. This allows you to create separate doxygen directories for projects that reside in the same directory, or just use a different directory name. If this field is blank, documents will be created in <project dir>/doxygen. Enter directory names without dots, leading separators, volume names, etc. DoxyBlocks does validation on the path name and will strip extraneous characters.

Examples: 
[blank]          -> <project dir>/doxygen. 
"docs"           -> <project dir>/docs. 
"docs/sub1/sub2"  -> <project dir>/docs/sub1/sub2. 
"doxygen/docs"    -> <project dir>/doxygen/docs.

OUTPUT_LANGUAGE

Used to specify the language in which all documentation generated by doxygen is written. Doxygen will use this information to generate all constant output in the proper language. The default language is English. Other languages are supported.

More information in doxygen help files

2.9  Editor Tweaks plugin

The EditorTweaks plugin contains several different features. On a per-file basis, it controls:

• word-wrap;

• line-numbers;

• tab key emissions (tab characters or spaces);

• number of spaces the tab key emits;

• end of line characters (carriage-return + linefeed; carriage-return; linefeed);

• visibility of end of line characters;

• on-demand striping of trailing white-space;

• on-demand synchronization of end of line characters;

• insert key suppression.

From the merge with the Aligner plugin, it has the ability to make sections of code more readable by aligning a specific character.
For example, aligning the ”=” in

int var = 1; 
int longVarName = 2; 
int foobar = 3;

will result in:

int var        = 1; 
int longVarName = 2; 
int foobar     = 3;

2.10  Environment Variables plugin

From Code::Blocks wiki. See also section 1.11.3.

Environment variables editor plugin allows for the setting of system environment variables in the focus of Code::Blocks.
A user can have several sets that contain 1..n environment variables.
A user can switch between these sets within the environment variables configuration dialog.
In addition the EnvVars plugin offers an option to projects (within project setup) to apply a certain EnvVar set to activate (and use during compilation).

The dialog for editing the sets is located in ’Settings’ →’Environment’ →’Environment variables’ .
The dialog for choosing the active set for the current project is located in ’Project’ →’Properties’ →’EnvVar options’ .

Script binding

This plugin provides its functionality through a squirrel binding:

NOTE: The value arguments are automatically expanded from macros. You do not have to call ReplaceMacros() on them.

Many other script functions are available. Have a look to https://wiki.codeblocks.org/index.php/Scripting_commands

Example

On windows in the post or pre build steps:

[[EnvvarApply(_("test"),_("testValue"));]] 
echo %test%

2.11  FileManager and PowerShell Plugin

The File Explorer Figure 2.13 is included in the FileManager plugin, and can be found in the ’Files’ tab. The composition of the File Explorer is shown in Figure 2.13.

On top you will find a field for entering the path. By clicking the button at the end of this field, the drop-down field will list a history of the past entries which can be navigated via a scroll bar. The up arrow key on the right-hand side of the field moves up the directory structure one directory.

In the ’Wildcard’ field you can enter a filter term for the file display. Leaving the field empty or entering * results in all files being displayed. Entering *.c;*.h, for example will result in solely C sources and header files being displayed. Opening the pull-down field will, again, list a history of the last entries.

Pressing the Shift key and clicking selects a group of files or directories, pressing the Ctrl key and clicking selects multiple separate files or directories.

The following operations can be started via the context menu if one or multiple directories are selected in the File Explorer:

Make Root

defines the current directory as the root directory.

Add to Favorites

sets a marker for the directory and stores it as a favourite. This function allows you to navigate quickly between frequently used directories, also on different network drives.

New File

creates a new file in the selected directory.

New Directory

creates a new subdirectory in the selected directory.

The following operations can be started via the context menu if one or multiple files or directories are selected in the File Explorer:

Duplicate

copies a file/directory and renames it.

Copy To

opens a dialogue for entering the target directory in which the copied file/directory is to be stored.

Move To

moves the selection to the target location.

Delete

deletes the selected files/directories.

Show Hidden Files

activates/deactivates the display of hidden system files. When activated, this menu entry is checkmarked.

Refresh

update the display of the directory tree.

The following operations can be started via the context menu if one or multiple files are selected in the File Explorer:

Open in CB Editor

opens the selected file in the Code::Blocks editor.

Rename

renames the selected file.

Add to active project

adds the file(s) to the active project.

User-defined functions can be specified via the menu command ’Settings’ →’Environment’ →’PowerShell’ . In the PowerShell mask, a new function which can be named at random, is created via the ’New’ button. In the ’ShellCommand Executable’ field, the executable program is stated, and in the field at the bottom of the window, additional parameters can be passed to the program. By clicking the function in the context menu or the PowerShell menu, the function is started and will then process the selected files/directories. The output is redirected to a separate shell window.

For example a menu entry in ’PowerShell’ →’SVN’ and in the context menu is created for ’SVN’. $file in this context means the file selected in the File Explorer, $mpath the selected files or directories (see section 3.2).

 Add;$interpreter add $mpaths;;;

This and every subsequent command will create a submenu, in this case called ’Extensions’ →’SVN’ →’Add’ . The context menu is extended accordingly. Clicking the command in the context menu will make the SVN command add process the selected files/directories.

TortoiseSVN is a widespread SVN program with integration in the explorer. The program TortoiseProc.exe of TortoiseSVN can be started in the command line and dispalys a dialogue to collect user input. So you can perform the commands, that are available as context menu in the explorer also in the command line. Therefore you can integrate it also a shell extension in Code::Blocks. For example the command

TortoiseProc.exe /command:diff /path:$file

will diff a selected file in the Code::Blocks file explorer with the SVN base. See Figure 2.14 how to integrate this command.

Example

You can use the file explorer to diff files or directories. Follow these steps:

1.

Add the name via menu ’Settings’ →’Environment’ →’PowerShell’ . This is shown as entry in the interpreter menu and the context menu.

2.

Select the absolute path of Diff executable (e.g. kdiff3). The program is accessed with the variable $interpreter.

3.

Add parameters of the interpreter

Diff;$interpreter $mpaths;;;

This command will be executed using the selected files or directories as parameter. The selection is accessed via the variable $mpaths. This is an easy way to diff files or directories.

$interpreter

Call this executable.

$fname

Name of the file without extension.

$fext

Extension of the selected file.

$file

Name of the file.

$relfile

Name of the file without path info.

$dir

Name of the selected directory.

$reldir

Name of directory without path info.

$path

Absolute path.

$relpath

Relative path of file or directory.

$mpaths

List of current selected files or directories.

$inputstr{ msg }

String that is entered in a message window.

$parentdir

Parent directory (../).

2.12  HexEditor

How a file can be opened in HexEditor within Code::Blocks.

1.

’File’ →’ Open with HexEditor’

2.

Project Navigator context menu (’Open with’ →’ Hex editor’

3.

Select the Tab Files in the Management Panel. By selecting a file in the FileManager and executing the context menu ’Open With Hex editor’ this file is opened in HexEditor.

Division of windows:

left is HexEditor view and right is the display as strings

Upper line: Current position (value in decimal/hex) and percentage (ratio of current cursor position to whole file).

Buttons:

Search functions

Goto Button: Jump to an absolute position. Format in decimal or hex. Relative jump forward or backward by specifying a sign.

Search: Search for hex patterns in the HexEditor view or for strings in the file preview.

Configuration of the number of columns: Exactly, Multiple of, Power of

Display mode: Hex, Binary

Bytes: Select how many bytes should be displayed per column.

Choice of Endianess: BE: Big Endian LE: Little Endian

Value Preview: Adds an additional view in HexEditor. For a selected value in HexEditor, the value is also displayed as Word, Dword, Float, Double.

Expression Input: Allows you to perform an arithmetic operation on a value in HexEditor. Result of the operation is displayed at the right margin.

Calc: Expression Tester

Editing a file in the HexEditor:

Includes Undo and Redo History.

For example, move the cursor to the string view: Insert spaces with the Insert key. Delete characters by pressing the Del key.

By entering a text, the existing content is overwritten as a string.

By entering numbers in the HexEditor view the values are overwritten and the preview is updated.

2.13  Incremental Search

For an efficient search in open files, Code::Blocks provides the so-called Incremental Search. This search method is initiated for an open file via the menu ’Search’ →’Incremental Search’ or by the keyboard shortcut Ctrl-I. The focus is then automatically set to the search mask of the corresponding toolbar. As soon as you begin entering the search term, the background of the search mask will be adjusted in accordance with the occurrence of the term. If a hit is found in the active editor, the respective position in the text is marked in colour. By default the current hit will be highlighted in green. This setting can be changed via ’Settings’ →’ Editor’ →’ Incremental Search’ (see Figure 2.15). Pressing the Return key induces the search to proceed to the next occurrence of the search string within the file. With Shift-Return the previous occurrence can be selected. This functionality is not supported by Scintilla if the incremental search uses regular expressions.

If the search string cannot be found within the active file, this fact is highlighted by the background of the search mask being displayed in red.

ESC

Leave the Incremental Search modus.

ALT-DELETE

Clear the input of the incremental search field.

The icons in the Incremental Search toolbar have the following meanings:

class="description">

Deleting the text within the search mask of the Incremental Search toolbar.

class="cmssbx-10x-x-120">, class="description">

Navigating between the occurrences of a search string.

class="description">

Clicking this button results in all the occurrences of the search string within the editor being highlighted in colour, instead of only the initial occurrence.

class="description">

Activating this option restricts the search to the text passage marked within the editor.

class="description">

This option means a case sensitive search is performed.

class="description">

Regular expression can be used in the input field of incremental search.

2.14  NassiShneiderman plugin

NassiShneiderman plugin allows the creation of Nassi Shneiderman diagrams within Code::Blocks ([ NassiShneiderman]).

2.14.1  Create a diagram

There are two possibilities to create a diagram.

1.

To create an empty diagram select the menu options ’File’ →’New’ →’Nassi Shneiderman diagram’ .

2.

The second option is to creates a diagram from C/C++ source code.

In an editor window highlight some code to create the diagram from. For example the body of a function/method from the opening braces till the closing brace. Then right click the selection and choose ’Nassi Shneiderman’ →’Create diagram’ (see Figure 2.16).

You should get a new diagram (see Figure 2.17).

The parser has some limitations:

• Comments can not be at the end of a branch.

• From a definition of a function it is only able to parse the body, not the declaration.

• For sure, you will find a lot more...

2.14.2  Editing structograms

2.14.2.1 What to do with a diagram?

You can do a lot of things with a structogram:

1.

Store for later usage. The diagram can be stored ’File’ →’Save file’ or ’File’ →’Save file as...’ .

2.

It is possible to export to different formats ’File’ →’Export’

• ”Export source...” to save as C source file.

• ”StrukTeX” to use in your documentation in LaTeX.

• ”PNG” or ”PS” and eventually ”SVG” to have a diagram in an image format known by a lot of other tools.

3.

Directly insert the code into the editor: Open or create a diagram. Back in an editor window right click and choose ’Nassi Shneiderman’ →’insert from xy’ (You get a list with all open diagrams here).

4.

Drag’n’Drop the diagram (or parts of it) to other tools. For example to OpenOffice Writer to get an image in your documentation.

If the chosen diagram has a selection, the export or code-generation takes only this part of the diagram.

2.14.2.2 Extensions

The NassiShneiderman plugin supports some extensions of Nassi-Shneiderman diagrams:

• break has a special brick with an ”right-arrow”

• continue has a special brick with a ”left-arrow”

• To be able to create diagrams from c/c++ switch statements, the selection does not implicitly break before a case. The different cases are vertically aligned. Supports C and C++.

2.15  LibFinder

If you want to use some libraries in your application, you have to configure your project to use them. Such configuration process may be hard and annoying because each library can use custom options scheme. Another problem is that configuration differs on platforms which result in incompatibility between unix and windows projects.

LibFinder provides two major functionalities:

• Searching for libraries installed on your system

• Including library in your project with just few mouse clicks making project platform-independent

2.15.1  Searching for libraries

Searching for libraries is available under ’Plugins’ →’Library finder’ menu. It’s purpose is to detect libraries installed on your system and store the results inside LibFinder’s database (note that these results are not written into Code::Blocks project files). Searching starts with dialogue where you can provide set of directories with installed libraries. LibFinder will scan them recursively so if you’re not sure you may select some generic directories. You may even enter whole disks – in such case searching process will take more time but it may detect more libraries (see Figure 2.18).

When LibFinder scans for libraries, it uses special rules to detect presence of library. Each set of rules is located in xml file. Currently LibFinder can search for wxWidgets 2.6/2.8, Code::Blocks SDK and GLFW – the list will be extended in future.

After completing the scan, LibFinder shows the results (see Figure 2.19).

In the list you check libraries which should be stored into LibFinder’s database. Note that each library may have more than one valid configuration and settings added ealier are more likely to be used while building projects.

Below the list you can select what to do with results of previous scans:

Do not clear previous results

This option works like an update to existing results – it adds new ones and updates those which already exist. This option is not recommended.

Second option (Clear previous results for selected libraries)

will clear all results for libraries which are selected before adding new results. This is the recommended option.

Clear all previous library settings

when you select this option, LibFinder’s database will be cleared before adding new results. It’s useful when you want to clean some invalid LibFinder’s database.

Another option in this dialogue is ’Set up Global Variables’ . When you check this option, LibFinder will try automatically configure Global Variables which are also used to help dealing with libraries.

If you have pkg-config installed on your system (it’s installed automatically on most linux versions) LibFinder will also provide libraries from this tool. There is no need to perform scanning for them – they are automatically loaded when Code::Blocks starts.

2.15.2  Including libraries in projects

LibFinder adds extra tab in Project Properties ’Libraries’ – this tab shows libs used in project and libs known in LibFinder. To add library into your project, select it in right pane and click < button. To remove library from project, select it on the left pane and click > button (see Figure 2.20).

You can filter libraries known to LibFinder by providing search filter. The ’Show as Tree’ checkbox allows to switch between categorized and uncategorized view.

If you want to add library which is not available in LibFinder’s database, you may use ’Unknown Library’ field. Note that you should enter library’s shortcode (which usually matches global variable name) or name of library in pkg-config. List of suggested shortcodes can be found at Global Variables. Using this option is recommended only when preparing project to be built on other machines where such library exists and is properly detected by LibFinder. You can access a global variable within Code::Blocks like:

$(#GLOBAL_VAR_NAME.include)

Checking the ’Don’t setup automatically’ option will notify LibFinder that it should not add libraries automatically while compiling this project. In such case, LibFinder can be invoked from build script. Example of such script is generated and added to project by pressing ’Add manual build script’ .

2.15.3  Using LibFinder and projects generated from wizards

Wizards will create projects that don’t use LibFinder. To integrate them with this plugin, you will have to manually update project build options. This can be easily achieved by removing all library-specific settings and adding library through ’Libraries’ tab in project properties.

Such project becomes cross-platform. As long as used libs are defined in LibFinder’s database, project’s build options will be automatically updated to match platform-specific library settings.

2.16  SpellChecker plugin

A plugin to check the spelling of strings and comments.

2.16.1  Introduction

A plugin to check the spelling of strings and comments. The spelling gets checked during typing. Additionally a thesaurus is provided. Both may be accessed on-demand by selecting the word in question, then choosing either Spelling... or Thesaurus... from the Edit menu (the operation can be bound to a hot-key via the Keyboard Shortcuts plugin). The context menu (right click the word) provides spelling suggestions.

2.16.2  Configuration

Configuration is in the menu ’Settings’ →’Editor’ . The spell check option are about half way down the list on the left.

The meaning of the controls are:

Enable online spell checker

Enable or disable the spell checker.

Language

The language used for spell checking and the thesaurus is selected by choosing a dictionary. This can also be changed in the status bar.

Path settings, Dictionaries

The plugin is looking in this path for the dictionary files.

Path settings, Thesauri

The plugin is looking in this path for the files needed by the thesaurus.

Path settings, Bitmaps

(Optional) The plugin is looking in this path for the flags to show in the status bar.

2.16.3  Dictionaries

SpellChecker uses a library called hunspell. Hunspell is the spell checker of OpenOffice.org, Mozilla Firefox and other projects. Dictionaries available for those applications are compatible with this plugin.

Open Office provides a collection of dictionaries for several languages and dialects to download. The OOo 3.x extensions (*.oxt) are compressed archives which can be opened with your favourite archiver (for example 7-Zip or File Roller). Copy the .aff file and the .dic file to the directory configured in ’Path settings, Dictionaries’ (see above).

If you’re running Linux you’ve probably already got compatible dictionaries installed. Look in /usr/share/hunspell or my choice is /usr/share/myspell/dicts. The reason I like the myspell files is they already include thesaurus files which are named correctly to work with the thesaurus, and everything is all in one location. Don’t copy these files. Just point the spell checker to where the files are already located.

I understand on Windows, Firefox and Thunderbird also install compatible dictionary files. These can be found in... C:∖Program Files∖Mozilla Firefox∖dictionaries or C:∖Program Files∖Mozilla Thunderbird∖dictionaries. In addition, both OpenOffice.org and LibreOffice install dictionary files to
C:∖Program Files∖(Open/Libre)Office∖share∖extensions∖dict-*.

The Google Chrome browser also installs dictionaries, but they are .bdic format and the Code::Blocks spell checker plugin will not work with them.

2.16.4  Thesaurus files

The files for the thesaurus are also available from OOo, like the dictionaries. Copy the thesaurus files (th_*.dat and th_*.idx) to the directory configured in ’Path settings, Thesauri’ (see above) and rename them to match the name of the dictionary but prepend ”th_” and let the extension as is.

Example: If the dictionary files (for one language) are ”en_GB.aff” and ”en_GB.dic” the files used for the thesaurus are ”th_en_GB.idx” and ”th_en_GB.dat”.

On my Linux system I found thesaurus files already installed in /usr/share/myspell/dicts and /usr/share/mythes. Again, don’t move the files. Set the spell checker to use the files from their current location.

On Windows, if either OpenOffice.org or LibreOffice is installed, they often include thesaurus files in C:∖Program Files∖(Open/Libre)Office∖share∖extensions∖dict-*.

2.16.5  Bitmaps (flags)

The bitmap of the actually selected language is shown in the status bar. If no bitmap is found, the name of the language is shown. The bitmap must be a PNG image. Choose a flag from the famfamfam_flag_icons and copy it to the directory configured in ’Path settings, Bitmaps’ (see above) and rename it to match the name of the dictionary but let the extension png.

2.16.6  Styles to check

Only text with specific styles gets checked (for example only comments and strings). Styles are automatically set by Scintilla (CodeBlocks editing component).

The file OnlineSpellChecking.xml contains a list with indices of the styles to check. The indices differ for different programming-languages so the file contains a list for every programming-language. To add styles, look for the name of the programming-language and the indices in the corresponding lexer_*.xml file and add this information to the file OnlineSpellChecking.xml.

For example, to check the spelling in bash shell scripts (*.sh files), add the line:

<Language name="Bash"index="2,5,6"/>

2.17  Source Code Exporter

The necessity occurs frequently of transferring source code to other applications or to e-mails. If the text is simply copied, formatting will be lost, thus rendering the text very unclear. The Code::Blocks export function serves as a remedy for such situations. The required format for the export file can be selected via ’File’ →’Export’ . The program will then adopt the file name and target directory from the opened source file and propose these for saving the export file. The appropriate file extension in each case will be determined by the export format. The following formats are available.

html

A text-based format which can be displayed in a web browser or in word processing applications.

rtf

The Rich Text format is a text-based format which can be opened in word processing applications such as Word or OpenOffice.

odt

Open Document Text format is a standardised format which was specified by Sun and O’Reilly. This format can be processed by Word, OpenOffice and other word processing applications.

pdf

The Portable Document Format can be opened by applications such as the Acrobat Reader.

2.18  SVN Support

The support of the version control system SVN is included in the Code::Blocks plugin TortoiseSVN. Via the menu ’TortoiseSVN’ →’Plugin settings’ you can configure the accessible svn commands in the tab ’Integration’ .

Menu integration

Add an entry TortoiseSVN with different settings in the menu bar.

Project manger

Activate the TortoiseSVN commands in the context menu of the project manager.

Editor

Active the TortoiseSVN commands in the context menu of the editor.

In the plugin settings you can configure which svn commands are accessible via the menu or the context menu. The tab integration provides the entry ’Edit main menu’ and ’Edit popup menu’ to configure these commands.

2.19  ToDo List

In complex software projects, where different users are involved, there is often the requirement of different tasks to be performed by different users. For this purpose, Code::Blocks offers a Todo List. This list can be opened via ’View’ →’To-Do list’ , and contains the tasks to be performed, together with their priorities, types and the responsible users. The list can be filtered for tasks, users and/or source files. A sorting by columns can be achieved by clicking the caption of the corresponding column.

If the sources are opened in Code::Blocks, a Todo can be added to the list via the context menu command ’Add To-Do item’. A comment will be added in the selected line of the source code.

// TODO (user#1#): add new dialog for next release

When adding a To-Do, a dialogue box will appear where the following settings can be made (see Figure 2.23).

User

User name <user> in the operating system. Tasks for other users can also be created here. In doing so, the corresponding user name has to be created by Add new. The assignment of a Todo is then made via the selection of entries listed for the User.

Note:
Note that the Users have nothing to do with the Personalities used in Code::Blocks.

Type

By default, type is set to Todo.

Priority

The importance of tasks can be expressed by priorities (1 - 9) in Code::Blocks.

Position

This setting specifies whether the comment is to be included before, after or at the exact position of the cursor.

Comment Style

A selection of formats for comments (e.g. doxygen).

2.20  Tools+

Creating a new tool is fairly simple, and can be completed in a few simple steps. First open ’Tools(+)’ →’Configure Tools...’ to access the User-defined Tools dialog.

Tool Name

This is the name that will be displayed in the Tools(+) drop-down menu. It will also be displayed as the tab name for tools that redirect to the Tools output window.

Command Line

Any valid command line function and switches can be placed here. Variable substitution is also accepted. The following list contains the more useful variables (see section 3.2 for the full list).

$relfile, $file

Respectively, the relative and absolute name of a selected file.

$reldir, $dir

Respectively, the relative and absolute name of a selected directory.

$relpath, $path

The relative and absolute name of the selected file or directory.

$mpaths

A list of selected files or directories (absolute paths only).

$fname, $fext

The name without extension and the extension without the name of the selected file.

$inputstr{prompt}

Prompts the user to enter a string of text which is substituted into the command line.

$if(condition){true clause}{false clause}

Resolves to false clause if condition is empty, 0, or false; otherwise true clause.

File Types

Wildcard expressions separated by semicolons will restrict population of the right click menu of a file, directory, or multiple paths in the Project Tree, File Explorer, or Editor Pane to the specified type(s). Leave blank to handle all file/directory types.

Working Directory

The directory from which the command is executed. Code::Blocks variables, project variables, and global variables are available. Also,

1.

If $dir is specified in the command line then $dir may be used here as well.

2.

$parentdir is available for $relfile, $file, $reldir, $dir, $relpath, $path, $fname, $fext, evaluating into the absolute path of the directory containing the item.

Tools Menu Path

Controls the placement of the command in the Tools(+) menu, giving the option of adding sub-menus (multiple levels are allowed).

• Submenu/Tool1

• Submenu/Tool2

• Tool3

Will create this structure.

The command name will be used if this entry is blank. If the first character is a period, the command will be hidden.

Context Menu Path

This controls the command’s placement in the right-click menu of the Projects and Files tabs of the Management pane. The same rules of structure with the Tools Menu Path apply here.

Please note that the command will not show up in the context menu unless the Command Line contains one or more of the following: $relfile, $file, $reldir, $dir, $relpath, $path, $fname, and $fext.

Output to

This determines where the output of the command will be redirected. The purpose and function of the command will determine which is best to select. Tools Output Window

Tools that only output results command (and require no input) line generally use this setting. The program will be run invisibly and any output will be redirected to the appropriate tab of the Tools Output Window. The text [DONE] will be added upon the tool’s completion.

Code::Blocks Console

This will cause the program to be run through the executable cb_console_runner (the same program that is launched after Build and run). This is generally used for command line tools with more advanced user interactions, although GUI programs can also be used (especially if the program is unstable and/or also leaves messages in the standard output). Console runner will pause the window (prevent it from closing), display the run time, and the exit code when the program finishes.

Standard Shell

This is the same as placing the command in a batch or shell script, then running it. The program will run in whatever its default method is, and when it finishes, its window will close. This setting is useful for running a program (for example a file or web browser) that must remain open after Code::Blocks is closed.

2.20.1  Example Tools

Open file browser to selected file

• Windows Explorer

  • Tools Menu

               explorer /select,"$(PROJECTFILE)"

  • Context Menu

               explorer /select,"$path"

• Dolphin

  • Tools Menu

               dolphin --select "$(PROJECTFILE)"

  • Context Menu

               dolphin --select "$path"

  Note:
  The following three Context Menu commands only support folders (but not files).

• Nautilus

  • Tools Menu

               nautilus --no-desktop --browser "$(PROJECTDIR)"

  • Context Menu

               nautilus --no-desktop --browser "$dir"

• Thunar

  • Tools Menu

               thunar "$(PROJECTDIR)"

  • Context Menu

               thunar "$dir"

• PCMan File Manager

  • Tools Menu

               pcmanfm "$(PROJECTDIR)"

  • Context Menu

               pcmanfm "$dir"

Update Subversion directory

• Windows

  • Tools Menu

               "path_to_svn\bin\svn" update "$inputstr{Directory}"

  • Context Menu

               "path_to_svn\bin\svn" update "$dir"

• Linux

  • Tools Menu

               svn update "$inputstr{Directory}"

  • Context Menu

               svn update "$dir"

Export makefile

• Windows

  • Tools Menu

               "path_to_cbp2make\cbp2make" -in "$(PROJECTFILE)"

• Linux

  • Tools Menu

               "path_to_cbp2make/cbp2make" -in "$(PROJECTFILE)"

Compress active project to archive

• Windows

  • 7z or zip - Tools Menu (on a single line)

               "path_to_7z\7z" a -t$if(zip == $inputstr{7z or zip?}){zip -mm=Deflate
                    -mmt=on -mx9 -mfb=128 -mpass=10}{7z -m0=LZMA -mx9
                    -md=64m -mfb=64 -ms=on} -sccUTF-8 "-w$(PROJECTDIR).."
                    "$(PROJECTDIR)..\$(PROJECT_NAME)" "$(PROJECTDIR)*"

  • tar.gz or tar.bz2 - Tools Menu (on a single line)

               cmd /c ""path_to_7z\7z" a -ttar -mx0 -sccUTF-8 "-w$(PROJECTDIR).."
                     "$(PROJECTDIR)..\$(PROJECT_NAME)" "$(PROJECTDIR)*" &&
                     "path_to_7z\7z" a -t$if(gz == $inputstr{gz or bz2?}){gzip -mx9
                     -mfb=128 -mpass=10 -sccUTF-8 "-w$(PROJECTDIR).."
                     "$(PROJECTDIR)..\$(PROJECT_NAME).tar.gz}{bzip2 -mmt=on -mx9
                     -md=900k -mpass=7 -sccUTF-8 "-w$(PROJECTDIR).."
                     "$(PROJECTDIR)..\$(PROJECT_NAME).tar.bz2}"
                     "$(PROJECTDIR)..\$(PROJECT_NAME).tar" &&
                      cmd /c del "$(PROJECTDIR)..\$(PROJECT_NAME).tar""

    Note:
    The Windows command line interpreter has been invoked directly here (cmd /c), allowing for multiple commands to be chained in a single line. However, this causes the command to fail to execute in the Code::Blocks Console.

• Linux

  • 7z or zip - Tools Menu

               7z a -t$if(zip == $inputstr{7z or zip?}){zip -mm=Deflate -mmt=on -mx9
                   -mfb=128 -mpass=10}{7z -m0=LZMA -mx9 -md=64m -mfb=64 -ms=on}
                   -sccUTF-8 "-w$(PROJECTDIR).." "$(PROJECTDIR)../$(PROJECT_NAME)"
                   "$(PROJECTDIR)*"

  • tar.gz or tar.bz2 - Tools Menu

               tar -cf "$(PROJECTDIR)../$(PROJECT_NAME).tar.$if(gz == $inputstr{gz
                    or bz2?}){gz" -I ’gzip}{bz2" -I ’bzip2} -9’ "$(PROJECTDIR)*"

2.21  Thread Search

Via the ’Search’ →’Thread Search’ menu, the appropriate plug-in can be shown or hidden as a tab in the Messages Console. In Code::Blocks, a preview can be displayed for the occurrence of a character string in a file, workspace or directory. In doing so, the list of search results will be displayed on the right-hand side of the ThreadSearch Console. By clicking an entry in the list, a preview is displayed on the left-hand side. By double-clicking in the list, the selected file is opened in the Code::Blocks editor.

2.21.1  Features

ThreadSearch plugin offers the following features:

• Multi-threaded ’Search in files’

• Internal read-only editor to preview the results

• File open in editors notebook

• Highly configurable

• Contextual menu ’Find occurrences’ to start a search in files with the word under cursor

2.21.2  Usage

1.

Configure your search preferences (see Figure 2.29)

Once the plugin is installed, there are 4 ways to run a search:

a)

Type/Select a word in the search combo box and press enter or click on Search on the Thread search panel of the Messages notebook.

b)

Type/Select a word in the toolbar search combo box and press enter or click on Search button.

c)

Right click on any ’word’ in active editor and click on ’Find occurrences’.

d)

Click on Search/Thread search to find the current word in active editor.

Note:
Items 1, 2 and 3 may not be available according to current configuration.

2.

Click again on the search button to cancel current search.

3.

A single click on a result item displays it on the preview editor at right location.

4.

A double click on a result item opens or set an editor in editors notebook at right location.

2.21.3  Configuration

To access ThreadSearch plugin configuration panel click on (see Figure 2.29):

1.

Options button on Messages notebook Thread search panel.

2.

Options button on Thread search toolbar.

3.

Settings/Environment menu item and then on the Thread search item on the left columns.

Search in part defines the set of files that will be analysed.

• Project and Workspace checkboxes are mutually exclusive.

• Directory path can be edited or set with Select button.

• Mask is the set a file specifications separated by ’;’. For example: *.cpp;*.c;*.h.

2.21.4  Options

Whole word

if checked, line matches search expression if search expression is found with no alpha-numeric +’_’ before and after.

Start word

if checked, line matches search expression if search expression is found at the beginning of a word, ie no alpha-numeric +’_’ before search expression.

Match case

if checked, the search is case sensitive.

Regular expression

the search expression is a regular expression.

2.21.5  Thread search options

Enable ’Find occurrences contextual menu item’

If checked, the Find occurrences of ’Focused word’ entry is added to the editor contextual menu.

Use default options when running ’Find occurrences’

If checked, a set of default options is applied to the searches launched with the ’Find occurrences’ contextual menu item. Per defaut option ’Whole word’ and ’Match case’ is enabled.

Delete previous results at search begin

If ThreadSearch is configured with ’Tree View’ then the search results will be listed hierarchically,

• the first node contains the search term

• above the files which contain the search term are listed

• within this list the line number and the corresponding content of the occurence is displayed

If you search different terms the list will become confusing, therefore previous search results can be cleared at search begin using this option.

Note:
In the list of occurences single items or all items can be deleted via the context menu ’Delete item’ or ’Delete all items’ .

2.21.6  Layout

Display header in log window

if checked, the header are displayed in the results list control.

Note:
If unchecked, the columns are no longer resizeable but space is spared.

Draw lines between columns

Draws lines between columns in list mode.

Show ThreadSearch toolbar

Display the toolbar of Thread Search plugin.

Show search widgets in ThreadSearch Messages panel

If checked, only the results list control and the preview editor are displayed. All other search widgets are hidden (spares space).

Show code preview editor

Code preview can be hidden either with this check box or with a double click on the splitter window middle border. This is where it can be shown again.

2.21.7  Panel Management

You can choose different modes how the the ThreadSearch window is managed. With the setting ’Message Notebook’ the ThreadSearch window will be a dockable window in the message panel. If you choose the setting ’Layout’ you will be able to undock the window from the message panel and put it somewhere else.

2.21.8  Logger Type

The view of the search results can be displayed in different ways. The setting ’List’ displays all occurrences as list. The other mode ’Tree’ gathers all occurrences within a file as a node.

2.21.9  Splitter Window Mode

The user can configure a horizontal or vertical splitting of the preview window and the output window of the search results.

2.21.10  Sort Search Results

The view of the search results may be sorted by path or file name.

2.22  Code statistics

Based on the entries in the configuration mask, this simple plugin detects the proportions of code, commentaries and blank lines for a project. The evaluation is called via the menu command ’Plugins’ →’Code statistics’ .

2.23  Code profiler

A simple graphical interface to the GNU GProf Profiler.

2.24  Projects Importer plugin

ProjectsImporter imports foreign projects and workspaces from Dev-C++, MSVC6, MSVC7, and MSVC8 for use as a Code::Blocks project.

2.25  Searching Available Source Code

This plugin makes it possible to select a term within the editor and to search for this term via the context menu ’Search at Koders’ in the [?] database. The dialogue offers the additional possibilities to of filtering for program languages and licences.

This database search will help you find source code originating from other world-wide projects of universities, consortiums and organisations such as Apache, Mozilla, Novell Forge, SourceForge and many others, which can be re-used without having to reinvent the wheel every time. Please observe the licence of the source code in each individual case.

2.26  Symbol Table Plugin

This plugin makes it possible to search for symbols in objects and libraries. The options and the path for the command line program nm are defined in the Options tab.

Clicking the ’Search’ stats the search, the results of the NM program are displayed in a separate window caleld ’SymTabs Result’. The name of the objects or libraries containing the symbol are listed under the title ’NM’s Output’.

3  Variable Expansion

Code::Blocks differentiates between several types of variables. These types serve the purpose of configuring the environment for creating a program, and at the same of improving the maintainability and portability. Access to the Code::Blocks variables is achieved via $<name>.

Environment Variable

are set during the startup of Code::Blocks. They can modify system environment variables such as PATH. This can be useful in cases where a defined environment is necessary for the creation of projects. The settings for environment variables in Code::Blocks are made at ’Settings’ →’Environment’ →’Environment Variables’ .

Builtin Variables

are predefined in Code::Blocks, and can be accessed via their names (see section 3.2 for details).

Command Macros

This type of variables is used for controlling the build process. For further information please refer to section 3.4.

Custom Variables

are user-defined variables which can be specified in the build options of a project. Here you can, for example define your derivative as a variable MCU and assign a corresponding value to it. Then set the compiler option -mcpu=$(MCU), and Code::Blocks will automatically replace the content. By this method, the settings for a project can be further parametrised.

Global Variables

are mainly used for creating Code::Blocks from the sources or developments of wxWidgets applications. These variables have a very special meaning. In contrast to all others if you setup such a variables and share your project file with others that have *not* setup this GV Code::Blocks will ask the user to setup the variable. This is a very easy way to ensure the ’other developer’ knows what to setup easily. Code::Blocks will ask for all path’s usually necessary.

3.1  Syntax

Code::Blocks treats the following functionally identical character sequences inside pre-build, post-build, or build steps as variables:

• $VARIABLE

• $(VARIABLE)

• ${VARIABLE}

• %VARIABLE%

Variable names must consist of alphanumeric characters and are not case-sensitive. Variables starting with a single hash sign (#) are interpreted as global user variables (see section 3.5 for details). The names listed below are interpreted as built-in types.

Variables which are neither global user variables nor built-in types, will be replaced with a value provided in the project file, or with an environment variable if the latter should fail.

The use of these variables can follow the following example for the date :

#include "include/manager.h"
wxString strdate = Manager::Get()->GetMacrosManager()->ReplaceMacros(_T("$TODAY"));

3.2  List of available built-ins

The variables listed here are built-in variables of Code::Blocks. They cannot be used within source files.

3.2.1  Code::Blocks workspace

$(WORKSPACE_FILENAME), $(WORKSPACE_FILE_NAME), $(WORKSPACEFILE), $(WORKSPACEFILENAME)

The filename of the current workspace project (.workspace).

$(WORKSPACENAME), $(WORKSPACE_NAME)

The name of the workspace that is displayed in tab Projects of the Management panel.

$(WORKSPACE_DIR), $(WORKSPACE_DIRECTORY), $(WORKSPACEDIR), $(WORKSPACEDIRECTORY)

The location of the workspace directory.

3.2.2  Files and directories

$(PROJECT_FILENAME), $(PROJECT_FILE_NAME), $(PROJECT_FILE), $(PROJECTFILE)

The filename of the currently compiled project.

$(PROJECT_NAME), $(PROJECTNAME)

The name of the currently compiled project.

$(PROJECT_DIR), $(PROJECTDIR), $(PROJECT_DIRECTORY), $(PROJECTDIRECTORY)

The common top-level directory of the currently compiled project.

$(ACTIVE_EDITOR_FILENAME)

The filename of the file opened in the currently active editor.

$(ACTIVE_EDITOR_LINE)

Return the current line in the active editor.

$(ACTIVE_EDITOR_COLUMN

Return the column of the current line in the active editor.

$(ACTIVE_EDITOR_DIRNAME)

the directory containing the currently active file (relative to the common top level path).

$(ACTIVE_EDITOR_STEM)

The base name (without extension) of the currently active file.

$(ACTIVE_EDITOR_EXT)

The extension of the currently active file.

$(ALL_PROJECT_FILES)

A string containing the names of all files in the current project.

$(MAKEFILE)

The filename of the makefile.

$(CODEBLOCKS), $(APP_PATH), $(APPPATH), $(APP-PATH)

The path to the currently running instance of Code::Blocks.

$(DATAPATH), $(DATA_PATH), $(DATA-PATH)

The ’shared’ directory of the currently running instance of Code::Blocks.

$(PLUGINS)

The plugins directory of the currently running instance of Code::Blocks.

$(TARGET_COMPILER_DIR)

The compiler installation directory so-called master path.

3.2.3  Build targets

replace FOOBAR with the target name

$(FOOBAR_OUTPUT_FILE)

The output file of a specific target.

$(FOOBAR_OUTPUT_DIR)

The output directory of a specific target.

$(FOOBAR_OUTPUT_BASENAME)

The output file’s base name (no path, no extension) of a specific target.

$(FOOBAR_PARAMETERS)

A specific target’s execution parameters

$(TARGET_OUTPUT_DIR)

The output directory of the current target.

$(TARGET_OBJECT_DIR)

The object directory of the current target.

$(TARGET_NAME)

The name of the current target.

$(TARGET_OUTPUT_FILE)

The output file of the current target.

$(TARGET_OUTPUT_BASENAME)

The output file’s base name (no path, no extension) of the current target.

$(TARGET_CC), $(TARGET_CPP), $(TARGET_LD), $(TARGET_LIB)

The build tool executable (compiler, linker, etc) of the current target.

$(TARGET_COMPILER_DIR)

The current target’s build tool directory (compiler, linker, etc).

3.2.4  Language and encoding

$(LANGUAGE)

The system language in plain language.

$(ENCODING)

The character encoding in plain language.

3.2.5  Time and date

$(TDAY)

Current date in the form YYYYMMDD (for example 20051228)

$(TODAY)

Current date in the form YYYY-MM-DD (for example 2005-12-28)

$(NOW)

Timestamp in the form YYYY-MM-DD-hh.mm (for example 2005-12-28-07.15)

$(NOW_L)

Timestamp in the form YYYY-MM-DD-hh.mm.ss (for example 2005-12-28-07.15.45)

$(WEEKDAY)

Plain language day of the week (for example ’Wednesday’)

$(TDAY_UTC), $(TODAY_UTC), $(NOW_UTC), $(NOW_L_UTC), $(WEEKDAY_UTC)

These are identical to the preceding types, but are expressed relative to UTC.

$(DAYCOUNT)

The number of the days passed since an arbitrarily chosen day zero (January 1, 2009). Useful as last component of a version/build number.

3.2.6  Platform dependence

$(PLATFORM)

Expands to msw on windows and unix on linux and mac (Since revision r11793)

3.2.7  Command line expansions

This commands can be used in the command line for the specific platform.

$(CMD_CP)

Will expand to a copy command for the specific platform. (on windows copy and on unix cp --preserve=timestamps)

$(CMD_RM)

delete command

$(CMD_MV)

move command

$(CMD_NULL)

NULL device (for redirecting streams)

$(CMD_MKDIR)

create a directory

$(CMD_RMDIR)

delete a directory

3.2.8  Random values

$(COIN)

This variable tosses a virtual coin (once per invocation) and returns 0 or 1.

$(RANDOM)

A 16-bit positive random number (0-65535)

3.2.9  Standard path

$(GET_DATA_DIR)

Unix: prefix/share/appname ; Windows: EXE path

$(GET_LOCAL_DATA_DIR)

Unix: /etc/appname ; Windows: EXE path

$(GET_CONFIG_DIR)

Unix: /etc ; Windows: C:∖Documents and Settings∖All Users∖Application Data

$(GET_USER_CONFIG_DIR)

Unix:   ; Windows: C:∖Documents and Settings∖username∖Application Data∖appname

$(GET_USER_DATA_DIR)

Unix:  /.appname ; Windows: C:∖Documents and Settings∖username∖Application Data

$(GET_USER_LOCAL_DATA_DIR)

Unix:  /.appname ; Windows: C:∖Documents and Settings∖username∖Local Settings∖Application Data∖appname

$(GET_TEMP_DIR)

ALL platforms: A writable, temporary directory

For Windows 10 or 11, paths are more like C:∖Users∖<user>...

3.2.10  Build in functions for path conversion

There are build in macro functions to simplify path generation

$TO_UNIX_PATH{}

convert path to unix path (use ’/’ as separator)

$TO_WINDOWS_PATH{}

convert path to windows (use ’∖’ as separator)

$TO_NATIVE_PATH{}

convert to native path form the codeblocks instance is running on

Usage

$TO_UNIX_PATH{$(TARGET_OUTPUT_FILE)}

returns the current target output file as unix path

3.2.11  Conditional Evaluation

$if(condition){true clause}{false clause}

Conditional evaluation will resolve to its true clause if

• condition is a non-empty character sequence other than 0 or false

• condition is a non-empty variable that does not resolve to 0 or false

• condition is a variable that evaluates to true (implicit by previous condition)

Conditional evaluation will resolve to its false clause if

• condition is empty

• condition is 0 or false

• condition is a variable that is empty or evaluates to 0 or false

Example

For example if you are using several platforms and you want to set different parameters depending on the operating system. In the following code the script commands of [[ ]] are evaluated and the <command> will be executed. This could be useful in a post-built step (on a single line).

[[ if (PLATFORM ==  PLATFORM_MSW) { print (_T("cmd /c")); } else 
     { print (_T("sh ")); } ]] <command>

3.3  Script expansion

For maximum flexibility, you can embed scripts using the [[ ]] operator as a special case of variable expansion. Embedded scripts have access to all standard functionalities available to scripts and work pretty much like bash backticks (except for having access to Code::Blocks namespace). As such, scripts are not limited to producing text output, but can also manipulate Code::Blocks state (projects, targets, etc.).

Example with Backticks

objdump -D ‘find . -name *.elf‘ > name.dis

The expression in backticks returns a list of all executables *.elf in any subdirectories. The result of this expression can be used directly by objdump. Finally the output is piped to a file named name.dis. Thus, processes can be automatted in a simple way without having to program any loops.

Example using Script

The script text is replaced by any output generated by your script, or discarded in case of a syntax error.

Since conditional evaluation runs prior to expanding scripts, conditional evaluation can be used for preprocessor functionalities. Built-in variables (and user variables) are expanded after scripts, so it is possible to reference variables in the output of a script.

[[ print(GetProjectManager().GetActiveProject().GetTitle()); ]]

inserts the title of the active project into the command line.

3.4  Command Macros

$compiler

Access to name of the compiler executable.

$linker

Access to name of the linker executable.

$options

Compiler flags

$link_options

Linker flags

$includes

Compiler include paths

$c

Linker include paths

$libs

Linker libraries

$file

Source file (full name)

$file_dir

Source file directory without file name and file name extension.

$file_name

Source file name without path info and file name extension.

$exe_dir

Directory of executable without file name and file name extension.

$exe_name

File name of executable without path and file name extension.

$exe_ext

File name extension of executable without path and file name.

$object

Object file

$exe_output

Executable output file

$objects_output_dir

Object Output Directory

3.4.1  Example 1: Compile single file

$compiler $options $includes -c $file -o $object

3.4.2  Example 2: Link object files to executable

$linker $libdirs -o $exe_output $link_objects $link_resobjects 
$link_options $libs

3.5  Global compiler variables

This section describes how to work with global variables.

3.5.1  Synopsis

Working as a developer on a project which relies on 3rd party libraries involves a lot of unnecessary repetitive tasks, such as setting up build variables according to the local file system layout. In the case of project files, care must be taken to not accidentially commit a locally modified copy. If one does not pay attention, this can happen easily for example after changing a build flag to make a release build.

The concept of global compiler variables is a unique new solution for Code::Blocks which addresses this problem. Global compiler variables allow you to set up a project once, and any number of developers using any number of different file system layouts being able to compile and develop this project. No local layout information ever needs to be changed more than once.

3.5.2  Names and Members

Global compiler variables in Code::Blocks are discriminated from per-project variables by a leading hash sign. Global compiler variables are structured; every variable consists of a name and an optional member. Names are freely definable, while some of the members are built into the IDE. Although you can choose anything for a variable name in principle, it is advisable to pick a known identifier for common packages. Thus the amount of information that the user needs to provide is minimised. The Code::Blocks team provides a list of recommended variables for known packages.

The member base resolves to the same value as the variable name uses without a member (alias).

The members include and lib are by default aliases for base/include and base/lib, respectively. However, a user can redefine them if another setup is desired.

It is generally recommended to use the syntax $(#variable.include) instead of $(#variable)/include, as it provides additional flexibility and is otherwise exactly identical in functionality (see section 3.5.6 and Figure 3.1 for details).

The members cflags and lflags are empty by default and can be used to provide the ability to feed the same consistent set of compiler/linker flags to all builds on one machine. Code::Blocks allows you to define custom variable members in addition to the built-in ones.

3.5.3  Constraints

• Both set and global compiler variable names may not be empty, they must not contain white space, must start with a letter and must consist of alphanumeric characters. Cyrillic or Chinese letters are not alphanumeric characters. If Code::Blocks is given invalid character sequences as names, it might replace them without asking.

• Every variable requires its base to be defined. Everything else is optional, but the base is absolutely mandatory. If you don’t define a the base of a variable, it will not be saved (no matter what other fields you have defined).

• You may not define a custom member that has the same name as a built-in member. Currently, the custom member will overwrite the built-in member, but in general, the behaviour for this case is undefined. If ’libext’ is a custom member we can only write $(#variable.libext) and not $(#variable)/libext.

• Variable and member values may contain arbitrary character sequences, subject to the following three constraints:

  • You may not define a variable by a value that references the same variable or any of its members

  • You may not define a member by a value that references the same member

  • You may not define a member or variable by a value that references the same variable or member through a cyclic dependency.

Code::Blocks will detect the most obvious cases of recursive definitions (which may happen by accident), but it will not perform an in-depth analysis of every possible abuse. If you enter crap, then crap is what you will get; you are warned now.

Examples

Defining wx.include as $(#wx)/include is redundant, but perfectly legal Defining wx.include as $(#wx.include) is illegal and will be detected by Code::Blocks Defining wx.include as $(#cb.lib) which again is defined as $(#wx.include) will create an infinite loop

3.5.4  Using Global Compiler Variables

All you need to do for using global compiler variables is to put them in your project! Yes, it’s that easy.

When the IDE detects the presence of an unknown global variable, it will prompt you to enter its value. The value will be saved in your settings, so you never need to enter the information twice.

If you need to modify or delete a variable at a later time, you can do so from the settings menu.

Example

The above image shows both per-project and global variables. WX_SUFFIX is defined in the project, but WX is a global user variable.

3.5.5  Variable Sets

Sometimes, you want to use different versions of the same library, or you develop two branches of the same program. Although it is possible to get along with a global compiler variable, this can become tedious. For such a purpose, Code::Blocks supports variable sets. A variable set is an independent collection of variables identified by a name (set names have the same constraints as variable names).

If you wish to switch to a different set of variables, you simply select a different set from the menu. Different sets are not required to have the same variables, and identical variables in different sets are not required to have the same values, or even the same custom members.

Another positive thing about sets is that if you have a dozen variables and you want to have a new set with one of these variables pointing to a different location, you are not required to re-enter all the data again. You can simply create a clone of your current set, which will then duplicate all of your variables.

Deleting a set also deletes all variables in that set (but not in another set). The default set is always present and cannot be deleted.

You can also export or import sets (since r13224 SVN version): files, with extension .set, are text files containing a particular set. Those files are easily transferable between users/computers.

All these options on sets are available with buttons ”Add”, ”Delete”, ”Clone”, ”Export” and ”Import”, located at the top of the Global Variable Environment window (see Figure 3.1).

3.5.6  Custom Members Mini-Tutorial

As stated above, writing $(#var.include) and $(#var)/include is exactly the same thing by default. So why would you want to write something as unintuitive as $(#var.include)?

Let’s take a standard Boost installation under Windows for an example. Generally, you would expect a fictional package ACME to have its include files under ACME/include and its libraries under ACME/lib. Optionally, it might place its headers into yet another subfolder called acme. So after adding the correct paths to the compiler and linker options, you would expect to #include <acme/acme.h> and link to libacme.a (or whatever it happens to be).

Boost, however, installs headers into C:∖Boost∖include∖boost-1_33_1∖boost and its libraries under C:∖Boost∖lib by default. It seems impossible to get this under one hood without having to adjust everything on every new PC, especially if you have to work under Linux or some other OS, too.

This is where the true power of global user variables is unveiled. When defining the value of the #boost variable, you go one step further than usual. You define the member include as C:∖Boost∖include∖boost-1_33_1∖boost and the member lib as C:∖Boost∖lib, respectively. Your projects using $(#boost.include) and $(#boost.lib) will magically work on every PC without any modifications. You don’t need to know why, you don’t want to know why.

3.5.7  Command line arguments

After revision [r13245] it is possible to use command line arguments to override and define global variables and set the current active set.

• ’-S’ parameter for setting current active set via command line

• ’-D’ parameter for defining/overriding user variable in form:
  -D set.variable.member=value or -D variable.member=value

4  Working With Code::Blocks

This chapter deals with some basic knowledge to be able to work with Code::Blocks. Some paragraphs, here directly taken from Wiki, overlap but with a slightly different presentation with the content of the first chapter.

4.1  The build process of Code::Blocks

In this pages, the build process is explained in detail. What goes on behind the scenes and ”when” is covered. I hope it makes an interesting read :).

4.1.1  Build order

As you have probably guessed, Code::Blocks does not launch build commands at random but rather as a well thought out and prepared sequence. But first let’s see what components are the subject of the build:

Workspace:

contains one or more projects

Project:

contains one or more build targets. It also contains the project’s files.

Build target:

project files are assigned to it, which are built as a group and generate one binary output. This output can either be an executable, a dynamic library or a static library. Note: there is one kind of build target that does not produce a binary output directly but rather just runs its pre/post build steps (which may generate a binary output externally).

Let’s break these subjects in sections and explain them in more detail.

4.1.2  Workspace

The workspace is the top-level container item for organizing your projects. Since there can be only one workspace open at a time, there really is no build order issue for them. It’s only one, so it’s just built ;).

Use the menu ’Build’ →’Build workspace’ to build a workspace (i.e. all the projects contained in it).

4.1.3  Projects

Here, things start getting interesting :).

Projects build order is different depending if the user has set project dependencies or not. Please read on.

Without project dependencies

In this case, projects are built in the order of appearence, from top to bottom. Most projects though (at least not the ”hello world” ones), would want to setup project dependencies.

Using project dependencies

Project dependencies are a simple way to tell Code::Blocks that a given project ”depends” on another (in the same workspace, always).

Thus imagine in your workspace you have a library project and an executable project which depends on the library. Then you could (and should) tell Code::Blocks about this dependency. To do this, you select ’Project’ →’Properties’ and click the ”Project’s dependencies..” button.

Please notice that the dependency information is saved within the workspace file, not the project file as it is a dependency between two projects within a workspace.

It is very easy to use this dialog. Select the project you want to add a dependency and then put a checkmark on all projects that this project depends on. This will ensure that all the projects you checked will be built before the project that depends on them, ensuring a synchronized build.

Tip: You don’t have to close this dialog and launch the other project’s properties again to set their dependencies. You can set all projects dependencies from this same dialog. Just select a different project in the drop-down box :).

Some things to note:

• Dependencies are set directly or indirectly. If project A depends directly on project B and project B depends on project C, then project A indirectly depends on project C too.

• Code::Blocks is smart enough to watch out for circular dependencies and prohibit them. A circular dependency is caused when project A depends directly or indirectly on project B and project B depends directly or indirectly on project A.

• Dependencies take effect either if building the whole workspace or a single project. In this case, only the dependencies needed for the project you ’re building will be built too.

4.1.4  Build targets

Build targets build order depend on a couple of things.

1.

If the user has selected a specific build target in the compiler toolbar’s drop-down box, then only this build target is built. If project dependencies are setup for the project containing this target, all projects it depends on will also build their target with the same name. If no such target exists, that project is skipped.

2.

If the virtual ”All” target is selected, then all targets in the project (and all the projects it depends on) are built in order, top to bottom. There are a couple of exceptions to this:

• A target is not built with ”All” if the target option (in project properties ”Targets” page) ”Build this target with All” is not selected.

• If no targets in the project have the above option selected, then no virtual ”All” target appears in the list.

4.1.5  Preprocessing phase

Before the actual build process starts (i.e. the compiler/linker commands start executing), a preprocessing step runs which generates all required command-lines for the entire build process. This step caches much of the information it generates, making subsequent builds faster in effect.

This step also runs any attached build scripts.

4.1.6  Actual commands execution

This is the stage that the build process actually starts, from the user’s point of view. The files start getting compiled and finally linked to generate the various binary outputs the build targets define.

In this step, the pre-build and post-build steps are also executed.

4.1.7  Pre-build and post-build steps

These are commands that can be setup on project and/or target level. They are shell commands that e.g. copy files around or any other operation you can do with a usual OS system shell.

The variables specified in the article Variable expansion (3) can be used in the scripts to get things like target output directory, project directory, target type and others.

Here’s a breakdown of the pre/post build steps execution order for an imaginary project with two targets (Debug/Release):

1.

Project pre-build steps

a)

Target ”Debug” pre-build steps

b)

Target ”Debug” compile files

c)

Target ”Debug” link files and generate binary output

d)

Target ”Debug” post-build steps (see notes below)

e)

Target ”Release” pre-build steps

f)

Target ”Release” compile files

g)

Target ”Release” link files and generate binary output

h)

Target ”Release” post-build steps (see notes below)

2.

Project post-build steps

I hope this is self-explaining :)

Script Samples

Post-build script that copies the output file into the folder C:∖Program∖bin in Windows:

cmd /c copy "$(PROJECT_DIR)$(TARGET_OUTPUT_FILE)" "C:\Program\bin"

Execute the bash script ”copyresources.sh” in Linux:

/bin/sh copyresources.sh

Create a new directory in the output directory:

mkdir $(TARGET_OUTPUT_DIR)/data

4.2  Creating a New Project

These pages are 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.

4.2.1  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, and click Go.

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; 
}

4.2.2  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;