mbedtls/docs/4.0-migration-guide/repo-split.md

CMake as the only build system

CMake is now the only supported build system for Mbed TLS. Support for the legacy GNU Make and Microsoft Visual Studio project-based build systems has been removed.

The GNU Make build system is still used internally for testing, but it will be removed once all test components have been migrated to CMake. The previous .sln/.vcxproj files are no longer distributed or generated.

Builds must now be configured and executed through CMake. See Compiling section in README.md for initial build instructions. 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.

Repository split

In Mbed TLS 4.0, the project was split into two repositories:

• Mbed TLS: provides TLS and X.509 functionality.
• TF-PSA-Crypto: provides the standalone cryptography library, implementing the PSA Cryptography API. Mbed TLS consumes TF-PSA-Crypto as a submodule. You should stay with Mbed TLS if you use TLS or X.509 functionality. You still have direct access to the PSA Cryptography API through the tf-psa-crypto submodule.

File and directory relocations

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/	All PSA headers consolidated here.
3rdparty/everest/ 3rdparty/p256-m/	tf-psa-crypto/drivers/	Third-party crypto driver implementations.

If you use your own build system to build Mbed TLS libraries, you will need to adapt to the new tree.

Configuration file split

Cryptography and platform configuration options have been moved from mbedtls_config.h to crypto_config.h, which is now mandatory. See Compile-time configuration.

Impact on some usages of the library

Checking out a branch or a tag

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

Linking directly to a built library

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.

Linking through a CMake target of the cryptography library

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_subproject
• programs/test/cmake_package
• programs/test/cmake_package_install.

Using Mbed TLS Crypto pkg-config file

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.

Audience-Specific Notes

Application Developers using a distribution package

You should stay with Mbed TLS if you use TLS or X.509 functionality.

• See Impact on usages of the library for the possible impacts on:
  • Linking against the cryptography library or CMake targets.
  • Use the updated pkg-config files (mbedcrypto.pc / tfpsacrypto.pc).

Developer or package maintainers

If you build or distribute Mbed TLS:

• The build system is now CMake only, Makefiles and Visual Studio projects are removed.
• You may need to adapt packaging scripts to handle the TF-PSA-Crypto submodule.
• You should update submodules recursively after checkout.
• Review File and directory relocations for updated paths.
• See Impact on usages of the library for the possible impacts on:
  • Linking against the cryptography library or CMake targets.
  • Use the updated pkg-config files (mbedcrypto.pc / tfpsacrypto.pc).
• Configuration note: cryptography and platform options are now in crypto_config.h (see Configuration file split).

Platform Integrators

If you integrate Mbed TLS with a platform or hardware drivers:

• TF-PSA-Crypto is now a submodule, update integration scripts to initialize submodules recursively.
• The PSA driver wrapper is now generated in TF-PSA-Crypto.
• Platform-specific configuration are now handled in crypto_config.h.
• See Repository split for how platform components moved to TF-PSA-Crypto.