com.codemesh.terp.ant.compiler.cpp
Class TargetOption

java.lang.Object
  com.codemesh.terp.ant.compiler.AbstractCompilerOption<CppCompiler>
      com.codemesh.terp.ant.compiler.cpp.TargetOption

All Implemented Interfaces:

CompilerOption<CppCompiler>, CppFileCreating, FileCreating<CppCompiler>

public class TargetOption
extends AbstractCompilerOption<CppCompiler>
implements CppFileCreating

Specifies the target of the C++ compilation. This is one of the key options of every compilation. With this option you specify:

• the target's name (without any prefixxes or suffixes).
• the target's type (archive, shared, executable).
• the target's subsystem (console or windows).
• the target's version (if supported by target type).
• the name of the .lib file when creating a shared library on Windows.
• whether or not to create dynamic links for versioned libraries on Unix/Linux.

A typical example of a target element that builds a versioned shared library might look like this:

     <target name="math"
             type="shared"
             version="${lib.version}"
     >
 

If lib.version is set to 1.0.5 this will result in:

• MacOS-X: libmath.dylib.1.0.5, libmath.dylib.1.0, libmath.dylib.1, libmath.dylib
• HP-UX, Solaris, Linux, AIX: libmath.so.1.0.5, libmath.so.1.0, libmath.so.1, libmath.so
• Windows: math.dll, math.lib

You can see how the <target> element treats the name you provide as a basename and applies the proper prefixes and suffixes for the type of target you are building.

Field Summary

static java.lang.String	CONSOLE
static java.lang.String	WINDOWS

Constructor Summary

TargetOption()

Method Summary

void	addCommands(java.util.List<java.lang.String> commandList, CppCompiler compiler, CompilerPhase phase) Adds the compiler switches repreesnted by this option to the list of switches.
boolean	appliesTo(CppCompiler compiler, CompilerPhase phase) Returns true if this compiler option applies to the given compiler and compiler phase.
java.util.List<java.lang.String[]>	calculateLinks(CppCompiler compiler) Returns a list of name pairs.
protected java.io.File	calculateTargetFile(CppCompiler compiler) Returns the primary target file.
java.util.List<java.lang.String>	creates(CppCompiler compiler, CompilerPhase phase) Returns a list of filenames representing the files that are created due to the presence of this compiler option.
java.lang.String	getImplib() Returns the .LIB filename.
java.lang.String	getInstallName() Returns the MacOS X-specific install name.
java.lang.String	getMakeLinks() Returns the configured value deciding whether or not to generate dynamic links for versioned libraries.
java.lang.String	getName() Returns the configured target basename.
java.lang.String	getSubsystem() Returns the Windows subsystem.
TargetType	getType() Returns the target type of the compiler invocation.
java.lang.String	getVersion() Returns the configured version number.
void	setImplib(java.lang.String implib) The name of the .LIB file on Windows (when building shared libraries).
void	setInstallName(java.lang.String name) A MacOS X-specific option that allows specification of an installname.
void	setMakeLinks(java.lang.String makeLinks) Specify true or false to decide whether to generate dynamic links for versioned libraries.
void	setName(java.lang.String name) Sets the target name.
void	setSubsystem(java.lang.String subsystem) Returns the subsystem being built.
void	setType(java.lang.String type) Sets the target type.
void	setVersion(java.lang.String version) Sets the file version.

Methods inherited from class com.codemesh.terp.ant.compiler.AbstractCompilerOption

expand, expand, getIf, getProject, getUnless, quoteIfNecessary, satisfies, setIf, setProject, setUnless

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

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

getIf, getUnless, satisfies, setIf, setUnless

Field Detail

CONSOLE

public static final java.lang.String CONSOLE

See Also:

Constant Field Values

WINDOWS

public static final java.lang.String WINDOWS

See Also:

Constant Field Values

Constructor Detail

TargetOption

public TargetOption()

Method Detail

setType

public void setType(java.lang.String type)

Sets the target type. Target type can be one of executable, archive, or shared. The bold parts of the strings are required.

Parameters:

type - the type string.

getType

public TargetType getType()

Returns the target type of the compiler invocation.

Returns:

the target type of the compiler invocation.

setSubsystem

public void setSubsystem(java.lang.String subsystem)

Returns the subsystem being built. This option only applies to compilation on Windows. Any non-null string is legal but terp only specifically understands the two strings "console" and "windows".

The default value is "console".

Parameters:

subsystem - the subsystem identifier.

getSubsystem

public java.lang.String getSubsystem()

Returns the Windows subsystem.

Returns:

the Windows subsystem.

