76 Xcpp Configuration Files

The Xcpp console application takes a command line argument which is a path to an xcpp configuration file which by convention has the .xcpp file extension.

This file is macro expanded using the Xc++ preprocessor. Therefore it can @import files, and use the various preprocessor directives such as @def, @for and @str.

Ignoring the preprocessor, the .xcpp file format is essentially a sequence of assignments to variables. i.e. it mostly consists of settings that take the form name = value.

In general, .xcpp config files support reassignments of variables. Only the last assigned value of a variable takes effect. This combined with the support for @import directives makes it possible to inherit default values and override some of the settings.

User-defined variables

User-defined variables begin with $ and are assigned a string value in double quotes. For example: 


$PROG_FILES = "c:/Program Files"

This is the same syntax for defining user-defined variableas in .xcpj files. In fact these variables are made available during the subsequent processing of each of the .xcpj files. This provides an ideal mechanism to pass information through to every project. It is particularly useful for passing through include and library paths to third party libraries (like boost).

The variables can be referenced from inside the double quoted string values of other variables. For example: 


$MSVS = "$(PROG_FILES)/Microsoft Visual Studio 8"

Pre-defined variables

The following variables have predefined meanings and provide the basis for defining the behaviour of an execution of xcpp.exe

Name Description
mode The mode (the essential action to be performed). For example 

mode = gen
compiler The compiler to be used. For example 

compiler = vc14
pathRootToXcws The logical path to the Ceda workspace file to be built. For example 

pathRootToXcws = "Ceda/cxObject/Object.xcws"
config The configuration to be built such as "Debug" or "Release". For example 

config = "Release"
platform The platform to target, such as "Win32" or "x64". For example 

platform = "x64"
PATH The PATH environment variable. For example 

PATH =
{
    "$(MSVS)/VC/bin"
    "$(MSVS)/Common7/IDE"
    "$(MSVS)/VC/PlatformSDK/bin"
    "c:/windows"
    "c:/windows/system32"
}

The PATH can be reassigned. This is useful for overriding the default PATH defined in compiler.xcpp. To append to the existing PATH use += instead of =. For example: 


PATH +=
{
    "c:/cad4u/bin"
}
INCLUDE The INCLUDE environment variable used when invoking the MSVC compiler. For example 

INCLUDE =
{
    "$(MSVS)/VC/include"
    "$(MSVS)/VC/PlatformSDK/include"
    "$(MSVS)/VC/atlmfc/include"
}

The INCLUDE variable can be reassigned. This is useful for overriding the default value defined in compiler.xcpp. To append to the existing INCLUDE variable use += instead of =. For example: 


INCLUDE +=
{
    "c:/cad4u/include"
}
LIB The LIB environment variable used when invoking the MSVC linker. For example 

LIB =
{
    "$(MSVS)/VC/lib"
    "$(MSVS)/VC/PlatformSDK/lib"
    "$(MSVS)/VC/atlmfc/lib"
}

The LIB variable can be reassigned. This is useful for overriding the default value defined in compiler.xcpp. To append to the existing LIB variable use += instead of =. For example: 


LIB +=
{
    "c:/cad4u/lib"
}
$EXPORT_LIB The path to the output folder for generated binaries (libraries, program database, map files and executables).
This path can be absolute or else relative to the build folder.
base.xcpp sets $EXPORT_LIB to "../lib"
$EXPORT_TRANSLATED_INCLUDE The path to the output folder for pure C++ public header files (i.e header files which have been translated into C++ from Xc++).
This path can be absolute or else relative to the build folder.
base.xcpp sets $EXPORT_TRANSLATED_INCLUDE to "../include"
$EXPORT_UNTRANSLATED_INCLUDE The path to the output folder for untranslated public header files and other export artefacts.
This path can be absolute or else relative to the build folder.
base.xcpp sets $EXPORT_UNTRANSLATED_INCLUDE to "../export"
$COMPILE_FILE_PATH Used in modes compile and show.

For interfacing with the external tools of the MSVS IDE it is appropriate to assign $COMPILE_FILE_PATH the value of the MSVS ItemPath variable.

$TARGET_DIR Provides an alternative mechanism for specifying the target platform and configuration which is handy for interfacing to the external tools of the MSVS IDE which defines a variable named TargetDir equal to the absolute path of the OutputDirectory build setting. Note that BaseDefaults.xcpjh sets 

OutputDirectory = "$(EXPORT_LIB)/$(PLATFORM)/$(CONFIG)"

For example 


$TARGET_DIR=r'C:\developer\build_all\lib\x64\Debug\'

is equivalent to defining


platform = "x64"
config = "Debug"

These are the last two folders in the path.
virtualTree Specifies the virtual tree which represents the input to the build process. The variable virtualTree is assigned an ordered list of paths to the roots of the physical trees. These paths can be absolute or else relative to the build folder

base.xcpp sets 


virtualTree =
{
    "$(PATH_TO_ROOT)"
}

The virtual tree can be reassigned a different list of paths. This is useful for overriding the default virtual tree defined in base.xcpp . To append to the existing virtual tree use += instead of =. For example: 


