Asio samples

Branch	Linux	Windows	Coverage	Coverity Scan
master
develop

Extended examples for Boost.Asio.

⚠️ Boost 1.84.0+ is not supported yet.

Building with Docker container

Refer to docker/builder/README.md for instruction on how to build Linux version with existing Docker images.

Build manual

Prerequisites

• C++ toolchain (one of):

  • MinGW with MSYS make

    MinGW-W64 4.9+

  • Visual Studio (Visual C++)

    2008, 2010, 2012, 2013, 2015, 2017, 2019 are tested versions

  • GCC with make

    4.6+

  • Clang with make

    3.6+

• CMake

  3.1+, consider using the latest version of CMake because it supports recent versions of libraries

• Boost

  1.47+, the latest tested version is 1.74

• Google Test

  Optional, copy of 1.7.0 version is shipped with this project and is used if no other instance is found

• Qt

  Optional, 4.0+, both 4.x and 5.x are supported with default preference to 5.x

• ICU

  Optional, required if static Qt 5.x is used, version should match Qt requirements / version which was used to build static Qt

Assumptions

• %...% syntax is used for Windows Command Prompt and ${...} syntax is used for *nix shell
• Windows Command Prompt with configured Windows SDK environment is used on Windows
• Directory with generated project files and with built binaries is specified in asio_samples_build_dir environment variable
• This repository is cloned into directory specified in asio_samples_home_dir environment variable
• ICU is located at directory specified by icu_home_dir environment variable
• Header files of Boost are located at directory specified by boost_headers_dir environment variable
• Binary files of Boost are located at directory specified by boost_libs_dir environment variable
• Qt 5.x is located at directory specified by qt5_home_dir environment variable
• Qt 4.x is located at directory specified by qt4_home_dir environment variable
• Google Test is located at directory specified by gtest_home_dir environment variable
• build type is specified in build_type environment variable and is one of:
  • Debug
  • Release
  • RelWithDebInfo
  • MinSizeRel
• cmake_generator environment variable is CMake generator
  • Visual Studio 14 2015 - Visual Studio 2015
  • Visual Studio 15 2017 - Visual Studio 2017
  • Visual Studio 16 2019 - Visual Studio 2019
  • Visual Studio 12 2013 - Visual Studio 2013
  • Visual Studio 10 2010 - Visual Studio 2010
  • Visual Studio 9 2008 - Visual Studio 2008
  • NMake Makefiles - NMake
  • MinGW Makefiles - MinGW makefiles
  • Unix Makefiles - *nix makefiles
• cmake_platform environment variable is CMAKE_GENERATOR_PLATFORM
  • Win32 - x86 platform when using Visual Studio
  • x64 - amd64 (x64) platform when using Visual Studio

Building of CMake project is usually performed in 2 steps:

1. Generation of project for build system
2. Building generated project with build system

Generation of project for build system

Assuming current directory is asio_samples_build_dir.

Windows Command Prompt, Visual Studio CMake generator:

cmake ... -G "%cmake_generator%" -A "%cmake_platform%" "%asio_samples_home_dir%"

Windows Command Prompt, NMake / MinGW makefiles CMake generator

cmake ... -G "%cmake_generator%" "%asio_samples_home_dir%"

*nix shell

cmake ... -G "${cmake_generator}" "${asio_samples_home_dir}"

where ... are optional parameters which are described below.

Use MA_TESTS CMake variable to exclude tests from build (tests are included by default):

cmake -D MA_TESTS=OFF ...

CMake project uses CMake find modules, so most of parameters comes from these CMake modules:

• FindBoost CMake module

  CMake variables which can be specified in command line to locate and configure Boost:

  • BOOST_INCLUDEDIR - Boost headers directory

    Windows Command Prompt:

    -D BOOST_INCLUDEDIR="%boost_headers_dir%"
    

    *nix shell

    -D BOOST_INCLUDEDIR="${boost_headers_dir}"
    

  • BOOST_LIBRARYDIR - Boost libraries directory

    Windows Command Prompt:

    -D BOOST_LIBRARYDIR="%boost_libs_dir%"
    

    *nix shell

    -D BOOST_LIBRARYDIR="${boost_libs_dir}"
    

  • Boost_USE_STATIC_LIBS - force usage of static Boost, possible values are ON (use static libraries) and OFF (linkage type depends on platform)

  • Boost_NO_SYSTEM_PATHS - do not search for Boost in default system locations

