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


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

The Perl scripts in this directory are for building C/C++ programs using
different compilers. All scripts have the same calling conventions. They take a
couple of source files, compile them to object files, and link 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_gnu.pl hello.c --name hello

And here comes a more complex example:

  perl unicc_wat.pl 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 the unicc scripts.
They can be given in any order.

<src-file>
  Path name of a source file including the file name ending which must be either
  ".c", ".cpp", ".cc" or ".cxx". This argument can be given multiple times.

--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.


Implementations
===============

bor (unicc_bor.pl)
  Uses 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 (unicc_gnu.pl)
  Uses 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.

gnu_x2 (unicc_gnu_x2.pl)
  This is like above, but it compiles up to two source files in parallel for
  taking advantage of two processors or processor cores. It is an experimental
  solution, but it works.

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

mic (unicc_mic.pl)
  Uses 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 (unicc_sun.pl)
  Uses the Sun C/C++ compiler on Linux.
  Successfully tested with:
   * Sun Studio 12 RC 1 on Linux, 64-bit

wat (unicc_wat.pl)
  Uses the Watcom or Open Watcom C/C++ compiler on Windows.
  Successfully tested with:
   * Watcom 11.0b
   * Open Watcom 1.7a


Possible future plans
=====================

- Add an option for parallel compilation on multi-processor/core systems.

- The scripts are identical in large parts. These parts could go into a common
  library or framework.

- Clearly, support for more compilers and operating systems.
