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>