• cmake-qt CMake module (refer to Qt cmake manual also)

  CMake variables which can be specified in command line to locate Qt 5.x:

  • Qt5Core_DIR

    Windows Command Prompt:

    -D Qt5Core_DIR="%qt5_home_dir%/lib/cmake/Qt5Core"
    

    *nix shell

    -D Qt5Core_DIR="${qt5_home_dir}/lib/cmake/Qt5Core"
    

  • Qt5Gui_DIR

    Windows Command Prompt:

    -D Qt5Gui_DIR="%qt5_home_dir%/lib/cmake/Qt5Gui"
    

    *nix shell

    -D Qt5Gui_DIR="${qt5_home_dir}/lib/cmake/Qt5Gui"
    

  • Qt5Widgets_DIR

    Windows Command Prompt:

    -D Qt5Widgets_DIR="%qt5_home_dir%/lib/cmake/Qt5Widgets"
    

    *nix shell

    -D Qt5Widgets_DIR="${qt5_home_dir}/lib/cmake/Qt5Widgets"
    

  CMake variables which can be specified in command line to locate Qt 4.x:

  • QT_QMAKE_EXECUTABLE - path to qmake executable

    Windows Command Prompt:

    -D QT_QMAKE_EXECUTABLE="%qt4_home_dir%/bin/qmake.exe"
    

    *nix shell

    -D QT_QMAKE_EXECUTABLE="${qt4_home_dir}/bin/qmake.exe"
    

  MA_QT CMake variable can be used to avoid usage of Qt and to skip examples using Qt. Possible values are:

  • ON (default) - search for (require) and use Qt
  • OFF - do not search for Qt and skip building the parts which use Qt

• FindGTest CMake module

  CMake variables which can be specified in command line to locate Google Test:

  • GTEST_ROOT - Google Test home directory

    Windows Command Prompt:

    -D GTEST_ROOT="%gtest_home_dir%"
    

    *nix shell

    -D GTEST_ROOT="${gtest_home_dir}"
    

  Note that if Google Test was built with CMake and MS Visual Studio then you have to "install" it somehow - just copying results of build (add "d" postfix into the name of debug artifacts) into Google Test root directory (or into "lib" sub-directory) would be enough for FindGTest.

  There is a copy of Google Test shipped as part of CMake project (refer to 3rdparty/gtest directory). It will be used in case FindGTest fails to find Google Test (so GTEST_ROOT is optional). Note that -D gtest_force_shared_crt=ON command line parameter is required in case shared C/C++ runtime is planned to be used with Google Test on Windows.

• FindICU CMake module

  Used only if static Qt 5.x is identified.

  CMake variables which can be specified in command line to locate ICU:

  • ICU_ROOT - ICU home directory

    Windows Command Prompt:

    -D ICU_ROOT="%icu_home_dir%"
    

    *nix shell

    -D ICU_ROOT="${icu_home_dir}"
    

To build with static C/C++ runtime:

• Use CMAKE_USER_MAKE_RULES_OVERRIDE CMake variable pointing to cmake/static_c_runtime_overrides.cmake

  Windows Command Prompt:

  -D CMAKE_USER_MAKE_RULES_OVERRIDE="%asio_samples_home_dir%/cmake/static_c_runtime_overrides.cmake"
  

  *nix shell

  -D CMAKE_USER_MAKE_RULES_OVERRIDE="${asio_samples_home_dir}/cmake/static_c_runtime_overrides.cmake"
  

• Use CMAKE_USER_MAKE_RULES_OVERRIDE_CXX CMake variable pointing to cmake/static_cxx_runtime_overrides.cmake

  Windows Command Prompt:

  -D CMAKE_USER_MAKE_RULES_OVERRIDE_CXX="%asio_samples_home_dir%/cmake/static_cxx_runtime_overrides.cmake"
  

  *nix shell

  -D CMAKE_USER_MAKE_RULES_OVERRIDE_CXX="${asio_samples_home_dir}/cmake/static_cxx_runtime_overrides.cmake"
  

• Static build of Qt

• ICU_ROOT CMake variable pointing to ICU home directory (static build, required for Qt).

Note that on Windows cmake-qt searches for some system libraries (OpenGL) therefore to work correctly CMake should be executed after Windows SDK environment was set up (even if Visual Studio generator is used).

