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 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.
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.
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 |
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 |
The data types used by the CC task:
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:
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 |
Each of the nested elements may appear multiple times.
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.
An additional command-line argument to pass to the compiler.
A set of preprocessor macros to define and/or undefine. See the DefineSet data type for details.
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.
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.
A set of libraries to pass to the linker. See the LibSet data type for details.
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.
A command-line argument to pass to the linker.
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.
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>