com.codemesh.terp.ant.compiler.cpp
Interface CppCompiler

All Superinterfaces:

Compiler<CppCompiler>, CppCompilerOptions, TerpAware, TerpContextHolder

All Known Implementing Classes:

Acc.Impl, CppCompilerImpl, Gcc.Impl, Icc.Impl, Msvc.Impl, Qcc.Impl, Suncc.Impl, Xlc.Impl

public interface CppCompiler
extends Compiler<CppCompiler>, CppCompilerOptions

The base interface implemented by all C++ compilers. This interface establishes the basic contract that all C++ compilers need to implement. Concretely, this interface is only implemented by the CppCompilerImpl type, which handles all C++ supported C++ compilers. There are CppCompilerImpl subtypes, but they only mix in one of the compiler-type marker interfaces. Using one of these maker-specific compiler types determines which found compilers are eligible to be wrapped by the C++ task. Using the CppCompilerImpl base type leaves all found compilers eligible.

Currently, the following compilers are supported:

Compiler	Code	Specific Type	Description
aCC	acc	Acc.Impl	The HP ANSI C++ compiler
g++	gcc	Gcc.Impl	The GNU C++ compiler
icc	icc	Icc.Impl	The Intel C++ compiler
cl.exe	msvc	Msvc.Impl	The Microsoft Visual C++ compiler
CC	suncc	Suncc.Impl	The SUN Workshop C++ compiler
xlC	xlc	Xlc.Impl	The IBM VisualAge C++ compiler

We would be happy to add other C++ compilers upon request.

Nested Class Summary

static class

CppCompiler.SourceToTargets

Nested classes/interfaces inherited from interface com.codemesh.terp.ant.TerpAware

TerpAware.Delegate

Method Summary

DynamicSourcesOption	createDynamicSources() Creates a nested task container that groups TerpEcho tasks which are used to dynamically generate source code files that are automatically added to the compilation.
VsProjectOption	createGenerateVsProject() Creates an option that generates a VisualStudio project file.
ObjectsOption	createObjects() Creates an option that adds already compiled object files to the build.
OptionsOption	createOptions() Creates an option representing a reference to an external options collection.
TerpSequential	createPostBuild() Creates a task container that is executed after the compiler chas been invoked.
TerpSequential	createPreBuild() Creates a task container that is executed before any compiler commands are invoked.
ProcArchOption	createProcArch() Creates an option that specifies the processor architecture for which we're building.
ProfileOption	createProfile() Creates an option that instruments the code with profiling support.
ResourceOption	createResource() Creates an option that dynamically generates a resource file.
SourcesOption	createSources() Creates an option that adds source files to the build.
TargetOption	createTarget() Creates an option that governs name, version, and type of build target.
java.io.File	getBaseDir() Returns a directory treated as the base directory for the compilation operation.
java.util.List<CppCompiler.SourceToTargets>	getCompilationSources(boolean bIncludeDynamics) Returns a list of compilation sources and the targets they're tied to.
Cpp.CppExecutor	getCompiler() Returns the compiler executor being used.
boolean	getCreateDirs() Returns true if target and temporary directories are being created on-demand.
java.lang.String	getTargetDir() Return the configured target directory in which build outputs are created.
java.lang.String	getTargetNameProperty() Return the name of a property that will hold the name of the primary build result of the compiler invocation.
java.util.Map<java.lang.String,java.lang.Object>	getTraits() Returns the map of known compiler traits.
void	setBatchSize(java.lang.String batchSize) Sets the number of source files that will be given to the compiler in one invocation.
void	setBOM(java.lang.String bom) Sets the file that will contain the generated bill of materials, i.e.
void	setCleanup(java.lang.String cleanup) Set to true if result and intermediate files should be deleted rather than created.
void	setCompiler(java.lang.String compiler) Specify the compiler that is to be used.
void	setCppExtensions(java.lang.String cppExts) Sets the extensions that are interpreted as C/C++ sources that are passed to the compiler.
void	setCreateDirs(java.lang.String create) Create target and intermdiate directories if they don't already exist.
void	setDepends(java.lang.String depends) Set to true if dependency files should be generated (if necessary).
void	setFailOnError(java.lang.String foe) True if compiler wrapper should abort when a compilation error is encountered.
void	setForceBuild(java.lang.String fb) True if compiler wrapper should always perform the buildsteps, whether required based on dependency analysis or not.
void	setMaxParallel(java.lang.String maxParallel) Specifies how many compiler invocations may run in parallel.
void	setParallel(java.lang.String parallel) True if parallel mode is enabled.
void	setShowOnly(java.lang.String so) Suppresses actual tool invocations and only shows the commands that would be executed.
void	setTargetDir(java.lang.String targetDir) The target directory to which output files (exe, dll, archive) are written.
void	setTargetNameProperty(java.lang.String propertyName) The name of a property that will hold the name of the primary build result of the compiler invocation.
void	setTempDir(java.lang.String tempDir) The temporary directory to which intermediary files (obj, etc.) are written.

Methods inherited from interface com.codemesh.terp.ant.compiler.Compiler

