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.

Compiling

The CC task only attempts to compile files which end in the following suffixes: .c.cc.cxx.cpp, .c++. It ignores header files (those ending in .h), and passes all other input files 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.

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.

The CC task also keeps track of the compiler settings that were used to compile each object file. When the CC task runs, it determines whether the settings for each object file have changed since the object file was built. If the settings have changed, the CC task will recompile the file. For example, if you change the debug attribute from false to true in your build file, the CC task will recompile all files that were not compiled with debug enabled.

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.

The CC task keeps track of the linker settings used to link each output file. When the CC task runs, it will re-link the output file it its linker settings have changed.

Static or shared libraries can be included in the link by including them in nested <libset> or <fileset> elements.

Supported Compiler Toolsets

The CC task only handles a small number of different compiler toolsets, listed below. You can control which compiler and linker is used, by including nested <compiler> and <linker> elements, respectively.

If a compiler is not specified, the compiler from the default toolset for the OS platform is used. Currently GCC is the default toolset for all platforms.

If a linker is not specified, the linker is taken from the toolset that was used to compile.

The table below lists the supported toolsets, and lists which commands need to be in your PATH to use the toolset.

Name Description Platforms Required Tools
gcc The GNU Compiler Collection (GCC). This is the default compiler for all platforms. On Windows, this task works with the MinGW and Cygwin toolsets. All gcc, ar
libtool GNU Libtool. All libtool
msvc Microsoft Visual C++. This task works with version 6.0, may work with other versions. Windows cl, link, lib

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 Compiler Toolset Executable File Object File Shared Library Static Library
Windows - basename.exe basename.obj basename.dll basename.lib
UNIX libtool basename basename.lo libbasename.la libbasename.a
UNIX - basename basename.o libbasename.so libbasename.a

See Also

The data types used by the CC task:

Parameters

Attribute Description Required
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
objdir The directory to place object files. Default is to place the object files in the same directory as the output file. Yes, if link is set to none.
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

Parameters specified as nested elements

Each of the nested elements may appear multiple times.

compiler

Compiler specific configuration. See the CCompiler data type for details. The CC task uses the first <compiler> element that meets its if and unless conditions. If there is no such element, the default compiler for the OS platform is used.

compilerarg

An additional command-line argument to pass to the compiler.

defineset

A set of preprocessor macros to define and/or undefine. See the DefineSet data type for details.

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.

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.

libset

A set of libraries to pass to the linker. See the LibSet data type for details.

linker

Linker specific configuration. See the Linker data type for details. The CC task uses the first <linker> element that meets its if and unless conditions. If there is no such element, the default linker for the OS platform is used.

linkerarg

A command-line argument to pass to the linker.

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.

Examples

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

<cc outfile="build/someapp" >
    <fileset dir="src" />
</cc>

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

<cc outfile="build/someapp" >
    <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" >
    <fileset dir="src" />
    <defineset>
      <define name="SOMEDEF" />
    </defineset>
</cc>

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

<cc link="shared" outfile="build/lib/app" >
    <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" >
    <fileset dir="src" />
    <libset libs="pthread, dl" />
        <fileset dir="build/lib" />
    </libset >
</cc>

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

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

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

<target name="build">
    <!-- Use MSVC if building on Windows -->
    <condition property="use.msvc" >
        <os family="windows" />
    </condition>

    <!-- Build the shared library -->
    <cc debug="true" link="shared" outfile="build/lib/somelib" >
        <compiler name="msvc" if="use.msvc" />
        <fileset dir="src/somelib" />
        <includepath location="inc" />
        <sysincludepath location="/someotherproject/include" />
        <defineset refid="defs" />
        <defineset define="EXTRA_LIB_DEF" />
        <libset refid="libs" />
    </cc>

    <!-- Build the executable -->
    <cc debug="true" outfile="build/bin/someapp" >
        <compiler name="msvc" if="use.msvc" />
        <fileset dir="src/someapp" />
        <includepath location="inc" />
        <defineset refid="defs" />
        <libset refid="libs" />
        <libset >
            <fileset dir="build/lib" />
        </libset >
    </cc>
</target>