View source for Variable expansion

[[Category:User Documentation]]

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

* <code>$VARIABLE</code>
* <code>$(VARIABLE)</code>
* <code>${VARIABLE}</code>
* <code>%VARIABLE%</code>

Variable names must consist of alphanumeric characters and are not case-sensitive. Variables starting with a single hash sign (<code>#</code>) are interpreted as [[global user variables]].
The names listed below are interpreted as builtin types.

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

'''Per-target definitions have precedence over per-project definitions.'''

== List of available builtins ==

=== Files and directories ===

<code>$(PROJECT_FILENAME)</code>, <code>$(PROJECT_FILE)</code>, <code>$(PROJECTFILE)</code>
:The filename of the currently compiling project.

<code>$(PROJECT_NAME)</code>
:The name of the currently compiling project.

<code>$(PROJECT_DIR)</code>, <code>$(PROJECTDIR)</code>, <code>$(PROJECT_DIRECTORY)</code>
:The common top-level directory of the currently compiling project.

<code>$(ACTIVE_EDITOR_FILENAME)</code>
:The filename of the file opened in the currently active editor.

<code>$(ACTIVE_EDITOR_DIRNAME)</code>
:Currently active file's containing directory (relative to the common top level path)

<code>$(ACTIVE_EDITOR_STEM)</code>
:Currently active file's base name (without extension).

<code>$(ACTIVE_EDITOR_EXT)</code>
:Currently active file's extension.

<code>$(ALL_PROJECT_FILES)</code>
:A string containing the names of all files in the current project.

<code>$(MAKEFILE)</code>
:The filename of the makefile.

<code>$(CODEBLOCKS)</code>, <code>$(APP_PATH)</code>, <code>$(APPPATH)</code>, <code>$(APP-PATH)</code>
:The path to the currently running instance of Code::Blocks

<code>$(DATAPATH)</code>, <code>$(DATA_PATH)</code>, <code>$(DATA-PATH)</code>
:The 'shared' directory of the currently running instance of Code::Blocks

<code>$(PLUGINS)</code>
:The 'plugins' directory of the currently running instance of Code::Blocks

=== Build targets ===

<code>$(FOOBAR_OUTPUT_FILE)</code>
:A ''specific'' target's output file.

<code>$(FOOBAR_OUTPUT_DIR)</code>
:A ''specific'' target's output directory.

<code>$(FOOBAR_OUTPUT_BASENAME)</code>
:A ''specific'' target's output file's base name (no path, no extension).

<code>$(TARGET_OUTPUT_DIR)</code>
:The ''current'' target's output directory.

<code>$(TARGET_NAME)</code>
:The ''current'' target's name.

<code>$(TARGET_OUTPUT_FILE)</code>
:The ''current'' target's output file.

<code>$(TARGET_OUTPUT_BASENAME)</code>
:The ''current'' target's output file's base name (no path, no extension).

<code>$(TARGET_CC), $(TARGET_CPP), $(TARGET_LD), $(TARGET_LIB)</code>
:The ''current'' target's build tool executable (compiler, linker, etc).

=== Language and encoding ===

<code>$(LANGUAGE)</code>
:The system language in human readable form.

<code>$(ENCODING)</code>
:The character encoding in human readable form.

=== Time and date ===

<code>$(TDAY)</code>
:Current date in the form <code>YYYYMMDD</code> (for example 20051228)

<code>$(TODAY)</code>
:Current date in the form <code>YYYY-MM-DD</code> (for example 2005-12-28)

<code>$(NOW)</code>
:Timestamp in the form <code>YYYY-MM-DD-hh.mm</code> (for example 2005-12-28-07.15)

<code>$(NOW_L)</code>
:Timestamp in the form <code>YYYY-MM-DD-hh.mm.ss</code> (for example 2005-12-28-07.15.45)

<code>$(WEEKDAY)</code>
:Human-readable day of the week (for example "Wednesday")

<code>$(TDAY_UTC)</code>, <code>$(TODAY_UTC)</code>, <code>$(NOW_UTC)</code>, <code>$(NOW_L_UTC)</code>, <code>$(WEEKDAY_UTC)</code>
:These are identical to the preceding types, but are expressed relative to UTC.

=== Random values ===

<code>$(COIN)</code>
:This variable tosses a virtual coin (once per invokation) and returns 0 or 1.

<code>$(RANDOM)</code>
:A 16bit positive random number (0-65535)

=== Conditional Evaluation ===

<code>$if(condition){true clause}{false clause}</code>
:Conditional evaluation will resolve to its <tt>true clause</tt> if
::<tt>condition</tt> is a non-empty character sequence other than <tt>0</tt> or <tt>false</tt>
::<tt>condition</tt> is a non-empty variable that does not resolve to <tt>0</tt> or <tt>false</tt>
::<tt>condition</tt> is a variable that evaluates to <tt>true</tt> (implicit by previous condition)
:Conditional evaluation will resolve to its <tt>false clause</tt> if
::<tt>condition</tt> is empty
::<tt>condition</tt> is <tt>0</tt> or <tt>false</tt>
::<tt>condition</tt> is a variable that is empty or evaluates to <tt>0</tt> or <tt>false</tt>

Please do note that neither the variable syntax variants <tt>%if(...)</tt> nor <tt>$(if)(...)</tt> are supported for this construct.

=== Path manipulation ===

<s><code>$relative(path), $absolute(path)</code>
:Replaces the argument <tt>path</tt> (which may be a variable) with its normalised absolute path/filename equivalent or with a path relative to the project directory, respectively.

:Keep in mind that functions <tt>$relative()</tt> and <tt>$absolute()</tt> are considerably more computionally expensive than any other builtin variable or function. Thus, if performance matters, do not use them "just for good", but only when you really need them. Also, please note that neither the variable syntax variants <tt>%relative(...)</tt> nor <tt>$(relative)(...)</tt> are supported for this construct.</s>