Crypto++ CMake

-+- Build Status -+-

-+-

Introduction

This repository contains CMake files for Wei Dai's Crypto++ (https://github.com/weidai11/cryptopp) for those who use the library in Modern CMake projects.

See this announcement from crypto++ maintainers.

The emphasis on Modern here is very important. In 2022, we have some really good solutions to many of the build problems developers used to waste a lot of time on. CMake in particular has made so much progress to become one of the most widely used build systems for C++. But, we're not talking about CMake 2.x here. We're talking about CMake 3.11+ and maybe even CMake 3.24+.

For more details on this topic, see down below...

Table of Contents

• Crypto++ CMake
  • Introduction
  • Table of Contents
  • Before you ask
  • Versioning principles
  • Standard usage
  • Using a local copy of crypto++
  • Requesting the master branch of cryptopp
  • Other ways
  • Why Modern CMake?

Before you ask

• Can you support an older version of CMake? You really don't need 3.21...

  No.

  This is an opinionated fork with the main purpose being to stay always on a recent version of CMake. We believe that the build system should be the latest unlike compilers and Operating Systems. If you want to stay on old versions, please take a look at the old repo.

• Can you fix the shared library build? I really like DLLs...

  Me too, but No.

  Crypto++ does not properly export symbols and manage visibility. You can request this feature from the crypto++ project maintainers. The old DLL build was only for FIPS version, with limited symbol exports. That version is going end-of-life and there is no point from supporting it here.

  If you love DLLs, you can make a Wrapper DLL as explained on crypto++ wiki.

  The CMakeLists.txt in this project are already built for shared and static builds, but the shared build is locked until crypto++ is ready for it.

• Why did you change XXX? It used to work like YYY before...

  I don't know.

  I use crypto++ in my project, and I use it in a way that I learnt and improved over time through experience, extensive reading of other peoples' experiences, and sticking as close as possible to modern cmake practices. I'm open to new ways and suggestions, especially if they come via a tracked issue, a rationale and a pull request. If you have a valid use case, please document it in an issue and let's find someone to help make it happen for you. It's Open Source 😃

Versioning principles

This project releases track the crypto++ releases. In other words, every time a new release of crypto++ happens, this project gets updated to take into account changes in source files, compiler options etc, and will see a new release with the same number than crypto++.

At times, bug fixes in this project will happen before a new crypto++ release is published. When a certain number of fixes have been added, and depending on the criticality of the defects, an additional release tag may be made. These patch tags will never introduce any additional changes in crypto++ itself.

Main release tags will have the format: CRYPTOPP_M_m_p, while patch tags will have the format CRYPTOPP_M_m_p_f, where M.m.p represents the crypto++ version and f is a suffix number incremented each time a patch tag is created. Patch tags will keep the same crypto++ version as the main release tag.

As always, if you want to get the latest and greatest, always track the master branch.

Standard usage

• Get this project using your favorite method (clone as submodule, get with FetchContent, get with CPM...)

• In your master CMakeLists.txt, add the following:

  add_subdirectory(xxxx)
  # where xxx is the location where you put the cryptopp-cmake files

  That's pretty much it. You'll be able to link against cryptopp or the scoped alias cryptopp::cryptopp and have cmake handle everything else for you.

An example is located in the test/standard-cpm directory.

Using a local copy of crypto++

Certain users would prefer to have a fully disconnected project, and in such scenario both the crypto++ source package and the cryptopp-cmake source package would be pre-downloaded and then unpacked somewhere.

You would still need to add cryptopp-cmake as a subdirectory in your master CMakeLists.txt, and you can set it up in such a way to use your local copy of crypto++ via the option CRYPTOPP_SOURCES. Just set that option in the cmake command line or in your CMakeLists.txt to point to the crypto++ source directory. The rest will be taken care of for you.

Requesting the master branch of cryptopp

If you want to test the bleeding edge of crypto++ with cmake, simply set the option CRYPTOPP_USE_MASTER_BRANCH in your CMakeLists.txt or the cmake command line and as usual, add the cryptopp-cmake as a subdirectory.

Other ways

There are many other ways to use this project, including by directly picking the files you need and adding them to your own project, by getting the package via conan, etc... Take some time to read the source code, and make suggestions if you need a new usage scenario via a new issue.

Why Modern CMake?

Have a look at Installing CMake from the online 'Modern CMake' book, to see a recent snapshot of which version of CMake is being installed by default on Linux distributions.

And more than that, it's so easy to install a modern version of CMake on Linux/MacOS/Windows, and many other OSes.

Looking at the release notes of CMake versions from 3.0 till now, a minimum version requirement of 3.21 is a good starting point. That release brings in particular presets and some nice quality of life features that will make the maintenance and the use of this project much simpler and pleasant. After all, there is no justification for doing free Open Source without pleasure 😃