The CMake project searches for Qt 5.x first and if Qt 5.x is not found then it searches for Qt 4.x. This can be changed with MA_QT_MAJOR_VERSION CMake variable which can be specified in command line.

Possible values are:

• 4 - search for Qt 4.x only

  -D MA_QT_MAJOR_VERSION=4
  

• 5 - search for Qt 5.x only

  -D MA_QT_MAJOR_VERSION=5
  

Example of generation of Visual Studio 2015 project with:

• static C/C++ runtime
• static Boost
• static Qt 5.x
• internal copy of Google Test
• x64 build

set "cmake_generator=Visual Studio 14 2015"
set "cmake_platform=x64"
cmake ^
-D CMAKE_USER_MAKE_RULES_OVERRIDE="%asio_samples_home_dir%/cmake/static_c_runtime_overrides.cmake" ^
-D CMAKE_USER_MAKE_RULES_OVERRIDE_CXX="%asio_samples_home_dir%/cmake/static_cxx_runtime_overrides.cmake" ^
-D ICU_ROOT="%icu_home_dir%" ^
-D BOOST_INCLUDEDIR="%boost_headers_dir%" ^
-D BOOST_LIBRARYDIR="%boost_libs_dir%" ^
-D Boost_NO_SYSTEM_PATHS=ON ^
-D Boost_USE_STATIC_LIBS=ON ^
-D Qt5Core_DIR="%qt5_home_dir%/lib/cmake/Qt5Core" ^
-D Qt5Gui_DIR="%qt5_home_dir%/lib/cmake/Qt5Gui" ^
-D Qt5Widgets_DIR="%qt5_home_dir%/lib/cmake/Qt5Widgets" ^
-G "%cmake_generator%" ^
-A "%cmake_platform%" ^
"%asio_samples_home_dir%"

Example of generation of makefiles on *nix with:

• shared C/C++ runtime
• static Boost
• shared Qt 5.x

cmake_generator="Unix Makefiles" && \
cmake \
-D Boost_USE_STATIC_LIBS=ON \
-D MA_QT_MAJOR_VERSION=5 \
-D CMAKE_BUILD_TYPE=${build_type} \
-G "${cmake_generator}" \
"${asio_samples_home_dir}"

Example of generation of Visual Studio 2015 project with:

• shared C/C++ runtime
• static Boost (which uses shared C/C++ runtime)
• shared Qt 5.x
• internal copy of Google Test
• x64 build

set "cmake_generator=Visual Studio 14 2015"
set "cmake_platform=x64"
cmake ^
-D BOOST_INCLUDEDIR="%boost_headers_dir%" ^
-D BOOST_LIBRARYDIR="%boost_libs_dir%" ^
-D Boost_NO_SYSTEM_PATHS=ON ^
-D Boost_USE_STATIC_LIBS=ON ^
-D gtest_force_shared_crt=ON ^
-D Qt5Core_DIR="%qt5_home_dir%/lib/cmake/Qt5Core" ^
-D Qt5Gui_DIR="%qt5_home_dir%/lib/cmake/Qt5Gui" ^
-D Qt5Widgets_DIR="%qt5_home_dir%/lib/cmake/Qt5Widgets" ^
-G "%cmake_generator%" ^
-A "%cmake_platform%" ^
"%asio_samples_home_dir%"

Example of generation of Visual Studio 2013 project with:

• static C/C++ runtime
• static Boost
• static Qt 5
• external Google Test
• x64 build
• Intel C++ Compiler XE 2015

set "cmake_generator=Visual Studio 12 2013"
set "cmake_platform=x64"
cmake ^
-D CMAKE_USER_MAKE_RULES_OVERRIDE="%asio_samples_home_dir%/cmake/static_c_runtime_overrides.cmake" ^
-D CMAKE_USER_MAKE_RULES_OVERRIDE_CXX="%asio_samples_home_dir%/cmake/static_cxx_runtime_overrides.cmake" ^
-D ICU_ROOT="%icu_home_dir%" ^
-D BOOST_INCLUDEDIR="%boost_headers_dir%" ^
-D BOOST_LIBRARYDIR="%boost_libs_dir%" ^
-D Boost_NO_SYSTEM_PATHS=ON ^
-D Boost_USE_STATIC_LIBS=ON ^
-D Qt5Core_DIR="%qt5_home_dir%/lib/cmake/Qt5Core" ^
-D Qt5Gui_DIR="%qt5_home_dir%/lib/cmake/Qt5Gui" ^
-D Qt5Widgets_DIR="%qt5_home_dir%/lib/cmake/Qt5Widgets" ^
-D GTEST_ROOT="%gtest_home_dir%" ^
-D CMAKE_C_COMPILER=icl ^
-D CMAKE_CXX_COMPILER=icl ^
-T "Intel C++ Compiler XE 15.0" ^
-G "%cmake_generator%" ^
-A "%cmake_platform%" ^
"%asio_samples_home_dir%"

