CMake
CMake is a build process manager designed to be used with the native build system of the platform. CMake supports various platforms, including Windows desktops and servers, Windows Phone, Windows Store, Linux, OS X, Android, iOS, Solaris, Unix and others. Its appealing to use CMake because it supports so many platforms.
Crypto++ 5.6.3 through 5.6.5 provided limited Cmake support. CMake was removed from the library prior to the release of Crypto++ 6.0. The Crypto++ mailing list discussion is at Remove CMake from GitHub; add it to Patch Page on wiki?, and the check-in of interest is Commit 913a9e60d375e458.
The CMake project files are now maintained by the community, and not the library. If you want to use CMake then download it from GitHub | cryptopp-cmake. If you have an improvement, then make the change and submit a pull request. It is a separate project to ensure folks don't accidentally use it. (Our unofficial Android.mk and Autotools are separate projects, too).
If you built the Crypto++ library using the makefile or MSBuild then you can incorporate it into a CMake project by following CMake link to external library.
A related topic is Requirements. Crypto++ attempts to minimize external dependencies like Autotools and CMake, so CMake will likely never be part of the official sources.
Many thanks to the folks who contributed to the CMake task. Special thanks to GamePad64, who made early contributions and wrote the initial wiki page. Additional thanks go to Anonimal, who also provided patches.
Bug Reports
CMake questions and bug reports should be reported at cryptopp-cmake. Please do not ask questions or report bugs at the Crypto++ GitHub.
Using CMake
This section provides instructions on using CMake to build the library. If the library is built and your are trying to CMake find it, then see CMake link to external library on Stack Overflow.
Create a build directory
First, create a directory outside the source directory, for example /home/user/cryptopp-build, then cd into it.
$ mkdir /home/user/cryptopp-build $ cd /home/user/cryptopp-build
This step is optional, but recommended. CMake creates out-of-source builds, so all the build artifacts are created in a separate directory, leaving the original source directory untouched. You can read more at CMake FAQ.
Select Options
The Crypto++ library can be configured to suit your particular needs. For example, it can be configured for a dbug build or a release build. To select a library configuration, use CMake options to control the library configuration. Multiple options can be selected.
To set an option, simply pass it to CMake using -D. For example, to enable a debeg configuration, perform the following.
cmake ... -DCMAKE_BUILD_TYPE=Release -DDISABLE_ASM=OFF
The table below provides CMake options to control library configurations.
| Define | Values | Default | Comments |
|---|---|---|---|
BUILD_TESTING |
ON/OFF | ON | Enables building the test drive program (cryptest.exe).
|
BUILD_DOCUMENTATION |
ON/OFF | OFF | Enables building documentation using Doxygen. |
DISABLE_ASM |
ON/OFF | OFF | Disables assembler and intrinsic code. This is a fail safe option and it should not be needed. Also see the wiki page config.h | assembly defines. |
DISABLE_SSSE3 |
ON/OFF | OFF | Disables SSSE3 instructions. This option is needed for some older Binutils due to downlevel assemblers. Also see the wiki page config.h | assembly defines. |
DISABLE_SSE4 |
ON/OFF | OFF | Disables SSE4.1 and SSE4.2 instructions. This option is needed for some older Binutils due to downlevel assemblers. Also see the wiki page config.h | assembly defines. |
DISABLE_AESNI |
ON/OFF | OFF | Disables AES-NI instructions. This option is needed for some older Binutils due to downlevel assemblers. Also see the wiki page config.h | assembly defines. |
DISABLE_SHA |
ON/OFF | OFF | Disables SHA instructions. This option is needed for some Binutils due to downlevel assemblers. Also see the wiki page config.h | assembly defines. |
CRYPTOPP_NATIVE_ARCH |
ON/OFF | OFF | Enables the addition of -march=native (IA32), -march=armv7-a -mfpu=neon (AMRv7a) or -march=armv8-a (AMRv8a) to CXXFLAGS.
|
CRYPTOPP_DATA_DIR |
- | "" | Sets the Crypto++ test data directory. The default value is an empty string. For more information see Issue #82: Add Debian-style Data Directory patch. |
CMAKE_INSTALL_PREFIX |
- | - | Sets the install prefix (similar to --prefix in Autotools). The default value is platform dependent.
|
CMAKE_BUILD_TYPE |
See below | Debug | Sets the build type. The value can be one of Debug/Release/MinSizeRel/RelWithDebInfo. You should explicitly set this value.
|
Note: the library's CRYPTOPP_DISABLE_ASM is a fail-safe. It should not be needed under any configurations, from X86 or X64 through ARM or MIPS. If its needed, then please report it on the mailing list or bug tracker so the issue can be fixed.
DISABLE_SSSE3, DISABLE_SSE4, DISABLE_AESNI, and DISABLE_SHA are automatically engaged if the assembler is too old to assemble an object file with the respective instruction. DISABLE_SHA is new, and it may miss the mark. If its needed, then please report it on the mailing list or bug tracker so the issue can be fixed.
If given a choice you should enable CRYPTOPP_NATIVE_ARCH by configuring CMake with -DCRYPTOPP_NATIVE_ARCH=1. On modern processors it will engage CPU features like AVX, AVX2, BMI and BMI2. AVX-based memcpy is often translated into 32-byte vmovdqa/vmovdqu and it is lightening fast. The library will usually perform much better with CRYPTOPP_NATIVE_ARCH.
The table below discusses values for CMAKE_BUILD_TYPE.
| Value | Comments |
|---|---|
Debug |
This option is similar to -O0 -g.
|
Release |
This option is similar to -O2 -DNDEBUG.
|
MinSizeRel |
This option is similar to -Os -DNDEBUG.
|
RelWithDebInfo |
This option is similar to -O2 -DNDEBUG -g. This is mostly used to strip symbols into a separate file after building. For example, for building -dbg packages in Debian.
|
Generate Makefiles
Next, generate the makefiles. Be sure to use the source directory as argument; and not the build directory. It may be either absolute or relative path.
$ cmake /home/user/cryptopp
Build the Library
Once the Makefiles are generated, you only have to run make to compile and link the library and test program.
$ make
This step builds static and shared versions of the library + tests binary (cryptest). If you want to build only shared or static version, then make cryptopp-static or cryptopp-shared targets. Like so: $ make cryptopp-static.
A more cross-platform way to build is to invoke $ cmake --build . (notice the dot) instead of make. It can be used, if we use non-Makefile generator (Ninja or Visual Studio, for example).
CMake hides the output of the compilation process by default. You can use VERBOSE=1 to display it. Please use VERBOSE=1 if you are asking for help on the mailing list or filing a bug report.
Test the Library
Once the library is built, it should be tested to ensure operational correctness.
TODO: talk about how to run cryptest.exe v and cryptest.exe tv all
Install the library
To install the library after building invoke
# make install
If you want to change installation prefix, you can do it using -DCMAKE_INSTALL_PREFIX=YOUR_INSTALL_PREFIX as described in CMake Options.
Note, that you may need root privileges if you install it in a system location.
Importing Crypto++
If you have a project that uses Crypto++ and CMake, and you want to add Crypto++ as a dependency. Include directories will be added automatically.
On Linux add these lines to CMakeLists.txt in your project directory:
find_package(CryptoPP REQUIRED) target_link_libraries(YOUR_TARGET_NAME cryptopp-static)
If you want to link with static version of the library, then use cryptopp-static instead of cryptopp-shared. On Windows you must use cryptopp-static because the dynamic link library is the FIPS DLL (which is something you should avoid).
Also see Issue 249, How to find Crypto++ package using CMake? and CMake link to external library on Stack Overflow. In Issue 249 we were trying to figure out what needed to be done. Unfortunately the CMake manual did not cover the topic and their mailing list was closed to subscriptions so we could not ask questions.
IDE Generators
CMake includes built-in support for a number of command line and IDE environments, including Nmake, Unix, VC++, Visual Studio 2002-2013 and Xcode. You can enlist a Generator with the -G option:
# Visual Studio 2013 cmake -G "Visual Studio 12" #Xcode cmake -G "Xcode"
Sometimes the output artifacts don't work as expected. For example, CMake does not generate a functioning set of Xcode project files; see Issue 355: CMake-based Xcode build fails to build any library, Issue 374: CMake XCode build on macOS fails and Cmake generated Xcode project does not produce library artifacts? on Stack Overflow.
CMake Removal
CMake was added to the library at Crypto++ 5.6.3. The CMake project files never achieved a good state and no one was available with the necessary skills to move them into a good state (or maybe, no one was available to perform the work). CMake was a failed experiment and removed from the library prior to the release of Crypto++ 6.0. The mailing list discussion is at Remove CMake from GitHub; add it to Patch Page on wiki?, and the check-in of interest is Commit 913a9e60d375e458.
CMake was a good learning experience. Based on the experience we knew not to add Android and Autotools to the official sources because the projects would likely suffer the same problems as CMake. In fact, Android, Autotools and CMake are all hosted on GitHub in separate projects and all carry the same "unofficial warnings".
Current Status
The table below lists the state of the CMake project files before they were removed.
| Platform | Status | Comments |
|---|---|---|
| Windows x86 | Not using library options | |
| Windows x64 | Not using library options | |
| Windows Phone | Not using library options | |
| Windows Store | Unknown | |
| MinGW | Don't care | Abandoned by its authors |
| MinGW-64 | Unknown | |
| Cygwin | Unknown | |
| Cygwin-64 | Unknown | |
| Linux i686 | Mostly using library options | |
| Linux x86_64 | Mostly using library options | |
| OS X i386 | Unknown | |
| OS X x86_64 | Unknown | |
| OS X PPC | Unknown | |
| iOS ARM | Unknown | |
| iOS ARM64 | Unknown | |
| iOS TV | Unknown | |
| iOS Watch | Unknown | |
| Linux A-32 | Mostly using library options | |
| Linux Aarch32 | Mostly using library options | |
| Linux Aarch64 | Mostly using library options | |
| Linux MIPS | Not using library options | |
| Linux MIPS64 | Not using library options | |
| Linux PPC | Mostly using library options | |
| Linux PPC64 | Mostly using library options | |
| AIX PPC | Unknown | |
| AIX PPC64 | Unknown | |
| Solaris i386 | Mostly using library options for GCC | Linker flags missing -xarch options
|
| Solaris x86_64 | Mostly using library options for GCC | Linker flags missing -xarch options
|
| Solaris Sparc | Mostly using library options for GCC | Linker flags missing -xarch options
|
| Solaris Sparc64 | Mostly using library options for GCC | Linker flags missing -xarch options
|
| Android armeabi | Not using library options | Not using Android options |
| Android armv7a | Not using library options | Not using Android options |
| Android armv7a+NEON | Not using library options | Not using Android options |
| Android armv8a | Not using library options | Not using Android options |
| Android i686 | Not using library options | Not using Android options |
| Android x86_64 | Not using library options | Not using Android options |
Downloads
cryptopp-cmake - GitHub with the latest CMake sources. This GitHub handles Crypto++ 8.7.0 and forward. Releases are tagged so you can download a version of the CMake project files to fit a version of the library.
cryptopp-cmake - Old CMake sources, read-only for historical purposes. This GitHub handled Crypto++ 8.6.0 and below. Releases are tagged so you can download a version of the CMake project files to fit a version of the library.