Introduction
The POCO C++ Libraries use a built system based on 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.