From ant-user-return-9331-apmail-jakarta-ant-user-archive=jakarta.apache.org@jakarta.apache.org Mon Jun 25 07:49:30 2001 Return-Path: Delivered-To: apmail-jakarta-ant-user-archive@jakarta.apache.org Received: (qmail 79119 invoked by uid 500); 25 Jun 2001 07:49:21 -0000 Mailing-List: contact ant-user-help@jakarta.apache.org; run by ezmlm Precedence: bulk List-Post: List-Help: List-Unsubscribe: List-Subscribe: Reply-To: ant-user@jakarta.apache.org Delivered-To: mailing list ant-user@jakarta.apache.org Received: (qmail 79098 invoked from network); 25 Jun 2001 07:49:17 -0000 From: "Adam Murdoch" To: Subject: proposed C++ support Date: Mon, 25 Jun 2001 17:52:32 +1000 Message-ID: MIME-Version: 1.0 Content-Type: multipart/mixed; boundary="----=_NextPart_000_0007_01C0FD9F.9C089750" X-Priority: 3 (Normal) X-MSMail-Priority: Normal X-Mailer: Microsoft Outlook IMO, Build 9.0.2416 (9.0.2910.0) Importance: Normal X-MimeOLE: Produced By Microsoft MimeOLE V5.50.4133.2400 X-Spam-Rating: h31.sny.collab.net 1.6.2 0/1000/N This is a multi-part message in MIME format. ------=_NextPart_000_0007_01C0FD9F.9C089750 Content-Type: text/plain; charset="iso-8859-1" Content-Transfer-Encoding: 7bit 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 . 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 . It is a pared-down version of which only does linking. I haven't attached the doc for it. Usage will be the same as . What we'd like from the ant-user folks is some feedback. Have a read and let us know what you think. Adam ------=_NextPart_000_0007_01C0FD9F.9C089750 Content-Type: text/html; name="cc.html" Content-Transfer-Encoding: quoted-printable Content-Disposition: attachment; filename="cc.html" Ant User Manual

CC

Description

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

=20

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

=20

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

=20

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=20 are passed directly to the linker.

=20

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=20 header files that it includes changes. To do this, the CC task parses = the=20 source and header files when they change, and maintains a cache of the=20 parsed information in basedir/.c_parser_cache.

=20

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

=20

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=20 last-modified time of the output file against that of the object files = and=20 libraries included in the link. Incremental linking is used where = available.

=20

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

=20

Supported Compilers

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

=20

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

=20 =20 =20 =20
Name Description Platforms Required Tools
gcc The GNU Compiler Collection (GCC).

This is the default compiler for all platforms. This task works = with the=20 MinGW toolset on Windows, and = may also work with the Cygwin=20 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=20 below describes the mappings for the various platforms and file types. = In=20 this table, basename refers to the file name, minus the directory = path and the extension.

=20 =20 =20
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
=20

See Also

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

=20

Parameters

=20 =20 =20 =20 =20 =20 =20 =20 =20
Attribute Description Required
compiler The compiler to use. See above for the list of=20 supported compilers.  If not specified will default to GCC No
debug Enables the generation of debug information in = the output=20 files. No
link The type of output file to produce. Possible = values=20 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
objdestdirThe directory to place object files. Yes
outfile The name of the output file. The CC task maps = this file=20 name depending on the output type and OS platform the build is = running on=20 (see above). Yes, if link is not = set to none
sourcedir The directory containing the source files. Yes, or at least one nested=20 <fileset> element.

Parameters specified as nested elements

compilerarg

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

=20

defineset

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

fileset

=20

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

includepath

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

libpath

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

linkerarg

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

=20

sysincludepath

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

=20

Examples

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

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

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

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

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

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

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

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

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

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

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

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

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

<target name=3D"build">

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

------=_NextPart_000_0007_01C0FD9F.9C089750 Content-Type: text/html; name="defineset.html" Content-Transfer-Encoding: quoted-printable Content-Disposition: attachment; filename="defineset.html" Ant User Manual

DefineSet

Description

=20

A datatype that defines a set of C preprocessor macros.

=20

See Also

The CC task.

Parameters

=20 =20 =20
Attribute Description Required
define A comma-separated list of preprocessor macros to = define. These take the form macro[=3Dvalue]. No
undefine A comma-separated list of preprocessor macros to = undefine. No
refid A reference to another = <defineset>. =20 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:

= =20 =20
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=20 attribute.

=20

Examples

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

=20
<defineset define=3D"SOMEDEF, ANOTHERDEF" />

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

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

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

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

------=_NextPart_000_0007_01C0FD9F.9C089750 Content-Type: text/html; name="libraryset.html" Content-Transfer-Encoding: quoted-printable Content-Disposition: attachment; filename="libraryset.html" Ant User Manual

LibrarySet

Description

=20

A datatype that defines a set of static and shared libraries to = include when linking an output file.

=20

See Also

The CC task.

Parameters

=20 =20
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>. =20 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=20 may be more than one nested <fileset> element.

Examples

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

<libraryset libs=3D"pthread, dl" />

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

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

------=_NextPart_000_0007_01C0FD9F.9C089750--