C/C++ Project Properties, Managed, C/C++ Build, Build Macros

Customizes the build macros used in your build configuration.

C/C++ Project Properties, Managed, C/C++ Build, Macros

Project Type:: Displays the type of project that is built by the selected build configuration.
Configuration:: Specifies the selected build configuration from the list provided.
Manage...: Adds, removes, renames and converts configurations.
Configuration Settings: Adds, removes, edits and manages build macros for a project or configuration.
Each tab contains two tables - one for user-defined build macros and one for non user-defined build macros.
Each table contains three columns:

Name of the build macro

Type of value contained in the build macro (see below)

Value of the build macro.

You can view all build macros that are not user-defined in the System Macros table. You can choose to also display all macros defined for lower-precedence contexts in the System Macros table by checking the Show parent context macros checkbox. System macros are read-only.

You can view all user-defined macros in the User Macros table. A user-defined macro overrides a non user-defined macro of the same name for the given context. Overridden macros are displayed in bold in the System Macros table.

Restore Defaults: Returns any changes back to their default setting.
Apply: Applies any changes.

Detailed Specification

Build Macros can be used in all C/C++ Build configuration properties that accept text. Build Macros are referenced in strings by enclosing them in braces, preceded by a dollar sign. There are no special restrictions on a macro name, though it is encouraged that a macro name begin with a letter and contain only letters, digits and underscore signs. Build macro names are case sensitive.
If the actual value of text property contains ${text}, it must be pre-pended with a backslash in order to distinguish it from a build macro. The Managed Build System (MBS) pre-defines many useful macros (see below) and allows tool integrators and users to define additional macros.

Build Macros can hold several types of values:

Text value: can be any text string
Text-List value: an array of Text values
Path-file value: can hold a file path
Path-dir value: can hold a directory path
Path-any value: can hold both a file and directory path
Path-file-List value: an array of Path-file values
Path-dir-List value: an array of Path-dir values
Path-any-List value: an array of Path-any values

Build Macros are context-sensitive, that is the macro of a given name could have different values depending on where it is used. Several contexts are defined:

The currently selected file.
The currently selected option
The currently selected configuration (which includes a tool-chain).
The currently selected project.
The current workspace.
The CDT and Eclipse installations.
The process environment variables defined in the environment passed to Eclipse.

Users can define and delete macros for any given project configuration, for the entire project or for the entire workspace.

The value of a build macro will be searched for in the order specified above. If macro is not found for the currently selected file context, the currently selected option context will be used, if not found, the currently selected configuration context will be used, etc. It is possible, but not recommended, for a user-defined macro to override the definition of an MBS pre-defined macro. Overriding MBS pre-defined macros can have unanticipated consequences.

To define a new macro the "New" button should be pressed. A dialog will appear representing the macro definition.

The "Name" field contains the list of macros that are already defined. A user can choose any variable from the list or enter a new variable name. When a macro from the list is chosen or the name typed by the user matches an already existing macro name, the other fields of the dialog get filled with the value, and value type of that macro.

When any of the "String," "File," "Directory" or "File or Directory" value types is selected, the macro value may be specified with the "Value" edit-box. For the "File" and "Directory" types, a "Browse" button is also displayed that allows selecting file or directory using the "Browse" dialog.

When either of the "List of Strings," "List of Files," "List of Directories" or "List Files or Directories" value types is selected, the macro value may be specified with the "Macro Value" multi-line text box and button bar.

Macro resolution takes place when the build file is being generated.

All macros, except the build process environment macros, always get resolved in the makefile. See the “Expand Build Environment Macros" checkbox in the “Build Settings" tab of the “C/C++ Build" page.

The Managed Build System pre-defines many useful macros described in the following tables:

File-specific macros

The set of file-context macros is predefined by the Managed Build System (MBS). Neither a tool-integrator nor a user can define new file-context macros.

Macro	Value Type	Description
${InputFileName}	Text	Represents the input file name. The input file has the following meaning: 1. If a tool does not accept building multiple files of the primary input type with one tool invocation, the input file is the file of the primary input type being built. 2. If a tool accepts building multiple files of the primary input type with one tool invocation the input file is undefined and the macros representing the input file contain information about one of the inputs of the primary input type being built.
${InputFileExt}	Text	Represents the extension of the input file.
${InputFileBaseName}	Text	Represents the base name of the input file. That is the file name with an extension stripped.
${InputFileRelPath}	Path(File)	Represents the input file path relative to the builder current directory.
${InputDirRelPath}	Path(Dir)	Represents the input file directory path relative to the builder current directory.
${OutputFileName}	Text	Represents the output file name. The output file has the following meaning: 1. If a tool is not capable of producing multiple files of the primary output type with one tool invocation the output file is the file of the primary output type that is built with a given tool invocation. 2. If a tool is capable of producing multiple files of the primary output type with one tool invocation the output file is undefined and the macros representing the output file contain information about one of the files of the primary output type that are built with a given tool invocation.
${OutputFileExt}	Text	Represents the output file extension.
${OutputFileBaseName}	Text	Represents the output file base name. That is the output file name with an extension stripped.
${OutputFileRelPath}	Path(File)	Represents the output file path relative to the current builder directory.
${OutputDirRelPath}	Path(Dir)	Represents the output file directory path relative to the current builder directory.

Configuration-specific macros

Macro	Value Type	Description
${ConfigName}	Text	Represents the name of a given configuration.
${ConfigDescription}	Text	Represents the description of a given configuration.
${BuildArtifactFileName}	Text	Represents the name of the build artifact.
${BuildArtifactFileExt}	Text	Represents the extension of the build artifact.
${BuildArtifactFileBaseName}	Text	Represents the base name of the build artifact.
${BuildArtifactFilePrefix}	Text	Represents the prefix of the build artifact.
${TargetOsList}	Text-List	Represents the list of the target OS names.
${TargetArchList}	Text-List	Represents the list of the target Arch names.

Project-specific macros

${ProjName}	Text	Represents the name of a given project.
${ProjDirPath}	Path(Dir)	Represents the absolute path of a given project.

Workspace-specific macros

${WorkspaceDirPath}

Path(Dir)

Represents the workspace absolute path.

${DirectoryDelimiter}

Text

Represents the directory delimiter used on the system. That is the “\? for Win32 systems and the “/? for Unix-like systems

This could be useful, e.g. in the case a user needs the absolute path of an input file. The absolute path would be represented in the following way: ${CWD}${DirectoryDelimiter}${InputFileRelPath}

${PathDelimiter}

Text

Represents the default path delimiter used on the system to separate paths in the path environment variables. That is the “;? for Win32 systems and the “:? for Unix-like systems

This might be used in the environment variable definitions

CDT/Eclipse installation-specific macros

${EclipseVersion}	Text	Represents the current Eclipse version.
${CDTVersion}	Text	Represents the current CDT version.
${MBSVersion}	Text	Represents the current MBS version.
${HostOsName}	Text	Represents the operating system name on which eclipse is running.
${HostArchName}	Text	Represents the architecture name on which eclipse is running.

Managed Build Project preferences

Managed Build Project preferences, Environment

Managed Build Project preferences, Macros