Example of generation of Visual Studio 2015 project with:

• shared C/C++ runtime
• shared Boost
• shared Qt 5
• x64 build
• Intel C++ Compiler 2016

set "cmake_generator=Visual Studio 14 2015"
set "cmake_platform=x64"
cmake ^
-D BOOST_INCLUDEDIR="%boost_headers_dir%" ^
-D BOOST_LIBRARYDIR="%boost_libs_dir%" ^
-D Boost_NO_SYSTEM_PATHS=ON ^
-D Boost_USE_STATIC_LIBS=OFF ^
-D gtest_force_shared_crt=ON ^
-D Qt5Core_DIR="%qt5_home_dir%/lib/cmake/Qt5Core" ^
-D Qt5Gui_DIR="%qt5_home_dir%/lib/cmake/Qt5Gui" ^
-D Qt5Widgets_DIR="%qt5_home_dir%/lib/cmake/Qt5Widgets" ^
-D CMAKE_C_COMPILER=icl ^
-D CMAKE_CXX_COMPILER=icl ^
-T "Intel C++ Compiler 16.0" ^
-G "%cmake_generator%" ^
-A "%cmake_platform%" ^
"%asio_samples_home_dir%"

Example of generation of Visual Studio 2010 project with:

• shared C/C++ runtime
• static Boost (which uses shared C/C++ runtime)
• shared Qt 4.x
• x86 build

set "cmake_generator=Visual Studio 10 2010"
set "cmake_platform=Win32"
cmake ^
-D BOOST_INCLUDEDIR="%boost_headers_dir%" ^
-D BOOST_LIBRARYDIR="%boost_libs_dir%" ^
-D Boost_NO_SYSTEM_PATHS=ON ^
-D Boost_USE_STATIC_LIBS=ON ^
-D gtest_force_shared_crt=ON ^
-D QT_QMAKE_EXECUTABLE="%qt4_home_dir%/bin/qmake.exe" ^
-G "%cmake_generator%" ^
-A "%cmake_platform%" ^
"%asio_samples_home_dir%"

Example of generation of Visual Studio 2008 project with:

• static C/C++ runtime
• static Boost
• static Qt 4.x
• x86 build

set "cmake_generator=Visual Studio 9 2008"
set "cmake_platform=Win32"
cmake ^
-D CMAKE_USER_MAKE_RULES_OVERRIDE="%asio_samples_home_dir%/cmake/static_c_runtime_overrides.cmake" ^
-D CMAKE_USER_MAKE_RULES_OVERRIDE_CXX="%asio_samples_home_dir%/cmake/static_cxx_runtime_overrides.cmake" ^
-D BOOST_INCLUDEDIR="%boost_headers_dir%" ^
-D BOOST_LIBRARYDIR="%boost_libs_dir%" ^
-D Boost_NO_SYSTEM_PATHS=ON ^
-D Boost_USE_STATIC_LIBS=ON ^
-D QT_QMAKE_EXECUTABLE="%qt4_home_dir%/bin/qmake.exe" ^
-G "%cmake_generator%" ^
-A "%cmake_platform%" ^
"%asio_samples_home_dir%"

Building generated project with build system

Building of generated project can be done using chosen (during generation of project) build system or using CMake.

CMake command to build generated project (Windows Command Prompt):

cmake --build "%asio_samples_build_dir%" --config "%build_type%"

CMake command to build generated project (*nix shell):

cmake --build "${asio_samples_build_dir}" --config "${build_type}"

Running tests

Assuming current directory is asio_samples_build_dir.

CTest command to run built tests (Windows Command Prompt):

ctest --build-config "%build_type%"

CTest command to run built tests (*nix shell):

ctest --build-config "${build_type}"