Build Instructions

Blend2D uses CMake to create native platform (or IDE) projects and to build them. Consult cmake-generators page to see which generators are supported on your target platform. You don't have to use CMake if you prefer other tools, but then you would have to set some compile flags and definitions manually, which is covered by Building Without CMake section. At the moment Blend2D only depends on AsmJit library, which is part of Blend2D source releases, but it's not part of Blend2D git repository. Git users have to clone AsmJit library separately.

Note

This page documents the process of building Blend2D. If you are more interested in using Blend2D within your own project the Getting Started page is much easier and provides all the information to use Blend2D in a CMake project.

Build Requirements

Operating systems supported:

  • Linux (tested on CI).
  • BSDs (FreeBSD, NetBSD, OpenBSD tested on CI).
  • MacOS (tested on CI).
  • Windows 7+ (Windows 10+ tested on CI).
  • Other operating systems may or may not work (nothing else tested on CI).

CPU architectures supported:

  • X86 - Both 32-bit and 64-bit targets are supported
  • ARM - Reference pipeline only (reference pipeline is currently limited to solid fills only and doesn't provide ASIMD acceleration)
  • Other architectures will be supported in the future via a reference pipeline written in C++

C++ compilers supported:

  • Clang with C++11 support enabled (Clang 10+ tested on CI)
  • GCC 4.8+ with C++ support enabled (GCC 7+ tested on CI)
  • MSVC 2019+ (VS-2019 and VS-2022 tested on CI)

Important

It's strongly advised to use latest compilers to compile Blend2D on all platforms to achieve maximum performance. Many floating point computations that are implemented in C++ can be autovectorized, so a capable compiler can make a significant difference.

Unsafe Optimizations

Never use unsafe math optimizations like -ffast-math, -ffinite-math-only, or /fp:fast as Blend2D relies on existence of NaN and Infinity. Additionally, C++ compiler should never reorder any floating point expressions as some expressions are very sensitive to such reordering. The only optimization that is allowed is using fused-multiply-add (FMA) instructions if they are available.

Build Configuration

By default only dynamically linked blend2d library is built. The following CMake build options are available:

Option Default Description
CMAKE_BUILD_TYPE (unset) Highly depends on CMake generator used:
  • If you use IDE that supports multiple configurations like Visual Studio or Xcode then leave it empty and use your IDE to select the build type you want
  • If you use a makefile based generator or ninja then you should set it to Release as Debug builds are order of magnitude slower than release builds
ASMJIT_DIR (unset) Where to find AsmJit library for static inclusion. Should be unset to let Blend2D autodetect the location:
  • <blend2d>/3rdparty/asmjit - Third party directory used by source releases
  • <blend2d>/../asmjit - Git users usually clone AsmJit at the same directory level as Blend2D
BLEND2D_TEST false Whether to build tests.
BLEND2D_EMBED false Whether to embed Blend2D library, which enables:
  • Building Blend2D as part of your project without creating any intermediate targets like static or dynamic libraries
  • Building Blend2D statically - BL_STATIC is implied by BL_EMBED so the build won't export any symbols
BLEND2D_STATIC false Whether to build Blend2D statically:
  • This would create a static library blend2d and provide Blend2D::Blend2D target that you can link to
  • When enabled BL_STATIC is defined during the build and must be defined as well by any code that includes Blend2D. If you use Blend2D::Blend2D target then you don't have to worry about anything as all the necessary stuff would be deduced from using the target
BLEND2D_SANITIZE (unset) Sanitizers to use to build Blend2D, possible options are address, undefined, thread, etc...
  • This option is only useful for Blend2D developers or for people that are facing runtime problems
  • Sanitizer-enabled builds are slower, but can discover issues that would not be discovered by normal debug builds
  • memory sanitizer is not reliable as Blend2D uses a JIT compiler that doesn't instrument the code, using it would lead to false positives
BLEND2D_NO_FUTEX false Disables using futexes (this is only useful for testing or as a workaround to disable Futexes in case that there is a bug in Blend2D)
BLEND2D_NO_INTRINSICS false Disables the use of non-SIMD intrinsics in Blend2D (there is no reason to explicitly turn on this option, it's only useful for testing)
BLEND2D_NO_INSTALL false If true Blend2D won't install blend2d library and public header files. Useful in cases in which Blend2D is compiles statically as a part of another project, which has install targets, but installing Blend2D is unwanted
BLEND2D_NO_JIT false Disables JIT compiler and AsmJit dependency (experimental, not suited for production)
BLEND2D_NO_NATVIS false Disables embedding blend2d.natvis file in Blend2D binary
BLEND2D_NO_STDCXX (unset) Disables linking to a C++ standard library. This option is autodetected - dynamically linked Blend2D library would not link to a standard C++ library by default
BLEND2D_NO_TLS false Disables the use of thread-local storage (there is no reason to explicitly turn on this option unless you are having issues with TLS or your target is operating system that has a very limited size of TLS)

Building From Source

The following steps can be used to clone and build Blend2D directly from git:

# Get both Blend2D and AsmJit.
$ git clone https://github.com/asmjit/asmjit
$ git clone https://github.com/blend2d/blend2d

# Create build directory.
$ mkdir blend2d/build
$ cd blend2d/build

# Configure the project. This would create either makefiles or
# IDE specific project files that are required to compile the
# project. Use BLEND2D_TEST to build tests.
#
# NOTE: Leave build type empty if you use Visual Studio or Xcode
$ cmake .. -DCMAKE_BUILD_TYPE=Release -DBLEND2D_TEST=TRUE

# Build the project. The build command depends on cmake-generator
# used to configure the project. If you use makefiles then `make`
# would be the command, otherwise it could be `ninja` or other IDE
# specific command.
$ cmake --build .

# Alternatively, if you use IDE such as Visual Studio or Xcode you
# may need to select the build type, which would default to Debug
# by default.
$ cmake -- build . --config Release

# DONE: You should have either blend2d.dll or libblend2d.so library.

The following steps can be used to build Blend2D source release:

# Get source release directly from blend2d.com.
$ wget https://blend2d.com/download/blend2d-VERSION.zip
$ unzip blend2d-VERSION.zip

# Create build directory.
$ mkdir blend2d/build
$ cd blend2d/build

# Configure and build (see the previous section for more details).
$ cmake .. -DCMAKE_BUILD_TYPE=Release -DBLEND2D_TEST=TRUE
$ cmake --build .

# DONE: You should have either blend2d.dll or libblend2d.so library.

Building Sample Applications

The same approach can be used to build sample applications. The following example shows how to clone everything from Blend2D git repositories, but it would work with source as well:

# Get both Blend2D and AsmJit.
$ git clone https://github.com/asmjit/asmjit
$ git clone https://github.com/blend2d/blend2d

# Get Blend2D interactive demos and a benchmarking tool.
$ git clone https://github.com/blend2d/blend2d-apps

# Build blend2d-apps - will try to autodetect Cairo and Qt.
$ mkdir blend2d-apps/build
$ cd blend2d-apps/build
$ cmake .. -DCMAKE_BUILD_TYPE=Release
$ cmake --build .
$ cd ..

# DONE: Your samples are compiled...

Building Without CMake

This page documents the process of building Blend2D without any help of CMake build scripts. It can be used as a reference of what CMake scripts are doing and as a recommendation of building Blend2D with other build tools or no build tools at all. Blend2D exports C API, but it's still a library written in C++ and requires at least C++11 capable compiler.

Compiler Independent Setup

  • Add the following source files to your target:
    • All source files in Blend2D src directory
    • All source files in AsmJit src directory. If you downloaded a source release of Blend2D then AsmJit will be at 3rdparty/asmjit directory within Blend2D project
  • Setup the C++ compiler in the following way:
    • Enable at least C++11 through -std=c++11 or /std:c++latest. C++17 is preferred though
    • Add ${ASMJIT_DIR}/src to your include path through -I... option
    • Define ASMJIT_STATIC to tell asmjit that it will be built statically
  • Define the following compile-time definitions to select a build type:
    • NDEBUG - should be always defined for release builds (standard C way)
    • BL_BUILD_DEBUG - force debug build, overrides autodetection based on NDEBUG (optional).
    • BL_BUILD_RELEASE - force release build, overrides autodetection based on NDEBUG (optional)
  • Define the following compile-time definitions to enable architecture-specific optimizations:
    • BL_BUILD_OPT_SSE2 - enables SSE2 optimizations (should be always enabled)
    • BL_BUILD_OPT_SSE3 - enables SSE3 optimizations
    • BL_BUILD_OPT_SSSE3 - enables SSSE3 optimizations
    • BL_BUILD_OPT_SSE4_1 - enables SSE4.1 optimizations
    • BL_BUILD_OPT_SSE4_2 - enables SSE4.2 optimizations
    • BL_BUILD_OPT_AVX - enables AVX optimizations
    • BL_BUILD_OPT_AVX2 - enables AVX2 optimizations

Compiler Specific Setup [GCC & Clang]

  • Use the following [optional] compiler flags to make the resulting binaries better:
    • -fvisibility=hidden - Blend2D API uses explicit public visibility so everything else should be hidden by default. Alternatively -fvisibility-inlines-hidden can be specified
    • -fno-exceptions - Blend2D doesn't use exceptions so you can turn them off
    • -fno-rtti - Blend2D doesn't use runtime type information or dynamic casts so you can turn this feature off
    • -fno-math-errno - Blend2D doesn't check errno after calling math functions, this option may help the C++ compiler to inline some intrinsic functions like sqrt
    • -fno-semantic-interposition - Better code generated as the compiler doesn't have to assume semantic interposition, GCC documentation , Clang uses this flag by default
    • -fno-threadsafe-statics - Blend2D has its own initialization step, which initializes everything required to make the library functional, thus thread-safe statics are not needed to guard initialization of static variables
    • -fmerge-all-constants - Blend2D doesn't compare pointers of constants so it's perfectly fine to merge constants having the same values
    • -ftree-vectorize - some compilers need this option to vectorize some constructs that Blend2D uses, however, this option would be probably set automatically at certain optimization levels by the compiler
    • -O2 or -O3 - it should be enough to use -O2 as -O3 often only increases code-size without increasing its performance
  • Each file with a certain suffix requires to be compiled with extra flags that enable architecture specific optimizations:
    • -msse2 must be used to compile *_sse2.cpp files if BL_BUILD_OPT_SSE2 was enabled
    • -msse3 must be used to compile *_sse3.cpp files if BL_BUILD_OPT_SSE3 was enabled
    • -mssse3 must be used to compile *_ssse3.cpp files if BL_BUILD_OPT_SSSE3 was enabled
    • -msse4.1 must be used to compile *_sse4_1.cpp files if BL_BUILD_OPT_SSE4_1 was enabled
    • -msse4.2 must be used to compile *_sse4_2.cpp files if BL_BUILD_OPT_SSE4_2 was enabled
    • -mavx must be used to compile *_avx.cpp files if BL_BUILD_OPT_AVX was enabled
    • -mavx2 must be used to compile *_avx2.cpp files if BL_BUILD_OPT_AVX2 was enabled

Compiler Specific Setup [MSVC]

  • Use the following [optional] compiler flags to make the resulting binaries better:
    • -O2 - favor performance over size
  • Each file with a certain suffix requires to be compiled with extra flags that enable architecture specific optimizations:
    • -arch:SSE2 and -D__SSE2__ must be used to compile *_sse2.cpp files if BL_BUILD_OPT_SSE2 was enabled
    • -arch:SSE2 and -D__SSE3__ must be used to compile *_sse3.cpp files if BL_BUILD_OPT_SSE3 was enabled
    • -arch:SSE2 and -D__SSSE3__ must be used to compile *_ssse3.cpp files if BL_BUILD_OPT_SSSE3 was enabled
    • -arch:SSE2 and -D__SSE4_1__ must be used to compile *_sse4_1.cpp files if BL_BUILD_OPT_SSE4_1 was enabled
    • -arch:SSE2 and -D__SSE4_2__ must be used to compile *_sse4_2.cpp files if BL_BUILD_OPT_SSE4_2 was enabled
    • -arch:AVX must be used to compile *_avx.cpp files if BL_BUILD_OPT_AVX was enabled
    • -arch:AVX2 must be used to compile *_avx2.cpp files if BL_BUILD_OPT_AVX2 was enabled
  • If you use LLVM toolchain, which meas that a clang-cl compiler is used instead of stock cl it's important to explicitly enable SSE3, SSSE3, SSE4.1, and SSE4.2 optimizations together with -arch:SSE2, otherwise the compilation would fail as Clang is not fully compatible with MS stock compiler:
    • -arch:SSE2 and -msse3 must be used to compile *_sse3.cpp files if BL_BUILD_OPT_SSE3 was enabled
    • -arch:SSE2 and -mssse3 must be used to compile *_ssse3.cpp files if BL_BUILD_OPT_SSSE3 was enabled
    • -arch:SSE2 and -msse4.1 must be used to compile *_sse4_1.cpp files if BL_BUILD_OPT_SSE4_1 was enabled
    • -arch:SSE2 and -msse4.2 must be used to compile *_sse4_2.cpp files if BL_BUILD_OPT_SSE4_2 was enabled

Linker Options

  • The following libraries are required on Windows:
    • (to be documented)
  • The following libraries are required on Linux, BSDs, and others:
    • libc (standard C library)
    • libm (if not part of standard C library)
    • libpthread (required to support multithreading)
    • librt (Required on Linux by clock_gettime() function)