proposed C++ support

[Adam Murdoch]

Hi,

Last week, a couple of tasks were submitted to ant-dev, for adding C/C++
support to ant.  One proposal was from Mark Russell, another from myself.

After a bit of discussion and some helpful suggestions from various ant-dev
people, we've combined what we feel are the best features from both
proposals into a single proposal.  Attached are the user docs describing
what the new tasks will do.

Briefly, we're planning to add two new tasks and some supporting data-types.

The main task is called <cc>.  It compiles and links a set of C/C++ source
files into an executable, a shared library (DLL), or a static library.  It
takes care of things like header-file dependencies, and platform-specific
naming coventions.

The second task is called <cclink>.  It is a pared-down version of <cc>
which only does linking.  I haven't attached the doc for it.  Usage will be
the same as <cc>.

What we'd like from the ant-user folks is some feedback.  Have a read and
let us know what you think.


Adam

Title: Ant User Manual

CC

Description

Compiles and links a set of C and C++ source files into an executable, shared library (DLL), or static library.

The CC task invokes the C/C++ compiler on each out-of-date source file. Following successful compilation of the source files, the CC task invokes the linker to produce the output file. Linking may be disabled using the link attribute.

You specify the task's input files using one or more nested <fileset> elements. The sourcedir attribute can also be used as a shortcut. It creates an implicit fileset that recursively includes all files in a particular directory.

Compiling

The CC task only attempts to compile files which end in the following suffixes: .c,  .cc,  .cxx,  .cpp, .c++. Input files that are not recognized as source files are passed directly to the linker.

The CC task tracks the dependencies between the source files, and the header files that they include. It recompiles a source file if any of the header files that it includes changes. To do this, the CC task parses the source and header files when they change, and maintains a cache of the parsed information in basedir/.c_parser_cache.

To locate header files, the CC task searches the directories specified by nested <includepath> elements. It does not search the directories specified by nested <sysincludepath> elements. This way, you can reduce the amount of parsing the task performs by putting header files which are unlikely to change, such as those from external libraries, in <sysincludepath> elements.

Linking

The linker is only invoked if the output file is out-of-date. The CC task determines if the linker needs to be invoked by comparing the last-modified time of the output file against that of the object files and libraries included in the link. Incremental linking is used where available.

Static or shared libraries can be included in the link by including them in nested <libraryset> elements, or in the input file set.

Supported Compilers

The CC task only handles a small number of different compilers and linkers, listed below. You can control which compiler to use with the compiler attribute. For example, on Windows, where Visual C++ and GCC are both supported, set compiler="vc" to use the Visual C++ compiler and linker.

The table below lists the supported compilers, and lists which command-line tools need to be in your PATH to use the compiler.

Name	Description	Platforms	Required Tools
gcc	The GNU Compiler Collection (GCC). This is the default compiler for all platforms. This task works with the MinGW toolset on Windows, and may also work with the Cygwin toolset.	UNIX, Windows	gcc, ar
vc	Microsoft Visual C++. This task works with version 6.0, may work with other versions.	Windows	cl, link, lib
xlc_r	IBM xlC_r Compiler.	AIX	xlC_r, ar
sunstudio	Sun Workshop. This task works with version 4.2, may work with other versions.	Solaris	CC, ar

Name Mapping

The CC task takes care of mapping file names, according to the naming convention for the OS platform that the build is running on. The table below describes the mappings for the various platforms and file types. In this table, basename refers to the file name, minus the directory path and the extension.

Operating System	Executable File	Object File	Shared Library	Static Library
Windows	basename.exe	basename.obj	basename.dll	basename.lib
Other	basename	basename.o	libbasename.so	libbasename.a

See Also

The CCLink task, the DefineSet data type, and the LibrarySet data type.

Parameters

Attribute	Description	Required
compiler	The compiler to use. See above for the list of supported compilers.  If not specified will default to GCC	No
debug	Enables the generation of debug information in the output files.	No
link	The type of output file to produce. Possible values are: none Does not produce an output file. executable Produces an executable file. shared Produces a shared library. static Produces a static library. Default is executable.	No
objdestdir	The directory to place object files.	Yes
outfile	The name of the output file. The CC task maps this file name depending on the output type and OS platform the build is running on (see above).	Yes, if link is not set to none
sourcedir	The directory containing the source files.	Yes, or at least one nested <fileset> element.

Parameters specified as nested elements

compilerarg

An additional command-line argument to pass to the compiler. There may be more than one nested <compilerarg> element.

defineset

A set of preprocessor macros to define and/or undefine. See DefineSet for more details. There may be more than one nested <defineset> element.

fileset

A Fileset that specifies the input files for the task. Files that are recognised as C or C++ source files are passed to the compiler. All other files are passed directly to the linker. There may be more than one nested <fileset> element.

includepath

A Path that specifies the directories to use when searching for header files. This path is passed to the compiler, and is used by the CC task when it is performing header file dependency checking. There may be more than one nested <includepath> element.

libpath

A Path that specifies the directories to use when searching for the libraries listed in the libs attribute. There may be more than one nested <libpath> element.

linkerarg

A command-line argument to pass to the linker. There may be more than one nested <linkerarg> element.

sysincludepath