setImplib

public void setImplib(java.lang.String implib)

The name of the .LIB file on Windows (when building shared libraries).

Parameters:

implib - the name of the .LIB file on Windows.

getImplib

public java.lang.String getImplib()

Returns the .LIB filename.

Returns:

the .LIB filename.

setName

public void setName(java.lang.String name)

Sets the target name. The target name is not normally the full filename of the file that's being created by the compiler. Only specify the name "root" or the "basename" of the file, without prefixes, suffixes, or directories.

For example: to build a shared library called foo.dll on Windows and libfoo.so.1.2.3 on Solaris, just specify name="foo". The version number will be appended automatically if you also set version="1.2.3".

Parameters:

name - the basename of the target file.

getName

public java.lang.String getName()

Returns the configured target basename.

Returns:

teh configured target basename.

setInstallName

public void setInstallName(java.lang.String name)

A MacOS X-specific option that allows specification of an installname. This is an optional attribute. When you set the installname, you completely take charge and we do not apply any mangling to the string you give us. This means that you must not forget the file extension (.dylib) and whatever framework or ELF version identifiers you want to add to the name.

Parameters:

name - the installname.

getInstallName

public java.lang.String getInstallName()

Returns the MacOS X-specific install name.

Returns:

the installname.

setVersion

public void setVersion(java.lang.String version)

Sets the file version. File versions are treated differently on different platforms. On Windows, they are embedded in the built module via the /VERSION linker option. On ELF-linker platforms, they get compiled into the shared library and they get appended to the filename. Only the major version number is compiled into the internal name whereas the full version is appended to the filename.

Specifying a version is optional.

Parameters:

version - the target version.

getVersion

public java.lang.String getVersion()

Returns the configured version number.

Returns:

the configured version number.

setMakeLinks

public void setMakeLinks(java.lang.String makeLinks)

Specify true or false to decide whether to generate dynamic links for versioned libraries.

Parameters:

makeLinks - true or false.

getMakeLinks

public java.lang.String getMakeLinks()

Returns the configured value deciding whether or not to generate dynamic links for versioned libraries.

Returns:

true or false

addCommands

public void addCommands(java.util.List<java.lang.String> commandList,
                        CppCompiler compiler,
                        CompilerPhase phase)

Adds the compiler switches repreesnted by this option to the list of switches. Some compiler options may result in more than one switch being added to a compiler invocation. Other compiler options may result in different options being added in different phases (compilation vs. linking) of the build.

This method is called by the compiler repeatedly with different values for the compiler phase to account for these possibilities.

Specified by:

addCommands in interface CompilerOption<CppCompiler>

Parameters:

commandList - the list to which the compiler switches represented by this option (if any) are added.

compiler - the compiler for which we're doing this.

phase - the compiler phase in wihch we're doing this.

calculateLinks

public java.util.List<java.lang.String[]> calculateLinks(CppCompiler compiler)

Returns a list of name pairs. The list is empty unless all of the conditions below are satisfied:

• makelinks is true.
• type is shared.

Each name pair has a versioned filename at index 0 and the less-specific versioned filename at index 1.

Parameters:

compiler - the compiler.

Returns:

a list of string arrays, each array containing 2 elements.

calculateTargetFile

protected java.io.File calculateTargetFile(CppCompiler compiler)

Returns the primary target file. The primary target file is the fully versioned, fully qualified target file.

For example, when building a shared library on Windows, the primary target file is a DLL (not a LIB). When building a versioned shared object on Unix, the primary target file is a file with version number appended to the name, for example libfoo.so.1.2.3. Based on other attributes, the compiler might generate additional files (.LIB files or version aliases) but they are irrelevant as far as this function is concerned.

Parameters:

compiler - the compiler.

Returns:

the primary target file.

appliesTo

public boolean appliesTo(CppCompiler compiler,
                         CompilerPhase phase)

Returns true if this compiler option applies to the given compiler and compiler phase. Not every option has switches to contribute for every compiler and every compilation phase. This method allows a quick, inexpensive check to filter out potentially more expensive calls later on.

Specified by:

appliesTo in interface CompilerOption<CppCompiler>

Parameters:

compiler - the compiler for which we're asking.

phase - the compiler phase we're executing.

Returns:

creates

public java.util.List<java.lang.String> creates(CppCompiler compiler,
                                                CompilerPhase phase)

Returns a list of filenames representing the files that are created due to the presence of this compiler option.

Specified by:

creates in interface FileCreating<CppCompiler>

Parameters:

compiler - the compiler.

phase - the compilation phase.

Returns:

a list of files, possibly empty.