Building Balau

This chapter discusses the preparatory steps, configuring, and building Balau.

Defaults

CMAKE_PREFIX_PATH

If the CMAKE_PREFIX_PATH is not set, the Balau CMakeLists.txt file defaults it to the ${HOME}/usr folder. This setup allows the ICU, Boost, and optionally libzip dependencies to be installed in ${HOME}/usr, to be picked up during CMake configuration automatically.

If the dependencies are located elsewhere, the CMAKE_PREFIX_PATH should be set, as discussed in the CMake variables section below.

CMAKE_INSTALL_PREFIX

If the CMAKE_INSTALL_PREFIX is not set, the Balau CMakeLists.txt file defaults it to the ${HOME}/usr folder. If the library should be installed elsewhere (such as to /usr), the CMAKE_INSTALL_PREFIX should be set, as discussed in the CMake variables section below.

Options

Balau contains a number of optional components that can be enabled/disabled during CMake configuration.

The currently available options are detailed in the table below.

Option	Default	Description
BALAU_ENABLE_ZLIB	ON	Enable ZLib library wrappers for gzip compression support.
BALAU_ENABLE_ZIP	ON	Enable LibZip library wrappers (Zipper and Unzipper).
BALAU_ENABLE_CURL	ON	Enable use of Curl library (email sending web app).
BALAU_ENABLE_HTTP	ON	Enable use of HTTP components (disabled for Boost < 1.68.0).

By default, ZLib and LibZip compression components are enabled, and the Curl components are not. Enabled components will require the corresponding library development files to be present during the build, as described in the dependencies section below.

Dependencies

In addition to the C++ standard library, Balau relies on two third party libraries and three utility libraries.

The first dependency is ICU, which provides Unicode support. ICU version 60.2 is the currently specified version in the CMakeLists.txt file.

The second dependency is the Boost library. Boost version 1.68.0 is the currently specified version in the CMakeLists.txt file.

The three utility library dependencies are zlib, libzip and curl. These libraries should be installed via your distribution's standard packaging system.

The only other dependencies used are standard dependencies on each supported platform.

Utility libraries

Debian/Ubuntu

The following command is for Ubuntu 18.04 and OpenSSL.

			sudo apt install zlib1g-dev libzip-dev libcurl4-openssl-dev libssl-dev

RPM based distributions

Fedora 28 / 29

			sudo yum install zlib-devel openssl-devel libcurl-devel libzip-devel

RHEL CentOS

Balau can be built on RHEL5 / CentOS v5 of later via the developer toolset 6 or later.

			sudo yum install zlib-devel openssl-devel libcurl-devel

The supplied version of libzip on these distributions is 0.10.1. A recent version of libzip must thus be compiled and installed. The following commands will download, build, and install libzip version 1.5.1 into the ${HOME}/usr directory (this directory will be referenced later via CMAKE_PREFIX_PATH).

			mkdir Libs
			cd Libs
			wget https://libzip.org/download/libzip-1.5.1.tar.gz
			tar zxvf libzip-1.5.1.tar.gz
			cd libzip-1.5.1
			mkdir build
			cd build
			cmake -DCMAKE_INSTALL_PREFIX=${HOME}/usr ..
			make
			make install

To install the developer toolset on CentOS, the SCL command can be used. DTS7 may be installed via the following command:

			scl enable devtoolset-7 bash

RHEL / CentOS also ship with old versions of CMake (2.8). As Balau requires at least CMake version 3.10.2, a suitable build of CMake must be available. Please refer to the CMake website for more information.

ICU

Linux

Download the ICU version 60.2 sources here.

To configure the ICU sources on Linux, unzip the sources and run the following commands in the unzipped ICU source directory. If you intend to use a different install prefix that the Balau default, the --prefix option should be set to the required path.

			cd /path/to/icu/code
			cd source

			# Replace ${HOME}/usr to alternative path if required.
			./runConfigureICU Linux --enable-static    \
			                        --disable-shared   \
			                        --disable-renaming \
			                        --prefix=${HOME}/usr

Then add the necessary ICU defines in the source/common/unicode/uconfig.h file. These additionally configure ICU's build.

			#define U_USING_ICU_NAMESPACE            1
			#define UNISTR_FROM_CHAR_EXPLICIT        explicit
			#define UNISTR_FROM_STRING_EXPLICIT      explicit
			#define U_NO_DEFAULT_INCLUDE_UTF_HEADERS 1
			#define U_HIDE_OBSOLETE_UTF_OLD_H        1
			#define ICU_NO_USER_DATA_OVERRIDE        1
			#define U_DISABLE_RENAMING               1
			// Linux/OSx platforms also use:
			#define U_CHARSET_IS_UTF8                1

Then build and install ICU.

			make CXXFLAGS='-std=c++17 -g -o2 -fPIC' -j4
			make install

