Global compiler variables

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 filesystem layout. In the case of project files, care must be taken to not accidentially commit a locally modified copy.

The concept of global compiler variables is an 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 filesystem layouts will be able to compile and develop the project. No local layout information needs to be changed more than once.

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 the member structure is 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. This way, 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 members dir and base resolve 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 recommended to always use the syntax $(#variable.include) instead of $(#variable)/include, as it provides additional flexibility and is otherwise exactly identical in functionality (see mini tutorial at end of page).

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.

Using Global Compiler Variables

All you need to do to start using global compiler variables is to put them in your project!

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-procect and global variables. WX_CFG is defined in the project, but WX is a global user variable.

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 as 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. Thus, 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.