virtualTree +=
{
    "acme/widgets"
}
diagnostics A boolean parameter which indicates whether to write more verbose information to stdout. Default = false.
exportPublicHeaders A boolean parameter which indicates whether to copy public header files from the input virtual tree to the output directory $EXPORT. Default = true.
repackageExecutableTargets A boolean parameter which indicates whether to copy dll and exe files from the input virtual tree to the output directory $EXPORT. Default = true.
solutionContainsPrepackagedProjects A boolean parameter which indicates whether pre-packaged projects in the input virtual tree are to appear in the MSVC solution. Default = true.
solutionContainsPrepackagedProjects A boolean parameter which indicates whether pre-packaged projects in the input virtual tree are to appear in the MSVC solution. Default = true.
makeExportedHeaderFilesReadOnly A boolean parameter which indicates whether public header files copied from the input virtual tree to the output directory $EXPORT will be made read only. Default = true.
translateOnly A boolean parameter which if true causes files to be written under build-artefacts/build/xcppsource without compiling and linking them using the MSVS compiler and linker. Default = false.
rebuildAll A boolean parameter which if true forces xcpp to rewrite all files under build-artefacts/build/xcppsource. Default = false.
writeTokenEquivalent A boolean parameter which indicates whether to rewrite files under build-artefacts/build/xcppsource that are token equivalent. Default = true.
makeTranslatedFilesReadOnly A boolean parameter which indicates whether xcpp translated files written under build-artefacts/build/xcppsource are made read only. Default = true.
targetXP A boolean parameter which indicates whether the MSVS generated project files should support the Windows XP platform. Default = false.
defaultToDll A boolean parameter which indicates whether projects having $TARGET_TYPE equal to "Library" are treated as "Dynamic-Link Library", otherwise "Static Library". Default = true.

Compiling and linking on Windows platforms

On Windows platforms xcpp.exe allows for building all the targets by running the C++ compiler, resource compiler and the linker itself. To allow this it must be provided with PATH, LIB and INCLUDE variables. The values of these variables must be white space delimited strings enclosed in curly braces. 


$MSVS = "c:/Program Files/Microsoft Visual Studio 8"

// VC8 professional
PATH =
{
    "$(MSVS)/VC/bin"
    "$(MSVS)/Common7/IDE"
    "$(MSVS)/VC/PlatformSDK/bin"
    "c:/windows"
    "c:/windows/system32"
}
INCLUDE =
{
    "$(MSVS)/VC/include"
    "$(MSVS)/VC/PlatformSDK/include"
    "$(MSVS)/VC/atlmfc/include"
}
LIB =
{
    "$(MSVS)/VC/lib"
    "$(MSVS)/VC/PlatformSDK/lib"
    "$(MSVS)/VC/atlmfc/lib"
}

compiler = vc8

targetXP = true

misc

There are a number of boolean flags that can also be set. These are detailed in the example of a .xcpp file given below: 


$MSVS = "c:/Program Files/Microsoft Visual Studio 8"

// VC8 professional
PATH =
{
    "$(MSVS)/VC/bin"
    "$(MSVS)/Common7/IDE"
    "$(MSVS)/VC/PlatformSDK/bin"
    "c:/windows"
    "c:/windows/system32"
}
INCLUDE =
{
    "$(MSVS)/VC/include"
    "$(MSVS)/VC/PlatformSDK/include"
    "$(MSVS)/VC/atlmfc/include"
}
LIB =
{
    "$(MSVS)/VC/lib"
    "$(MSVS)/VC/PlatformSDK/lib"
    "$(MSVS)/VC/atlmfc/lib"
}

compiler = vc8

virtualTree =
{
    "c:/dev/head"
    "c:/dev/utils/v2"
    "c:/dev/cad/v1"
}

$EXPORT = "../export"

// Enables writing of more verbose information
// to stdout
diagnostics = false

// Indicates whether to copy public header files
// from the input virtual tree to the output
// directory $EXPORT
exportPublicHeaders = true

// Indicates whether to copy dll and exe files
// from the input virtual tree to the output
// directory $EXPORT.
repackageExecutableTargets = true

// Indicates whether pre-packaged projects in
// the input virtual tree are to appear in the
// MSVC solution.
solutionContainsPrepackagedProjects = true

// Indicates whether public header files copied
// from the input virtual tree to the output
// directory $EXPORT will be made read only.
makeExportedHeaderFilesReadOnly = true

// Generate MSVC .vcproj and .sln files
mode = gen

Settings relevant to translation

The following settings are relevant to the translation mode available to xcpp.exe. Translation is outside the scope of this article. 


// If true causes xcpp to write the files under
// ./source without compiling and linking them
// using the VC compiler and linker.
translateOnly = false

// Forces xcpp to rewrite all files under
// ./source
rebuildAll = false

// Indicates whether to rewrite files under
// ./source that are token equivalent
writeTokenEquivalent = false

// Indicates whether xcpp translated files
// written under ./source are made read only.
makeTranslatedFilesReadOnly = true

Builtin xcpp files in Ceda/_BUILD/XcppConfig

  (root)
    └── Ceda
        └── _BUILD
            └── XcppConfig
                ├── base.xcpp
                ├── compiler.xcpp
                ├── msys2.xcpp
                └── selectcompiler.xcpp