addOption, getCode, getContext, getOptions, getVersion

Methods inherited from interface com.codemesh.terp.ant.TerpAware

getIf, getUnless, satisfiesConditions, setIf, setUnless

Methods inherited from interface com.codemesh.terp.ant.TerpContextHolder

setContext

Methods inherited from interface com.codemesh.terp.ant.compiler.cpp.CppCompilerOptions

createBoundsCheck, createCompileOnly, createDebug, createDefine, createExceptions, createInclude, createLibpath, createLibrary, createManifest, createMultithreaded, createOptimize, createOption, createQuiet, createRelocatable, createRtti, createRunpath, createRuntime, createUndefine, createWarning, getOptions

Method Detail

getBaseDir

java.io.File getBaseDir()

Returns a directory treated as the base directory for the compilation operation. This directory will typically be the ANT project's basedir, but if the CppCompiler interface were implemented by a type that does not extend ANT Task, it could be derived from another build variable.

The purpose of this function is to provide a reference location for the creation of relative paths, for example when generating VisualStudio projects.

Returns:

the compilation's reference directory.

setBOM

void setBOM(java.lang.String bom)

Sets the file that will contain the generated bill of materials, i.e. the source files, the build options, etc. This value can be expanded by terp.

Parameters:

bom - the filename.

setBatchSize

void setBatchSize(java.lang.String batchSize)

Sets the number of source files that will be given to the compiler in one invocation. If the total set of sources is larger, the compiler will be invoked multiple times.

Parameters:

batchSize - the number of sources in one compiler invocation.

setCleanup

void setCleanup(java.lang.String cleanup)

Set to true if result and intermediate files should be deleted rather than created.

Parameters:

cleanup - true for cleanup, false for regular compilation.

setDepends

void setDepends(java.lang.String depends)

Set to true if dependency files should be generated (if necessary).

Parameters:

depends - true if dependency files should be generated, false if not.

setCreateDirs

void setCreateDirs(java.lang.String create)

Create target and intermdiate directories if they don't already exist.

Parameters:

create - true if directories should be created, false otherwise.

getCreateDirs

boolean getCreateDirs()

Returns true if target and temporary directories are being created on-demand.

Returns:

true if directories are being created on-demand.

setCompiler

void setCompiler(java.lang.String compiler)

Specify the compiler that is to be used. The compiler specifier works in conjunction with the task type. The compiler specifier should consist of a terp expression that can be converted to a C++ compiler executor. Here are some examples:

Example 1

The simplest and most generic compiler specifier is probably

 compiler="{}"
 

It specifies an empty list, i.e. no configuration arguments. That leaves the terp framework with complete freedom to pick a compiler.

Example 2

In this example, we specify a compiler by version number.

 compiler="{version:3.4}"
 

This would for example successfully pick a g++ 3.4.6 compiler if one had been identified by the framework. This is also synonymous with the simplified form of

 compiler="3.4"
 

A numeric string is always interpreted as a version number. Just be careful with version numbers like "13.10" because they degenerate to the number 13.1 which does not match 13.10. In this case you will have to use a string version number as in:

 compiler="{version:"13.10"}"
 

Example 3

You can also create a compiler specifier from a compiler executable:

 compiler="{compiler:"C:/Program Files/Microsoft Visual Studio 8/VC/bin/cl.exe"}"
 

In this case, the terp framework will figure out version numbers and other compiler attributes via compiler reflection.

Example 4

The terp C++ compiler abstraction is most powerful when you have to build your software with multiple compiler versions, in multiple configurations. consider the following example:

 <terp.foreach name="pa" expression="{x86,amd64}">
   <terp.foreach name="vers" expression="{13,14,15}">
     <terp.foreach name="debug" expression="{true,false}">
       <terp.cpp compiler="^msvc({procarch:pa, version:vers})"
                 targetDir="${basedir}/out/${pa}/v${vers}/${if(debug)}debug${else}release$end}"
                 tempDir="${basedir}/temp/${pa}/v${vers}/${if(debug)}debug${else}release$end}"
       >
         <debug value="${debug}"/>
         ...
       </terp.foreach>
     </terp.foreach>
   </terp.foreach>
 </terp.foreach>
 

In this example we have a triple-nested loop over processor architectures, compiler versions, and release vs. debug build mode. The compiler invoked inside the nested loops and always picks the correct compiler executable

Parameters:

compiler - the compiler specifier.

getCompiler

Cpp.CppExecutor getCompiler()

Returns the compiler executor being used.

Returns:

a compiler executor.

getTraits

java.util.Map<java.lang.String,java.lang.Object> getTraits()

Returns the map of known compiler traits. Compiler traits are properties that are determined either via compiler reflection or via the built-in expert system that comes with terp.

Returns:

the map of traits.

setCppExtensions

void setCppExtensions(java.lang.String cppExts)

Sets the extensions that are interpreted as C/C++ sources that are passed to the compiler.

Parameters:

cppExts - a comma- or semicolon-separated list of extensions.

setFailOnError