A Path that specifies the directories to use when searching for system header files. This path is passed to the compiler. It is not used by the CC task when it is performing header file dependency checking. There may be more than one nested <sysincludepath> element.

Examples

The example below compiles all the source files under the src directory, and links them into build/bin/someapp (build\bin\someapp.exe). It places the object files in the build/obj directory.

<cc sourcedir="src" outfile="build/bin/someapp" objdestdir="build/obj" />

The example below builds an executable from source files in two 
different directories.  It uses header files from 
src/somelib.
 

<cc outfile="build/bin/someapp" objdestdir="build/obj" >
    <fileset dir="src/common" />
    <fileset dir="src/server" />
    <includepath location="src/somelib" />
</cc>


The example builds an executable, defining the preprocessor macro 
SOMEDEF during compilation.
 

<cc outfile="build/lib/someapp" objdestdir="build/obj" >
    <fileset dir="src" />
    <defineset>
      <define name="SOMEDEF" />
    </defineset>
</cc>


The example below builds a shared library called 
build/lib/libapp.so (build\lib\app.dll).
 

<cc link="shared" outfile="build/lib/app" objdestdir="build/obj" >
    <fileset dir="src" />
</cc>


The example builds an executable, linking against the libraries 
pthread and dl, and all the libraries in directory
build/lib.
 

<cc outfile="build/lib/someapp" objdestdir="build/obj" >
    <fileset dir="src" />
    <libraryset libs="pthread, dl">
      <fileset dir="build/lib" />
    </libraryset>
</cc>


Below is a more complete example.  It uses GCC to build debug versions 
of a shared library, and an executable that uses the shared library.
 

<!-- Define a common set of libraries -->
<libraryset id="libs">
    <fileset dir="lib" />
    <fileset dir="/someotherproject/lib" />
</libraryset>

<!-- Define a common set of macros -->
<defineset id="defs">
    <define name="DEBUG" />
    <define name="SOMEDEF" value="1"/>
    <undefine name="UNWANTEDDEF" />
</defineset>

<target name="build">

    <!-- Build a shared library -->
    <cc compiler="gcc" debug="true" link="shared" outfile="build/lib/somelib" objddestdir="build/obj">
        <fileset dir="src/somelib" />
        <includepath location="inc" />
        <sysincludepath location="/someotherproject/include" />
        <defineset refid="defs" />
        <defineset define="EXTRA_DEF" />
        <libraryset refid="libs" />
        <linkerarg value="-somearg" />
    </cc>
    
    <!-- Build an executable -->
    <cc compiler="gcc" debug="true" outfile="build/lib/someapp" objddestdir="build/obj">
        <fileset dir="src/someapp" />
        <includepath location="inc" />
        <defineset refid="defs" />
        <libraryset refid="libs" />
        <libraryset>
            <fileset dir="build/lib" includes="*somelib*" />
        </libraryset>
        <compilerarg value="-somearg" />
    </cc>
</target>







Title: Ant User Manual






DefineSet
Description
  
A datatype that defines a set of C preprocessor macros.
  
See Also

The CC task.

Parameters


  

    
Attribute
    
Description
    
Required
  

  

    
define
    
A comma-separated list of preprocessor macros to define.
    These take the form macro[=value].
    
No
  
  
  

    
undefine
    
A comma-separated list of preprocessor macros to undefine.
    
No
  
  
  

    
refid
    
A reference to another <defineset>.  
    No other attributes or nested elements may be used with this attribute.
    
No
  
  


Parameters specified as nested elements

define

Defines a preprocessor macro.  It takes the following attributes:
 


  

    
Attribute
    
Description
    
Required
  

  

    
name
    
The name of the macro to define.
    
Yes
  
  
  

    
value
    
The value to set the macro to.
    
No
  
  


undefine

Undefines a preprocessor macro.  It takes a single name 
attribute.
 

Examples

Below is a define set which defines two macros, SOMEDEF
and ANOTHERDEF.
 

<defineset define="SOMEDEF, ANOTHERDEF" />


Below is a define set which defines the same macros, using nested elements.

<defineset>
    <define name="SOMEDEF" />
    <define name="ANOTHERDEF" />
</defineset>


Below is a define set which gives macro SOMEDEF the value 1, 
and undefines macro UNWANTEDDEF.

<defineset>
    <define name="SOMEDEF" value="1" />
    <undefine name="UNWANTEDDEF" />
</defineset>








Title: Ant User Manual






LibrarySet
Description
  
A datatype that defines a set of static and shared libraries to include
when linking an output file.
  
See Also

The CC task.

Parameters


  

    
Attribute
    
Description
    
Required
  

  

    
libs
    
A comma-separated list of the libraries to include in the
    link.  Names in this list should be the library's basename.
    
No
  
  
  

    
refid
    
A reference to another <libraryset>.  
    No other attributes or nested elements may be used with this attribute.
    
No
  
  


Parameters specified as nested elements

fileset

A Fileset that contains the libraries to include in the library set.  There 
may be more than one nested <fileset> element.

Examples

The example below defines a library set that contains the libraries 
pthread and dl.

<libraryset libs="pthread, dl" />


The example below defines a library set that contains all the files in
build/lib.

<libraryset>
    <fileset dir="build/lib" />
</libraryset>