User's Guide: preTools Suite for Windows

Getting Started

Reference

Component Setup

Each build component has its own base_config section in the configuration file. The name of a base_config section is determined by the name of its build component entry in the detect section. For example, to the MSVC80 component entry for Visual C++ 8.0,

	<detect>
          ...
	  <component name="MSVC80">
	    ...	  
	  </component>
	</detect>
		
there is a corresponding base_config section which is also named MSVC80:
        <base_configurations>
          ...
	  <base_config name="MSVC80">
            ...
          </base_config>
        </base_configurations>
		

A base_config element contains the definitions of environment variables. The basic form of an environment variable definition is:

  <env name="VarName">VarValue</env>
		

For example, many components define an "Include" path to tell the compiler where to find header files; this value might look like this:
  <env name="INCLUDE">C:\VStudio\VC\ATLMFC\INCLUDE;
                          C:\VStudio\VC\INCLUDE;</env>
		
Although, this definition would work, it "hard codes" the base directory of the Visual C++ installation directory, "C:\VStudio". A better way to define this variable is as follows:
  <env name="INCLUDE">$(Base)\VC\ATLMFC\INCLUDE;
                        $(Base)\VC\INCLUDE</env>
		

$(Base) is one of several macros that are expanded at the time the base_config is processed. This macro expands to the base installation directory of the build component. The base installation directory is determined from the component's detect section entry.

Commonly, "path-type" environment variables are built up from several components, with each one contributing search paths which are concatenated to create the complete environment variable value. This can be done easily by referencing an existing environment variable on the right side of the assignment statement by enclosing the variable name with the percent character ('%'). For example, the current value of the environment variable INCLUDE is given by %INCLUDE%, as shown in this example:

  <env name="INCLUDE">%INCLUDE%;$(Base)\PlatformSDK\include</env>
(Note that a literal percent character ('%') is inserted in a string as "%%".)

Conditional Statements

Several simple forms of conditional statement are supported. The first compares an evaluated expression with a string value for equality and has this form:

 <ifeq expression="%OS%" value="Windows_NT">
    ... environment variable assignment statements
 </ifeq> 
and it has a complimentary form which tests for inequality:
 <ifneq expression="%OS%" value="Windows_NT">
    ... environment variable assignment statements
 </ifneq> 
The expression may contain an environment variable enclosed by '%' characters or macro variables such as $(BuildType). The evaluated expression is compared to the string specified in the "value" attribute. If the boolean outcome of the comparison is true then the elements between the <ifeq> or <ifneq> and its closing tag, are processed.

A common use of this conditional element is to test the macro "$(BuildType)" which in preMake evaluates to one of the strings: "debug", "nodebug", or "retail" (in preBuild it evaluates to one of "checked", "free", or "retail"). Using this macro with conditional blocks makes it easy to tailor the environment for debug and non-debug builds.

To test if an environment variable is not defined, the following element is used:

 <ifndef var="OS">
    ... environment variable assignment statements
 </ifndef> 

To test if an environment variable is defined, the following element is used:

 <ifdef var="OS">
    ... environment variable assignment statements
 </ifdef> 

Finally, a switch-case type branching is supported in which each case is a possible value of an environment variable or macro variable supplied as argument to the switch element. This construct takes the following form:

 <switch expression="$(BuildType)">
   <case value="nodebug">
       ... environment variable assignment statements
   </case>
   <case value="debug">
       ... environment variable assignment statements
   </case>
 </switch>
		

Macros

Several macros are defined which can be referenced in environment variable definitions and conditional statements. Each macro begins with the characters "$(" and ends with a closing ")". Each macro is replaced with an appropriate string value. A single literal dollar sign can be entered as "$$".

Macro Description
Base Evaluates to a string of the build component's base installation directory. This is determined from the string assigned to the registry_value in the corresponding detect section entry.
BaseDrv Evaluates to a string containing the drive letter and colon of the build component's base installation directory.
BaseUp1 Evaluates to a string of the directory one level up from the build component's base installation directory. This is equivalent to "$(Base)\.. ".
BaseUp2 Evaluates to a string of the directory two levels up from the build component's base installation directory. This is equivalent to "$(Base)\..\.. ".
BuildType Evaluates to a string representing the build type. For preMake it is one of: "debug", "nodebug", or "retail". For preBuild it is one of: "checked ", "free", or "retail".