POCO C++ Libraries GNU Make Build System
AAAIntroduction

!!!Introduction

The POCO C++ Libraries use a built system based on
[[http://www.gnu.org/software/make/ GNU Make]] on every platform
capable of running it. This includes Linux, Mac OS X, virtually
every other Unix platform, as well as Cygwin and MinGW on Windows.

Why GNU Make? Well, GNU Make is available virtually everywhere
and it's usually readily available, such as on Linux and Mac OS X.
Sure, there are more advanced build systems out there, but the
philisophy for POCO is download -- compile -- go. Requiring the user
to download and install another build tool just for getting
POCO to work is unacceptable.

The build system consists of a number of make files, as well as a few
supporting shell scripts. All core files are located within the <*build*>
directory in the POCO distribution. For every library and executable,
there is a small make file describing the kind of project,
its input files, and the output.

The POCO build system automatically determines the dependencies
between source and header files. This is done when a source file is
compiled for the first time, or after a source file has been changed.
This relieves the developer from the tedious task of maintining file
dependencies manually - one of the biggest drawbacks of GNU Make.


!!Build System Features

The POCO build system supports the following features:

  * building libraries, applications and plugins
  * debug and release builds
  * dynamic and static linking
  * 32-bit and 64-bit builds
  * automatic dependency detection
  * easy to use
  * support for cross-compiling for embedded platforms
    such as Embedded Linux or iOS


!!Build System Overview

The core of the build system consists of three different kinds of files --
platform configuration files, make rules and shell scripts. All are located
in the <*build*> directory within the POCO C++ Libraries root directory.

  build/
    config/
      Darwin
      Linux
      HP-UX
      ...

    rules/
      compile
      dylib
      exec
      global
      lib

    script/
      makedepend.gcc
      makedepend.cxx
      makedepend.SunCC
      makeldpath
      projname
      shlibln
      ...
----


!Configuration Files

Configuration files contain all the knowledge how the toolchain (compiler and linker)
must be invoked for a given platform. Configuration files for the most common
Unix platforms and their toolchains, as well as for Cygwin and MinGW are already
part of POCO.
Support for an additional platform (or a variation of a platform) can be added
by creating a new (or copying and modifying) an existing build configuration file.

Configuration files are located in the <*build/config*> directory.


!Rule Files

Rule files contain platform independent make rules for compiling and
linking executables or (static and shared) libraries from source files,
using the tools defined in a configuration file. Rule files are located
in the <*build/rules*> directory.


!Script Files

Script files are called by the build system's make files to do things that
cannot be expressed in make files. For example, there are scripts for
invoking a particular C++ compiler in such a way that it produces a list of
dependencies for later inclusion by the build system. Script files are
located in the <*build/script*> directory.



!!Filesystem Layout

!Sources

The build system expects a project's files (header files, source files, Makefiles)
to be in a certain directory layout.
First, all project directories must be located in or under the same directory where the
<*build*> directory is located, or in a directory below.
All header files must be in the <*include*> directory (or a subdirectory of it).
All source files must be in the <*src*> directory.
Finally, there must be a Makefile (named <*Makefile*>) located in the project directory.

Below is a sample for a POCO source directory hierarchy:

  poco/
    build/
    Foundation/
    Net/
    Util/
    XML/
    ...

    MyLib/
      include/
        MyLib.h
        MyClass.h

      src/
        MyClass.cpp

      Makefile
----


!Build Products

The POCO build system puts final build products (executables and libraries)
and intermediate products (object files, dependency files) into certain directories.
Unless specified otherwise (by setting the environment variable
POCO_BUILD accordingly -- see below), these directories are located within
the source directory tree. All libraries are put into a
directory with the path <*lib/<OSNAME>/<OSARCH>*>, within the POCO base directory.
Executables are put into a directory with the path <*bin/<OSNAME>/<OSARCH>*>,
within the project directory. Object files are put into a directory with the
path <*obj/<OSNAME>/<OSARCH>*>, within the project directory.
Dependency files are put into <*.dep/<OSNAME>/<OSARCH>*>,
also within the project directory.

Unless specified otherwise (by setting the Makefile variables
<[$(POCO_TARGET_OSNAME)]> and <[$(POCO_TARGET_OSARCH)]>, <*<OSNAME>*> is the
name of the host's operating system, as obtained by a call to
<*uname*> (or something equivalent), and <*<OSARCH>*> is the name of the
host's hardware architecture, as obtained by a call to <*uname -m*>
(or something equivalent).

Taking into account the build products, a typical project hierarchy looks like this:


  poco/
    build/
    lib/
      Linux/
        i686/
          libCppUnit.so.1
          libCppUnitd.so.1
          libCppUnit.so
          libCppUnitd.so
          libPocoFouncation.so.1
          ...

    Foundation/
      ...
      testsuite/
        ...
        bin/
          Linux/
            i686/
              testrunner
              testrunnerd
              ...

    Net/
    Util/
    XML/
    ...

    MyLib/
      .dep/
        Linux/
          i686/
            MyClass.d

      obj/
        Linux/
          i686/
            MyClass.o

      include/
        MyLib.h
        MyClass.h

      src/
        MyClass.cpp

      Makefile
----


!!Project Makefiles

Depending on the kind of project, a project Makefile comes in one of three variants.


!Library Makefiles

The Makefile for a library always looks like this:

  #
  # Makefile for a library
  #

  include $(POCO_BASE)/build/rules/global

  objects = MyClass ...

  target = MyLib
  target_version = 1
  target_libs = PocoFoundation ...

  include $(POCO_BASE)/build/rules/lib
----


Every Makefile always has to include <*$(POCO_BASE)/build/rules/global*> first.
In the <*objects*> section, the source files (located in the <*src*> directory)
must be specified. The file extension must not be included; the build system
will find files ending in .cpp (C++ sources) and .c (C sources).
<*target*> specifies the name of the library, <*target_version*> specifies the
version number for the shared library. <*target_libs*> specifies the
libraries required for linking the library.

Last in the Makefile is the inclusion of <*$(POCO_BASE)/build/rules/lib*>,
which includes the rules for building a shared or static library.


!Executable Makefiles

Makefiles for executables look similar to the ones for libraries.


  #
  # Makefile for a library
  #

  include $(POCO_BASE)/build/rules/global

  objects = MyClass ...

  target = MyLib
  target_libs = PocoFoundation ...

  include $(POCO_BASE)/build/rules/exec
----



The only differences are the missing <*target_version*> entry, and the
<*$(POCO_BASE)/build/rules/exec*> file, which is included instead of
<*$(POCO_BASE)/build/rules/lib*> at the end of the Makefile.



!Plugin Makefiles



Makefiles for plugins - shared libraries that are loadable dynamically at runtime - again look almost the same as Makefiles for ordinary libraries or executables.

  #
  # Makefile for a library
  #

  include $(POCO_BASE)/build/rules/global

  objects = MyClass ...

  target = MyPlugin
  target_libs = PocoFoundation ...

  include $(POCO_BASE)/build/rules/dylib
----


The difference is the file that is included at the end of the Makefile:
<*$(POCO_BASE)/build/rules/dylib*>.


!!!Build System Reference


!!Target Variables

!target

The <*target*> variable specifies the name of the resulting library or executable,
excluding the suffix.


!target_version

The <*target_version*> variable specifies the shared library version of the resulting
shared library.


!target_libs

The <*target_libs*> variable specifies all libraries that must be linked to the
target. These libraries must have been built with this build system and they
must follow the build system conventions, specifically, the names for debug
and release builds.


!target_extlibs

The <*target_extlibs*> variables specifies additional libraries that must be
linked to the target. No assumptions are made regarding debug or release builds.
The names given here are simply passed to the linker by prepending the <[-l]> flag.


!target_includes

The <*target_includes*> variable specifies a list of directories used for searching
header files.


!!Postbuild Command

A Makefile can contain a so-called postbuild command -- a shell command
that will be executed when the target has been built successfully.
To specify a postbuild command, define the variable <*postbuild*>
in your Makefile, e.g.

  #
  # Makefile for a library
  #

  include $(POCO_BASE)/build/rules/global

  objects = MyClass ...

  target = MyLib
  target_libs = PocoFoundation ...

  postbuild = echo "The build is done."

  include $(POCO_BASE)/build/rules/exec
----


!!Make Targets

Independently of which kind of product (library, executable, plugin) is
being built, there are always five make targets available:
Note that these targets are only available in project-level Makefiles, not
the global Makefile.

!clean

The <*clean*> target will remove all executable and intermediate object files,
forcing a full rebuild with the next make.


!all

<*all*> is the default target, used if no other target is specified.
Depending on the current configuration, it will either build a statically linked or
dynamically linked library/executable, or both.


!static_debug

The <*static_debug*> target will build a statically linked debug version of
the library or executable. Statically linked executables will be linked
in the <*static*> subdirectory within the <*bin/<OSNAME>/<OSARCH>*> directory.
Debug libraries and executables have a 'd' appended to their basename
(e.g., MyLibd.so).


!static_release

The <*static_release*> target will build a statically linked release
version of the library or executable.


!shared_debug

The <*shared_debug*> target will build a dynamically linked debug version
of the library or executable. The library or executable will
have the suffix <*d*> appended to its name (e.g., if target is MyExec,
the actual name of the executable will be MyExecd).


!shared_release

The <*shared_release*> target will build a dynamically linked release
version of the library or executable.


!!Environment Variables

The POCO build system requires or uses certain environment variables to work properly.

!POCO_BASE

<*POCO_BASE*> is required and specifies the directory where the POCO
source tree is located.


!POCO_BUILD

<*POCO_BUILD*> specifies the directory where the build system puts all
intermediate build files (object files, dependency files) and build
products (libraries and executables). Normally, these files are located
within the POCO source tree. Setting POCO_BUILD allows to keep the POCO
source tree clean and free of binaries.


!POCO_CONFIG

<*POCO_CONFIG*> specifies the build configuration file (located in build/config)
to use. Defaults to the output of <*uname*> if not specified.


!POCO_TARGET_OSNAME and POCO_TARGET_OSARCH

<*POCO_TARGET_OSNAME*> and >*POCO_TARGET_OSARCH*> are used in
cross builds, to specify the operating system name and hardware
architecture of the target. These names is used to find the directory
where intermediate object files and final build products are put.
Intermediate files are always put into <*obj/<OSNAME>/<OSARCH>*>
and final build products are put into <*lib/<OSNAME>/<OSARCH>*>, or
<*bin/<OSNAME>/<OSARCH>*>, respectively.
If <*POCO_TARGET_OSNAME*> is specified, its value becomes the
value for <*<OSNAME>*>. If <*POCO_TARGET_OSARCH*> is specified, its value
likewise becomes the value for <*<OSARCH>*>

The default value for <*<OSNAME>*> is the output of <*uname*> or a
similar command.
The default value for <*<OSARCH>*> is the output of <*uname -m*> or a
similar command.


!OSARCH_64BITS

If defined to 1, will force a 64 bit build on platforms that support 64 bit builds.


!PROJECT_BASE


Setting this environment variable allows you to use the build system to
build POCO-based libraries and executables outside the POCO_BASE directory
hierarchy. Given a directory <*/projects*> containing a project directory
<*MyProject*> (that is, <*/projects/MyProject*>), <*PROJECT_BASE*>
must be set to <*/projects*>. Assuming <*/projects/MyProject/Makefile*>
is available, you can change to the <*/projects/MyProject*> directory and
invoke <*gmake*> to build your project. <*POCO_BASE*> must still be set
and point to the POCO source tree, as usual.


!!Special Files

!components

The build system requires a file named <*components*> being located in
<*$(POCO_BASE)*>. This file contains a list of project names, one per line.
The contents of this file are used by the build system to automatically
build include search paths. For example, if <*components*> has the following content:

  Foundation
  XML
  Util
  Net
----

the following include search path options will be used for compiling:

  -I$(POCO_BASE)/Foundation/include -I$(POCO_BASE)/XML/include -I$(POCO_BASE)/Util/include -I$(POCO_BASE)/Net/include
----


If a new library is being added to POCO, a corresponding entry should be made in the <*components*> file, so that the compiler can find its header files.


!libversion

The content of the file <*libversion*>, located in <*$(POCO_BASE)*>,
will be stored in the variable <*$(LIBVERSION)*>. This variable can be used
in a Makefile as the value for the <*target_version*> variable.


!Configuring the Build Process

The build process is configured by build configuration files,
located in the <*build/config*> directory.
Unless specified otherwise, by setting the <*POCO_CONFIG*>
environment variable accordingly, the build system selects the
build configuration file with the same name as the host's
operating system (output of <*uname*>). If you need support for a
new operating system, or just need to customize an existing configuration,
you'll usually create a new build configuration file (by copying an existing one).

    A typical build configuration file looks like this:

    #
    # Linux
    #
    # Make settings for Linux 2.6/gcc 3.3
    #
    #

    #
    # General Settings
    #
    LINKMODE = SHARED

    #
    # Define Tools
    #
    CC      = gcc
    CXX     = g++
    LINK    = $(CXX)
    LIB     = ar -cr
    RANLIB  = ranlib
    SHLIB   = $(CXX) -shared -Wl,-soname,$(notdir $@) -o $@
    SHLIBLN = $(POCO_BASE)/build/script/shlibln
    STRIP   = strip
    DEP     = $(POCO_BASE)/build/script/makedepend.gcc
    SHELL   = sh
    RM      = rm -rf
    CP      = cp
    MKDIR   = mkdir -p

    #
    # Extension for Shared Libraries
    #
    SHAREDLIBEXT     = .so.$(target_version)
    SHAREDLIBLINKEXT = .so

    #
    # Compiler and Linker Flags
    #
    CFLAGS          =
    CFLAGS32        =
    CFLAGS64        =
    CXXFLAGS        = -Wall -Wno-sign-compare
    CXXFLAGS32      =
    CXXFLAGS64      =
    LINKFLAGS       =
    LINKFLAGS32     =
    LINKFLAGS64     =
    STATICOPT_CC    =
    STATICOPT_CXX   =
    STATICOPT_LINK  = -static
    SHAREDOPT_CC    = -fPIC
    SHAREDOPT_CXX   = -fPIC
    SHAREDOPT_LINK  = -Wl,-rpath,$(LIBPATH)
    DEBUGOPT_CC     = -g -D_DEBUG
    DEBUGOPT_CXX    = -g -D_DEBUG
    DEBUGOPT_LINK   = -g
    RELEASEOPT_CC   = -O2 -DNDEBUG
    RELEASEOPT_CXX  = -O2 -DNDEBUG
    RELEASEOPT_LINK = -O2

    #
    # System Specific Flags
    #
    SYSFLAGS = -D_XOPEN_SOURCE=500 -D_REENTRANT -D_THREAD_SAFE -D_FILE_OFFSET_BITS=64 -D_LARGEFILE64_SOURCE -DPOCO_HAVE_FD_EPOLL

    #
    # System Specific Libraries
    #
    SYSLIBS  = -lpthread -ldl -lrt
----

The various settings in the build configuration file are described below.

!!General Settings

!LINKMODE

This specifies the default link mode, which can have the values
<*STATIC*>, <*SHARED*> or <*BOTH*>.


!TOOL

For cross builds, <*TOOL*> specifies the prefix for the toolchain executables, e.g.

  TOOL = arm-unknown-linux-gnu
----

<*TOOL*> can later be used in the tool section, as in:

  CC  = $(TOOL)-gcc
  CXX = $(TOOL)-g++
  ...
----


!POCO_TARGET_OSNAME and POCO_TARGET_OSARCH

The general settings section is also the right place to define
<*POCO_TARGET_OSNAME*> and <*POCO_TARGET_OSARCH*> for cross builds.


!!Tool Definition

!CC

<*CC*> specifies the command for invoking the C compiler.


!CXX

<*CXX*> specifies the command for invoking the C++ compiler.


!LINK

<*LINK*> specifies the command for invoking the link editor.


!STRIP

<*STRIP*> specifies the command for invoking the strip utility.


!LIB

<*LIB*> specifies the command for invoking the library archiver utility.


!RANLIB

<*RANLIB*> specifies the command for invoking the library table of contents updater
utility.


!SHLIB

<*SHLIB*> specifies the command for creating shared libraries.


!SHLIBLN

<*SHLIBLN*> specifies the command for creating shared library
symbolic links (e.g. <*libPocoFoundation.so*> -> <*libPocoFoundation.so.1*>)


!DEP

<*DEP*> specifies the command for creating or updating the dependencies. This
is usually a shell script invoking the C/C++ compiler in a special way to generate
a list of dependencies.


!SHELL

<*SHELL*> specifies the command for invoking the POSIX shell.


!RM

<*RM*> specifies the command for deleting files and directories.


!CP

<*CP*> specifies the command for copying files.


!MKDIR

<*MKDIR*> specifies the command for creating directories.


!!Shared Library Extensions

!SHAREDLIBEXT

<*SHAREDLIBEXT*> specifies the extension for shared libraries.
This usually includes a version number (e.g. <*.so.1*>).


!SHAREDLIBLINKEXT

<*SHAREDLIBLINKEXT*> specifies the extension for shared library
symbolic links. (e.g., <*.so*>)


!!Compiler and Linker Flags

!CFLAGS

<*CFLAGS*> specifies additional flags passed to the C compiler.


!CFLAGS32

<*CFLAGS32*> specifies additional flags passed to the C compiler
if compiling in 32 bit mode.


!CFLAGS64

<*CFLAGS64*> specifies additional flags passed to the C compiler
if compiling in 64 bit mode.


!CXXFLAGS

<*CXXFLAGS*> specifies additional flags passed to the C++ compiler.


!CXXFLAGS32

<*CXXFLAGS32*> specifies additional flags passed to the C++ compiler if
compiling in 32 bit mode.


!CXXFLAGS64

<*CXXFLAGS64*> specifies additional flags passed to the C++ compiler if
compiling in 64 bit mode.


!LINKFLAGS

<*LINKFLAGS*> specifies additional flags passed to the linker.


!LINKFLAGS32

<*LINKFLAGS32*> specifies additional flags passed to the linker if
compiling in 32 bit mode.


!LINKFLAGS64

<*LINKFLAGS64*> specifies additional flags passed to the linker if
compiling in 64 bit mode.


!STATICOPT_CC

<*STATICOPT_CC*> specifies additonal flags passed to the C compiler
if compiling for static linking.


!STATICOPT_CXX

<*STATICOPT_CXX*> specifies additonal flags passed to the C++ compiler if
compiling for static linking.


!STATICOPT_LINK

<*STATICOPT_LINK*> specifies additonal flags passed to the linker for
static linking.


!SHAREDOPT_CC

<*SHAREDOPT_CC*> specifies additonal flags passed to the C compiler if
compiling for dynamic linking.


!SHAREDOPT_CXX

<*SHAREDOPT_CXX*> specifies additonal flags passed to the C++ compiler if
compiling for dynamic linking.


!SHAREDOPT_LINK

<*SHAREDOPT_LINK*> specifies additonal flags passed to the linker for dynamic linking.


!DEBUGOPT_CC

<*DEBUGOPT_CC*> specifies additional flags passed to the C compiler if compiling in debug mode.


!DEBUGOPT_CXX

<*DEBUGOPT_CXX*> specifies additional flags passed to the C++ compiler if compiling in debug mode.


!DEBUGOPT_LINK

<*DEBUGOPT_LINK*> specifies additional flags passed to the linker if linking in debug mode.


!RELEASEOPT_CC

<*RELEASEOPT_CC*> specifies additional flags passed to the C compiler if compiling in release mode.


!RELEASEOPT_CXX

<*RELEASEOPT_CXX*> specifies additional flags passed to the C++ compiler if compiling in release mode.


!RELEASEOPT_LINK

<*RELEASEOPT_LINK*> specifies additional flags passed to the linker if linking in release mode.


!!System Specific Flags

!SYSFLAGS

<*SYSFLAGS*> specifies flags passed to both the C and C++ compiler. This usually contains system-specific include paths and settings such as -D_XOPEN_SOURCE=500 or -D_THREAD_SAFE.


!SYSLIBS

<*SYSLIBS*> specifies flags passed to the linker. Usually, this flags specify system-specific libraries, such as -lpthread or -ldl.