How to use the framework in POSIX

The project is being ported to POSIX. The following development environment is being used:

Clang with libc++ was chosen for being a modern and fast toolchain, which is already fully compliant with C++11 and can compile everything MSVC 2013 can (and more). You can set up this development environment yourself following the steps below.

1. Install the toolchain
Install the packages for Clang version 3.5 or later (the port is being tested with version 3.6, but version 3.3 is likely to be enough, because it is already C++11 fully compliant), along with libc++1, libc++-dev, libc++abi1 and libc++abi-dev.

2. Install CMake or build Qt5
The easiest way is to use CMake as make system. You can install CMake in ubuntu running the command
sudo apt-get install cmake

If you want to use QMake as your make system, or if you want full integration of Qt Creator IDE with the clang compiler, then you need to build the Qt framework from source using clang and libc++.
Why? QtCreator comes with a Qt instance built by gcc64 and libstdc++, which means the make system will not work perfectly with clang & libc++. For that, you can follow http://qt-project.org/doc/qt-5/linux-building.html. Do not forget to read http://qt-project.org/doc/qt-5/configure-options.html and set the configure step to use "linux-clang-libc++" mkspec.

After Qt framework is built, set up QtCreator IDE to use a kit consisting of clang, the Qt5 instance you compiled and the mkspec "linux-clang-libc++".

3. Build POCO ++ Libraries
Build the POCO C++ libraries using Clang and libc++ too. You will need only Foundation, XML and Utils (built as static libraries). The remaining modules can be omitted. For that you can follow http://pocoproject.org/download/index.html, but not with a little problem. By the time I was writing this tutorial, POCO C++ v1.6.1 was the latest stable release and did not support building in linux using clang and libc++ yet. There was no build configuration for such toolchain. However, there is a workaround. You can use the content below and save as new building configuration:
#
# $Id: //poco/1.4/build/config/Linux#2 $
#
# Linux
#
# Make settings for Linux 2.6/clang++ v3.6 with libc++
# Hacked by Felipe Vieira Aburaya ;)
#

#
# General Settings
#
LINKMODE ?= SHARED

#
# Define Tools
#
CC      = clang
CXX     = clang++
LINK    = $(CXX)
LIB     = ar cqs
RANLIB  = ranlib
SHLIB   = $(CXX) -shared -Wl,-soname,$(notdir $@) -o $@
SHLIBLN = $(POCO_BASE)/build/script/shlibln
STRIP   = strip
DEP     = $(POCO_BASE)/build/script/makedepend.clang 
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          = 
CXXFLAGS        = -std=c++11 -stdlib=libc++ -Wall -Wno-sign-compare -Wno-unused-variable -Wno-unused-function -Wno-unneeded-internal-declaration
LINKFLAGS       = -std=c++11 -stdlib=libc++
SHLIBFLAGS      = -std=c++11 -stdlib=libc++
DYLIBFLAGS      = -std=c++11 -stdlib=libc++
STATICOPT_CC    =
STATICOPT_CXX   =
STATICOPT_LINK  =
SHAREDOPT_CC    = -fPIC 
SHAREDOPT_CXX   = -fPIC
SHAREDOPT_LINK  = 
DEBUGOPT_CC     = -g -D_DEBUG
DEBUGOPT_CXX    = -g -D_DEBUG
DEBUGOPT_LINK   = 
RELEASEOPT_CC   = -DNDEBUG -O2
RELEASEOPT_CXX  = -DNDEBUG -O2
RELEASEOPT_LINK = 

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

This new building configuration must be placed under [POCO root directory]/build/config, named "Linux-clang-libcxx" for example. Then you can build POCO with::
$ sudo mkdir /opt/Poco-1.6.1
$ ./configure --omit=Data/ODBC,Data/MySQL --no-tests --no-samples --static --config=Linux-clang-libcxx --prefix=/opt/Poco-1.6.1
$ make
$ sudo make -s install

You can learn more about the building process of POCO in https://raw.githubusercontent.com/pocoproject/poco/poco-1.6.1/README.

4. Build Boost C++ Libraries
Download the source for Boost C++ libraries v1.6x and, once again, build it with clang & libc++. First you will build and install Boost.build. In order to get the libraries (static and with shared link to runtime) with debug symbols, you need to run
./tools/build/b2 -j 2 variant=debug link=static threading=multi toolset=clang cxxflags="-std=c++11 -stdlib=libc++" linkflags="-stdlib=libc++" runtime-link=shared --layout=tagged

Finally, in order to get the same libraries in release mode, you will run
./tools/build/b2 -j 2 variant=release link=static threading=multi toolset=clang cxxflags="-std=c++11 -stdlib=libc++" linkflags="-stdlib=libc++" runtime-link=shared --layout=tagged

At the end you can manually copy the compiled libraries and headers to another location, such as /opt/boost-1.60. The framework projects will need this location for linking.

5. Build googletest framework
[You can skip this step if you do not plan to run 3FD unit & integration tests.]
No need to download googletest because it is already included in 3FD source code. But you are going to need CMake. Again, clang & libc++ need to be your toolchain, so when you run cmake, make sure to pass the following arguments:
-DCMAKE_CXX_COMPILER="clang++" -DCMAKE_CXX_FLAGS="-std=c++11 -stdlib=libc++"

In fact, such options are already applied by configure.sh as described in the next step.

6. Build 3FD
Edit 3FD project files (for qmake they are the *.pro, and for CMake they are the CMakeLists.txt inside each project directory) so as to set the correct location for your builds of POCO and Boost.

Now you can run the build using QMake (from QtCreator IDE, if you want) or CMake.

If you choose CMake, there are some scripts that can help you:

Extract the contents of cmake_build_scripts.tar.gz to the root of the sources directory. You want the directory named x64 directly under the root. This directory separates the builds by project and Debug/Release modes. In this directories there are scripts that invoke CMake for you. For example, if you want to build the integration tests, all you need to do is:
~/Documents/3FD $ cd x64/Debug/3FD/
~/Documents/3FD/x64/Debug/3FD $ ./configure.sh
~/Documents/3FD/x64/Debug/3FD $ make
...
~/Documents/3FD/x64/Debug/3FD $ cd ../gtest/
~/Documents/3FD/x64/Debug/gtest $ ./configure.sh
~/Documents/3FD/x64/Debug/gtest $ make
...
~/Documents/3FD/x64/Debug/gtest $ cd ../IntegrationTests/
~/Documents/3FD/x64/Debug/IntegrationTests $ ./configure.sh
~/Documents/3FD/x64/Debug/IntegrationTests $ make
...

Notice that first 3FD and gtest were built, because the integration tests depend on them. The script configure.sh invokes make clean and regenerates the makefile from CMakeLists.txt.

7. Link your project to 3FD
Once the framework is compiled, you are going to set up your solution to link to the framework just like you do for any other static library. Then there are just a couple of things to set:
  • In your enviroment, define the macros ENABLE_3FD_CST and ENABLE_3FD_ERR_IMPL_DETAILS (recommended, so as to enable the stack tracing feature in release mode, plus exception detailed info) and NDEBUG in release mode;
  • Provide a XML configuration file for the framework instance used by you application. This file must have the same name of the application executable (including the extension) plus ".3fd.config". A template for this file is provided in the source.

Last edited Jan 4, 2016 at 3:57 PM by faburaya, version 44

Comments

No comments yet.