Difference between revisions of "Variable expansion"

From Code::Blocks
Line 143: Line 143:
 
:As conditional evaluation runs prior to expanding scripts, conditional evaluation can be used for preprocessor functionality. Builtin variables (and user variables) are expanded after scripts, so it is possible to reference variables in a script's output.
 
:As conditional evaluation runs prior to expanding scripts, conditional evaluation can be used for preprocessor functionality. Builtin variables (and user variables) are expanded after scripts, so it is possible to reference variables in a script's output.
  
:<u>Example:</u> adding <tt>[[ print(5+3); ]]</tt> to compiler options inserts <tt>8</tt>
+
:<u>Example:</u> adding <tt>[[ local p=GetProjectManager().GetActiveProject(); print(p.GetTitle()); ]]</tt> to compiler options inserts the active project's title into the command line.

Revision as of 08:38, 8 December 2006


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

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

The filename of the currently compiling project.

$(PROJECT_NAME)

The name of the currently compiling project.

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

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

$(ACTIVE_EDITOR_FILENAME)

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

$(ACTIVE_EDITOR_DIRNAME)

Currently active file's containing directory (relative to the common top level path)

$(ACTIVE_EDITOR_STEM)

Currently active file's base name (without extension).

$(ACTIVE_EDITOR_EXT)

Currently active file's extension.

$(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

Build targets

$(FOOBAR_OUTPUT_FILE)

A specific target's output file.

$(FOOBAR_OUTPUT_DIR)

A specific target's output directory.

$(FOOBAR_OUTPUT_BASENAME)

A specific target's output file's base name (no path, no extension).

$(TARGET_OUTPUT_DIR)

The current target's output directory.

$(TARGET_OBJECT_DIR)

The current target's object directory.

$(TARGET_NAME)

The current target's name.

$(TARGET_OUTPUT_FILE)

The current target's output file.

$(TARGET_OUTPUT_BASENAME)

The current target's output file's base name (no path, no extension).

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

The current target's build tool executable (compiler, linker, etc).

Language and encoding

$(LANGUAGE)

The system language in human readable form.

$(ENCODING)

The character encoding in human readable form.

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)

Human-readable 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.

Random values

$(COIN)

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

$(RANDOM)

A 16bit positive random number (0-65535)

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

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

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 functionality available to scrips 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.). Although this is technically possible, it is generally bad design and a very stupid idea to do so. Manipulating Code::Blocks state from a pre-build script is a much better solution.
The script text is replaced with any output generated by your script, or discarded in case of a syntax error.
As conditional evaluation runs prior to expanding scripts, conditional evaluation can be used for preprocessor functionality. Builtin variables (and user variables) are expanded after scripts, so it is possible to reference variables in a script's output.
Example: adding local p=GetProjectManager().GetActiveProject(); print(p.GetTitle()); to compiler options inserts the active project's title into the command line.