Building CharLS

Introduction

The most practical way to use CharLS is to use the source distribution and build it yourself. This ensures that the library matches your C++ compiler and environment. This can be done from the git repository or the released versions of CharLS in the C++ package managers vcpkg or Conan.
The next sections will explain how to build CharLS from its git repository. These sections assume that the reader has a basic understanding how to build C++ software libraries.

General

Required Tools

Git
CharLS is maintained in a git repository hosted on Github. Released versions can be downloaded as a zip or tar.gz file. Unreleased version can be retrieved as a git repository. A git client can be downloaded from http://git-scm.com or installed with your prefered package manager.

CMake
CharLS ships with a CMakeLists.txt files that can be used with CMake. CMake is a cross platform meta build tool that can generate native build scripts. CMake can be downloaded from http://www.cmake.org/ or installed with your prefered package manager. CMake also requires an build tool like Ninja, msbuild or make that also needs to be installed.

C++ Compiler
To build CharLS 3.x a C++ 17 compatible compiler is required (Charls 2.x can be build with C++14 and CharLS 1.x can be build with C++03). If a C++ compiler is installed correctly on your system CMake will be able to locate it.

General Build Steps

1. Clone the CharLS Git repository to your own system.

2. CMake can be used to build in-source and out-of-source. The recommendation is to build CharLS out-of-source:

3. To build the “debug” version, use the following steps:

   • cd into the root directory of your cloned charls directory
   • mkdir debug
   • cd debug
   • cmake -DCMAKE_BUILD_TYPE=Debug .. (static library) or
   • cmake -DCMAKE_BUILD_TYPE=Debug -DBUILD_SHARED_LIBS=On .. (shared library)
   • cmake --build .

4. To build the “release” version, use the following steps:

   • cd into the root directory of your cloned charls directory
   • mkdir release
   • cd release
   • cmake -DCMAKE_BUILD_TYPE=Release .. (static library) or
   • cmake -DCMAKE_BUILD_TYPE=Release -DBUILD_SHARED_LIBS=On .. (shared library) cmake --build .

Note 1: On Windows pass -G Ninja to the cmake command line to force the creation of ninja make files. The default on the Windows platform is to generate Visual Studio project files.

Windows (Visual Studio)

CharLS comes also with a Visual Studio 2019\2022 solution. Instead of using CMake, MSBuild or the Visual Studio 2022 IDE can be used to build Charls. Newer versions of Visual Studio can also open directly the CMakeLists.txt build script.

Windows (MinGW \ MSYS2)

GCC for Windows (MinGW) can be used to build CharLS, for example: - cmake -DCMAKE_BUILD_TYPE=Release -DBUILD_SHARED_LIBS=On -G "MinGW Makefiles" .. - make

macOS (Xcode)

The provided CMake CMakeLists.txt build script files can also be used to create a Xcode project file, allowing CharLS to be build inside the Xcode IDE. The following steps will create a Xcode project file and open it in Xcode:
- cd into the root directory of your cloned charls directory
- mkdir build
- cd build
- cmake -G Xcode ..
- open charls.xcodeproj/