C++ library package

dmitigr::cpplipa (lipa - is an abbreviation of "library package") - is a package of C++ libraries, including:

• fcgi - FastCGI implementation (server);
• http - HTTP parts implementation (with basic client and server);
• jrpc - JSON-RPC 2.0 implementation;
• pgfe - PostgreSQL driver;
• rajson - RapidJSON thin wrapper;
• sqlixx - SQLite driver;
• ws - WebSocket server;
• miscellaneous stuff (from basic utilities to URL processing to concurrency).

All of these libraries can be used as shared libraries, static libraries or header-only libraries.

Some of these libraries are available as derived library packages:

• dmitigr::fcgi;
• dmitigr::pgfe;
• dmitigr::sqlixx.

Unbundled third-party dependencies

• CMake build system version 3.16+;
• C++17 compiler (GCC 7.4+ or Microsoft Visual C++ 15.7+);
• libpq library for pgfe;
• libuv library for ws;
• OpenSSL library (optionally) for ws;
• SQLite for sqlixx;
• zlib library (optionally) for ws.

Bundled third-party dependencies

CMake options

The table below (one may need to use horizontal scrolling for full view) contains variables which can be passed to CMake for customization.

Remarks

• <Lib>_ROOT specifies a prefix for both binary and headers of the <Lib>. For example, if PostgreSQL installed relocatably into /usr/local/pgsql, the value of Pq_ROOT should be set accordingly;
• when building with Microsoft Visual Studio the value of CMAKE_BUILD_TYPE doesn't selects the build configuration within the generated build environment. The CMake command line option --config should be used for that purpose.

Installation

Library package can be installed as a set of:

• shared libraries if -DBUILD_SHARED_LIBS=ON option is specified;
• static libraries if -DBUILD_SHARED_LIBS=OFF option is specified (the default);
• header-only libraries if -DDMITIGR_CPPLIPA_HEADER_ONLY=ON option is specified.

The default build type is Debug.

Installation on Linux

$ git clone https://github.com/dmitigr/cpplipa.git
$ mkdir cpplipa/build
$ cd cpplipa/build
$ cmake -DCMAKE_BUILD_TYPE=Release ..
$ cmake --build . --parallel
$ cmake sudo make install

Installation on Microsoft Windows

Run the Developer Command Prompt for Visual Studio and type:

> git clone https://github.com/dmitigr/cpplipa.git
> mkdir cpplipa\build
> cd cpplipa\build
> cmake -A x64 ..
> cmake --build . --config Release --parallel

Next, run the elevated command prompt (i.e. the command prompt with administrator privileges) and type:

> cmake --install .

Alternatively, one of the following build commands may be used: > cmake --build . --config Release --target install or > cmake -DBUILD_TYPE=Release -P cmake_install.cmake

A bitness of the target architecture must corresponds to the bitness of external dependencies!

To make installed DLLs available for any application that depends on it, symbolic links can be created:

• in %SYSTEMROOT%\System32 for a 64-bit DLL on a 64-bit host (or for the 32-bit DLL on the 32-bit host);
• in %SYSTEMROOT%\SysWOW64 for the 32-bit DLL on 64-bit host.

For example, to create the symbolic link to dmitigr_pgfe.dll, the mklink command can be used in the elevated command prompt:

> cd /d %SYSTEMROOT%\System32
> mklink dmitigr_pgfe.dll "%ProgramFiles%\dmitigr_cpplipa\lib\dmitigr_pgfe.dll"

Usage

Assuming foo is the name of library, the following considerations should be followed:

• headers other than dmitigr/foo/foo.hpp should not be used since these headers are subject to reorganize;
• namespace dmitigr::foo::detail should not be used directly since it consists of the implementation details.

Usage with CMake

With CMake it's pretty easy to use the libraries (including derived versions) in two ways: as a system-wide installed library(-es) or as a library(-es) dropped into the project source directory.

The code below demonstrates how to import system-wide installed libraries by using CMake (this snippet is also valid when using the derived library package(s)):

cmake_minimum_required(VERSION 3.16)
project(foo)
find_package(dmitigr_cpplipa REQUIRED COMPONENTS fcgi pgfe)
set(CMAKE_CXX_STANDARD 17)
set(CMAKE_CXX_STANDARD_REQUIRED ON)
add_executable(foo foo.cpp)
target_link_libraries(foo dmitigr_fcgi dmitigr_pgfe)

The next code demonstrates how to import the derived Pgfe library package dropped directly into the project's source directory 3rdparty/pgfe:

set(DMITIGR_CPPLIPA_HEADER_ONLY ON CACHE BOOL "Header-only?")
add_subdirectory(3rdparty/pgfe)

Note, that all CMake variables described in CMake options are also valid for derived library packages.

Specifying a library type to use

It's possible to explicitly specify a type of library to use. To do it, the corresponding suffix of a component name should be specified:

• the suffix "_shared" corresponds to shared libraries;
• the suffix "_static" corresponds to static libraries;
• the suffix "_interface" corresponds to header-only libraries.

For example, the code below demonstrates how to use the shared fcgi library and the header-only pgfe library in a same project side by side:

find_package(dmitigr_cpplipa REQUIRED COMPONENTS fcgi_shared pgfe_interface)
# ...
target_link_libraries(foo dmitigr_fcgi dmitigr_pgfe)

Note that libraries of the explicitly specified types must be installed to be found!

If the type of library is not specified (i.e. suffix of a component name is omitted), find_package() will try to import the first available library in the following order:

1. a shared library;
2. a static library;
3. a header-only library.

Usage without CMake

It's possible to use the libraries without CMake. In order to use an any library of the package as header-only library, just copy the contents of the src directory to a project directory which is under an include path of a compiler, for example, src/3rdparty/dmitigr. Then, just include the header of the required library, for example:

#include "dmitigr/pgfe/pgfe.hpp"

int main()
{
  dmitigr::pgfe::Connection conn;
}

Please note, that external dependencies must be linked manually in this case. So, the snippet above could be compiled with the following command:

g++ -std=c++17 -I/usr/local/pgsql/include -L/usr/local/pgsql/lib -lpq -ohello hello.cpp

Licenses and copyrights

All the libraries of the package itself (except the third-party software) is distributed under zlib LICENSE.

Third-party software are distributed under:

• RapidJSON is distributed under the following LICENSE;
• uSockets is distributed under the following LICENSE;
• uWebSockets is distributed under the following LICENSE.

For conditions of distribution and use, please see the corresponding license.