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 currently no equivalent for make uninstall in the Mbed TLS CMake build system.
The following table illustrates the approximate CMake equivalents of common make commands. Most CMake examples show only the configuration step, others (like installation) correspond to different stages of the build process.
| 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 now 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 have 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. These libraries are still located in the library directory within the build tree.
The cryptography libraries are also now provided as libtfpsacrypto.<ext>, consistent with the naming used in the TF-PSA-Crypto repository.
You may need to update include paths to the public header files, see File and Directory Relocations for details.
The base name of the libraries are now tfpsacrypto (formely mbedcrypto), mbedx509 and mbedtls. As before, these base names are also the names of CMake targets to build each library. If your CMake scripts reference a cryptography library target, you need to update its name accordingly.
For example, the following CMake code:
target_link_libraries(mytarget PRIVATE mbedcrypto)
should be updated to:
target_link_libraries(mytarget PRIVATE tfpsacrypto)
You can refer to the following example demonstrating how to consume Mbed TLS as a CMake subproject:
programs/test/cmake_subprojectThe same renaming applies to the cryptography library targets declared as part of the Mbed TLS CMake package, use MbedTLS::tfpsacrypto instead of MbedTLS::mbedcrypto.
For example, the following CMake code:
find_package(MbedTLS REQUIRED) target_link_libraries(myapp PRIVATE MbedTLS::mbedcrypto)
should be updated to:
find_package(MbedTLS REQUIRED) target_link_libraries(myapp PRIVATE MbedTLS::tfpsacrypto)
You can also refer to the following example programs demonstrating how to consume Mbed TLS as a CMake package:
programs/test/cmake_packageprograms/test/cmake_package_installThe 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.
The Mbed TLS CMake build system still installs the cryptography libraries under their legacy name, libmbedcrypto.<ext>, so you can continue linking against them. The cryptography library is also now provided as libtfpsacrypto.<ext>.
Regarding the headers, the main change is the relocation of some headers to subdirectories called private. These headers are installed primarily to satisfy compiler dependencies. Others remain for historical reasons and may be cleaned up in later versions of the library.
We strongly recommend not relying on the declarations in these headers, as they may be removed or modified without notice. See the section Private Declarations in the TF-PSA-Crypto 1.0 migration guide for more information.
Finally, note the new include/tf-psa-crypto directory, which contains the TF-PSA-Crypto version and build-time configuration headers.
If you build or distribute Mbed TLS:
mbedcrypto.pc or tfpsacrypto.pc).crypto_config.h (see Configuration file split).If you integrate Mbed TLS with a platform or hardware drivers:
crypto_config.h.