Windows

This section will be filled in when the Windows port has been completed.

Boost

Linux

Download the Boost version 1.68.0 sources here.

To configure the Boost sources on Linux, unzip the sources and run the following commands in the unzipped Boost source directory. If you intend to use different install prefixes than the Balau default, the --prefix and --with-icu options should be set to the required path.

			# Replace ${HOME}/usr ocurrances to alternative paths if required.
			./bootstrap.sh --with-icu=${HOME}/usr --prefix=${HOME}/usr

Then build and install Boost.

			./b2 -j4
			./b2 install

Windows

This section will be filled in when the Windows port has been completed.

CMake variables

Balau relies on two CMake variables in order to find its dependencies and to specify where to install itself. These two variables may optionally be set before building the library.

If you use the default Balau installation location (${HOME}/usr), both these variables will default to this. Otherwise, these variables must be set before building the library.

The exact method for specifying these CMake variables depends on whether you use the command line or an IDE. Only the command line technique is covered in the build steps here. For IDEs that support CMake, these are typically set from within the settings/preferences of the IDE. Refer to the specific IDE's documentation for information.

CMAKE_PREFIX_PATH

This CMake variable specifies a list of directories where dependencies may be found. More information is available on the CMake documentation here.

CMAKE_INSTALL_PREFIX

This CMake variable specifies the installation prefix into which the Balau library will be installed. More information is available on the CMake documentation here.

Environment variables

The Balau test application uses a number of environment variables in the unit tests, imported via the CMakeLists.txt file. These environment variables are optional. If they are not defined, the unit tests that require them will be disabled.

Refer to the CMakeLists.txt file for details on each environment variable if you wish to run the associated unit tests.

Building Balau

Building can be achieved either via the command line or from within an IDE that supports the CMake build system. Building and installing via the command line is covered in this document.

Linux

Open a command prompt and prepare the build with the following commands.

			cd path/to/projects
			git clone https://github.com/borasoftware/balau.git
			cd path/to/balau/code
			mkdir build-debug
			cd build-debug

If you are using the default prefix path and install prefix, execute the following commands.

			cmake -DCMAKE_BUILD_TYPE=Debug ..
			make -j 4
			make install

If you are using a non-default prefix path and/or a non-default install prefix, run the following commands, replacing ${DEPS} with the installation locations of the dependencies you configured in the previous steps, and ${BALAU_PREFIX} with the installation prefix where you wish to install the Balau library.

			cmake -DCMAKE_PREFIX_PATH=${DEPS}            \
			      -DCMAKE_INSTALL_PREFIX=${BALAU_PREFIX} \
			      -DCMAKE_BUILD_TYPE=Debug               \
			      ..

			make -j 4
			make install

The above set of commands:

creates an out of source build directory build-debug;
configures CMake;
builds the library;
installs the library to ${BALAU_PREFIX}.

If you wish to have a release build, set CMAKE_BUILD_TYPE to Release instead.

Windows

This section will be filled in when the Windows port has been completed.

Linking

In order to link to the Balau library, your CMakeLists.txt file needs to be modified with the Balau library and its dependencies.

These instructions have been written in order to use statically linked libraries. On some platforms, the ordering of the entries in the CMakeLists.txt file is important, in order that the linker may resolve the dependencies correctly.

The following CMake commands will ensure all libraries are found and linked correctly.

			######################## BALAU ########################

			find_package(Balau 2019.7.1 REQUIRED)
			message(STATUS "Balau include dirs: ${Balau_INCLUDE_DIRS}")
			message(STATUS "Balau library:      ${Balau_LIBRARY}")
			include_directories(BEFORE ${Balau_INCLUDE_DIRS})
			set(ALL_LIBS ${ALL_LIBS} ${Balau_LIBRARY})

			################### BOOST LIBRARIES ###################

			set(Boost_DETAILED_FAILURE_MSG ON)
			set(Boost_USE_STATIC_LIBS ON)
			set(Boost_USE_MULTITHREADED ON)
			set(Boost_USE_STATIC_RUNTIME OFF)
			# Add any other Boost libraries that you may require.
			find_package(Boost 1.68.0 REQUIRED COMPONENTS thread chrono date_time filesystem system serialization iostreams)
			include_directories(${Boost_INCLUDE_DIRS})
			set(ALL_LIBS ${ALL_LIBS} ${Boost_LIBRARIES})

			message(STATUS "Boost include dirs: ${Boost_INCLUDE_DIRS}")

			######################### ICU #########################

			find_package(ICU 60.2 REQUIRED COMPONENTS i18n uc data)
			include_directories(${ICU_INCLUDE_DIRS})
			set(ALL_LIBS ${ALL_LIBS} ${ICU_LIBRARIES})
			message(STATUS "ICU include dirs: ${ICU_INCLUDE_DIRS}")