Mbed TLS now uses CMake exclusively to configure and drive its build process. Support for the GNU Make and Microsoft Visual Studio project-based build systems has been removed.
The previous .sln and .vcxproj files are no longer distributed or generated.
See the Compiling section in README.md for instructions on building the Mbed TLS libraries and tests with CMake. If you develop in Microsoft Visual Studio, you could either generate a Visual Studio solution using a CMake generator, or open the CMake project directly in Visual Studio.
With the removal of GNU Make support, all build, test, and installation operations must now be performed using CMake. This section provides a quick reference for translating common make commands into their CMake equivalents.
Run cmake -S . -B build once before building to configure the build and generate native build files (e.g., Makefiles) in the build directory. This sets up an out-of-tree build, which is recommended.
| Make command | CMake equivalent | Description |
|---|---|---|
make | cmake --build build | Build the libraries, programs, and tests in the build directory. |
make test | ctest --test-dir build | Run the tests produced by the previous build. |
make clean | cmake --build build --target clean | Remove build artifacts produced by the previous build. |
make install | cmake --install build --prefix build/install | Install the built libraries, headers, and tests to build/install. |
Unless otherwise specified, the CMake command in the table below should be preceded by a cmake -S . -B build call to configure the build and generate build files in the build directory.
| Make command | CMake equivalent | Description |
|---|---|---|
make lib | cmake --build build --target lib | Build only the libraries. |
make tests | cmake -S . -B build -DENABLE_PROGRAMS=Off && cmake --build build | Build test suites. |
make programs | cmake --build build --target programs | Build example programs. |
make apidoc | cmake --build build --target mbedtls-apidoc | Build documentation. |
Target names may differ slightly; use cmake --build build --target help to list all available CMake targets.
There is no CMake equivalent for make generated_files or make neat. Generated files are automatically created in the build tree with cmake --build build and removed with cmake --build build --target clean. If you need to build the generated files in the source tree without involving CMake, you can call framework/scripts/make_generated_files.py.
There is no CMake equivalent for make uninstall. To remove an installation, simply delete the directory specified as the installation prefix.
| Make usage | CMake usage | Description |
|---|---|---|
make DEBUG=1 | cmake -S . -B build -DCMAKE_BUILD_TYPE=Debug | Build in debug mode. |
make SHARED=1 | cmake -S . -B build -DUSE_SHARED_MBEDTLS_LIBRARY=On | Also build shared libraries. |
make GEN_FILES="" | cmake -S . -B build -DGEN_FILES=OFF | Skip generating files (not a strict equivalent). |
make DESTDIR=install_dir | cmake --install build --prefix install_dir | Specify installation path. |
make CC=clang | cmake -S . -B build -DCMAKE_C_COMPILER=clang | Set the compiler. |
make CFLAGS='-O2 -Wall' | cmake -S . -B build -DCMAKE_C_FLAGS="-O2 -Wall" | Set compiler flags. |
In Mbed TLS 4.0, the project was split into two repositories:
The following table summarizes the file and directory relocations resulting from the repository split between Mbed TLS and TF-PSA-Crypto. These changes reflect the move of cryptographic, cryptographic-adjacent, and platform components from Mbed TLS into the new TF-PSA-Crypto repository.
| Original location | New location(s) | Notes |
|---|---|---|
library/* (*) | tf-psa-crypto/core/tf-psa-crypto/drivers/builtin/src/ | Contains cryptographic, cryptographic-adjacent (e.g., ASN.1, Base64), and platform C modules and headers. |
include/mbedtls/* (*) | tf-psa-crypto/include/mbedtls/tf-psa-crypto/drivers/builtin/include/private/ | Public headers moved to include/mbedtls; now internal headers moved to include/private. |
include/psa | tf-psa-crypto/include/psa | All PSA headers consolidated here. |
3rdparty/everest3rdparty/p256-m | tf-psa-crypto/drivers/everesttf-psa-crypto/drivers/p256-m | Third-party crypto driver implementations. |
(*) The library and include/mbedtls directories still exist in Mbed TLS, but not contain only TLS and X.509 components.
Cryptography and platform configuration options have been moved from include/mbedtls/mbedtls_config.h to tf-psa-crypto/include/psa/crypto_config.h, which is now mandatory. See Compile-time configuration.
The header include/mbedtls/mbedtls_config.h still exists and now contains only the TLS and X.509 configuration options.
If you use the Python script scripts/config.py to adjust your configuration, you do not need to modify your scripts to specify which configuration file to edit, the script automatically updates the correct file.
There has been significant changes in the configuration options, primarily affecting cryptography.
For details about TLS-related changes, see Changes to TLS options.
After checking out a branch or tag of the Mbed TLS repository, you must now recursively update the submodules, as TF-PSA-Crypto contains itself a nested submodule:
git submodule update --init --recursive
The Mbed TLS CMake build system still provides the cryptography libraries under their legacy name, libmbedcrypto.<ext>, so you can continue linking against them. The cryptography libraries are also now provided as libtfpsacrypto.<ext> like in the TF-PSA-Crypto repository.
The base name of the CMake cryptography library target has been changed from mbedcrypto to tfpsacrypto. If no target prefix is specified through the MBEDTLS_TARGET_PREFIX option, the associated CMake target is thus now tfpsacrypto.
The same renaming applies to the cryptography library targets declared as part of the Mbed TLS CMake package. When no global target prefix is defined, use MbedTLS::tfpsacrypto instead of MbedTLS::mbedcrypto.
As an example, the following CMake code:
find_package(MbedTLS REQUIRED) target_link_libraries(myapp PRIVATE MbedTLS::mbedtls MbedTLS::mbedx509 MbedTLS::mbedcrypto)
would be updated to something like
find_package(MbedTLS REQUIRED) target_link_libraries(myapp PRIVATE MbedTLS::mbedtls MbedTLS::mbedx509 MbedTLS::tfpsacrypto)
For more information, see the CMake section of README.md. You can also refer to the following example programs demonstrating how to consume Mbed TLS via CMake:
programs/test/cmake_subprojectprograms/test/cmake_packageprograms/test/cmake_package_install.The Mbed TLS CMake build system still provides the pkg-config file mbedcrypto.pc, so you can continue using it. Internally, it now references the tfpsacrypto library. A new pkg-config file, tfpsacrypto.pc, is also provided. Both mbedcrypto.pc and tfpsacrypto.pc are functionally equivalent, providing the same compiler and linker flags.
pkg-config files (mbedcrypto.pc / tfpsacrypto.pc).If you build or distribute Mbed TLS:
pkg-config files (mbedcrypto.pc / tfpsacrypto.pc).crypto_config.h (see Configuration file split).If you integrate Mbed TLS with a platform or hardware drivers:
crypto_config.h.