void setFailOnError(java.lang.String foe)

True if compiler wrapper should abort when a compilation error is encountered. The default value is true.

Parameters:

foe - true when compilation should be terminated in case of error.

setForceBuild

void setForceBuild(java.lang.String fb)

True if compiler wrapper should always perform the buildsteps, whether required based on dependency analysis or not.

Parameters:

fb - true when buildsteps should be performed unconditionally.

setMaxParallel

void setMaxParallel(java.lang.String maxParallel)

Specifies how many compiler invocations may run in parallel.

Parameters:

maxParallel - the maximum number of parallel invocations.

setParallel

void setParallel(java.lang.String parallel)

True if parallel mode is enabled.

Parameters:

parallel - parallel mode.

setShowOnly

void setShowOnly(java.lang.String so)

Suppresses actual tool invocations and only shows the commands that would be executed. Similar to the -dryrun option provided by some compilers, but implemented in the compiler wrapper.

Parameters:

so - true when tool invocations should be suppressed.

setTargetDir

void setTargetDir(java.lang.String targetDir)

The target directory to which output files (exe, dll, archive) are written. This directory is terp expanded.

Parameters:

targetDir - the output directory.

getTargetDir

java.lang.String getTargetDir()

Return the configured target directory in which build outputs are created.

Returns:

the target directory.

setTargetNameProperty

void setTargetNameProperty(java.lang.String propertyName)

The name of a property that will hold the name of the primary build result of the compiler invocation. This property can subsequently be used to test whether the file was created or not.

Parameters:

propertyName - a property name.

getTargetNameProperty

java.lang.String getTargetNameProperty()

Return the name of a property that will hold the name of the primary build result of the compiler invocation. By default, this method returns null, i.e. the compiler invocation does not create a property holding the name of a file.

Returns:

a property name or null.

setTempDir

void setTempDir(java.lang.String tempDir)

The temporary directory to which intermediary files (obj, etc.) are written.

Parameters:

tempDir - the intermediate file directory.

getCompilationSources

java.util.List<CppCompiler.SourceToTargets> getCompilationSources(boolean bIncludeDynamics)

Returns a list of compilation sources and the targets they're tied to.

Parameters:

bIncludeDynamics - true if dynamically generated sources should be included.

Returns:

a list of source-to-target instances.

createDynamicSources

DynamicSourcesOption createDynamicSources()

Creates a nested task container that groups TerpEcho tasks which are used to dynamically generate source code files that are automatically added to the compilation. This option is extremely useful for the generation of source code that derives information from the context at runtime. You can for example embedd information about the version, the compiler, the compiler options, etc. in the source code to provide an info API.

Returns:

a task container containing tasks that generate dynamic sources.

createGenerateVsProject

VsProjectOption createGenerateVsProject()

Creates an option that generates a VisualStudio project file. This option only applies to the MSVC++ and Intel C++ compilers on Windows but it is harmless when used with other compilers or platforms.

Returns:

a newly created GenerateVsProject.

createObjects

ObjectsOption createObjects()

Creates an option that adds already compiled object files to the build. Adding object files that have been compiled with a different set of compiler switches is a recipe for disaster, so be very careful when using this option.

Returns:

a newly created ObjectsOption.

createOptions

OptionsOption createOptions()

Creates an option representing a reference to an external options collection. The external options collection is identified by an object id. If no external options collection

Returns:

a reference to the external options collection.

createProcArch

ProcArchOption createProcArch()

Creates an option that specifies the processor architecture for which we're building. Processor architectures are an interesting issue. With some compilers, there are different executables for different processor architectures and all you do is choose the proper compiler; you don't supply a compiler option. With other compilers, the same compiler executable can generate code for more than one processor architecture. Typically, support is limited to building a 32-bit or a 64-bit version, but on MacOS X you can build so-called universal binaries that include several architectures at once.

Returns:

a newly created ProcArchOption.

createProfile

ProfileOption createProfile()

Creates an option that instruments the code with profiling support.

Returns:

a newly created ProfileOption.

createResource

ResourceOption createResource()

Creates an option that dynamically generates a resource file. Resource files are only known on Windows, so this is a no-op for most compilers.

Returns:

a newly created ResourceOption.

createSources

SourcesOption createSources()

Creates an option that adds source files to the build. Source files are not limited to C++ sources, they could also include .DEF files, .RC files, or other supported input files. The compiler abstraction sorts them into the appropriate "buckets" for compilation or linking.

Returns:

a newly created SourcesOption.

createTarget

TargetOption createTarget()

Creates an option that governs name, version, and type of build target.

Returns:

a newly created TargetOption.

createPreBuild

TerpSequential createPreBuild()

Creates a task container that is executed before any compiler commands are invoked. This could be used to instrument source code or check additional code out of source control, or really anything you want.

Returns:

a task container.

createPostBuild

TerpSequential createPostBuild()

Creates a task container that is executed after the compiler chas been invoked. This could be used to clean up after a build, to stage files to different locations, to post-process build results (strip, instrument,...) or really anything you want.

Returns:

a task container.