unicc - Unified High-Level Interface to C/C++ Compilers
#######################################################


Description
===========

The Perl script "unicc.pl" is a high-level interface to different C/C++
compilers. It takes a couple of source files, compiles them to object files, and
links these in order to create an executable, a static library or a dynamic
library. Each operation is performed only if the output file is not existing or
if it is not newer than the input files. Therefore, include file dependencies
are checked recursively, but only if found via an explicit given include path
(option --inc-search-dir). This normally means that standard include files are
not checked.


Examples
========

Here is a simple example for building a program using the GNU compiler:

  perl unicc.pl --compiler gnu hello.c --name hello

And here comes a more complex example:

  perl unicc.pl --compiler wat src/hello.c src/world.c --obj-dir obj \
   --lib-search-dir lib --inc-search-dir include --bin-dir bin \
   --debug --type wexe --name helloworld


Calling Conventions
===================

This chapter describes the arguments and options for calling unicc.pl. They can
be given in any order.

<src-file>
  Path name of a source file including the file name ending which must be ".c",
  ".cpp", ".cc" or ".cxx". On Windows, ".rc" files are also supported. This
  argument can be given multiple times.

--compiler <name>
  Name of the compiler. See the Compilers chapter more below for all possible
  names. The default is "gnu".

--cpus <count>
  Number of CPU's to be used. More precisely, it is the maximum number of source
  files to be compiled in parallel. The default is 1.

--type <type>
  Set the type of the output file. Possible types are:
    cexe    console executable
    wexe    windowed executable (different against cexe on Windows only)
    lib     static library
    dynlib  dynamic library
  The default is cexe.

--name <name>
  Set the name of the output file without ending, and, if it's a library,
  without the UNIX "lib" in front (Default: "unnamed").

--obj-dir <dir>
  Target directory for object files and other temporary files (default: ".").

--bin-dir <dir>
  Target directory for the executable (default: "."). Ignored if type is not
  cexe or wexe.

--lib-dir <dir>
  Target directory for the library, if type is lib or dynlib (default: "."). In
  addition, this option acts like --lib-search-dir.

--lib-search-dir <dir>
  A directory where to search for libraries to be linked. This option can be
  given multiple times.

--inc-search-dir <dir>
  A directory where to search for include files. This option can be given
  multiple times.

--link <name>
  Name of a library to be linked. The name must be without file name ending and
  without the UNIX "lib" in front (e.g. say "X11" instead of "libX11.a"). This
  argument can be given multiple times. The order may be important (high-level
  first).

--math
  Link with the standard math library.

--rtti
  Enable Run Time Type Information.

--exceptions
  Enable C++ exceptions.

--debug
  Create debug information in the output.

--def <name>[=<value>]
  Define a preprocessor variable. This option can be given multiple times.


Compilers
=========

Here comes a list of all possible values for the compiler option:

bor
  Use the Borland C/C++ compiler on Windows.
  *** Please do not use this for compiling Eagle Mode! ***
  It has been tested with Borland C++ 5.6.4 (C++BuilderX) and CodeGear C++ 5.9
  (C++Builder 2007), but Eagle Mode always crashes right away or it even fails
  to compile (seems difficult to solve).

gnu
  Use the GNU C/C++ compiler (gcc). This has been successfully tested with many
  gcc versions. Minimum should be something like version 3.3. Cygwin and MinGW
  are also supported.

int
  Use the Intel C/C++ compiler (icc) on Linux.
  Successfully tested with:
   * icc 9.1 on Linux, 64-bit

mic
  Use the Microsoft C/C++ compiler on Windows.
  Successfully tested with:
   * cl 13.10 (Visual Studio .NET 2003)
   * cl 14.00 AMD64 (Platform SDK for Server 2003 R2)

sun
  Use the Sun C/C++ compiler on Linux.
  Successfully tested with:
   * Sun Studio 12 RC 1 on Linux, 64-bit

wat
  Use the Watcom or Open Watcom C/C++ compiler on Windows.
  Successfully tested with:
   * Watcom 11.0b
   * Open Watcom 1.7a
