Ronald Cron | 9228e4a | 2025-10-05 16:25:43 +0200 | [diff] [blame] | 1 | ## CMake as the only build system |
Ronald Cron | a5e1b6d | 2025-10-08 09:10:54 +0200 | [diff] [blame] | 2 | Mbed TLS now uses CMake exclusively to configure and drive its build process. |
| 3 | Support for the GNU Make and Microsoft Visual Studio project-based build systems has been removed. |
Ronald Cron | 9228e4a | 2025-10-05 16:25:43 +0200 | [diff] [blame] | 4 | |
Ronald Cron | a5e1b6d | 2025-10-08 09:10:54 +0200 | [diff] [blame] | 5 | The previous `.sln` and `.vcxproj` files are no longer distributed or generated. |
Ronald Cron | 9228e4a | 2025-10-05 16:25:43 +0200 | [diff] [blame] | 6 | |
Ronald Cron | a5e1b6d | 2025-10-08 09:10:54 +0200 | [diff] [blame] | 7 | See the `Compiling` section in README.md for instructions on building the Mbed TLS libraries and tests with CMake. |
Ronald Cron | 9228e4a | 2025-10-05 16:25:43 +0200 | [diff] [blame] | 8 | 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. |
| 9 | |
Ronald Cron | 5d069c9 | 2025-10-08 12:08:55 +0200 | [diff] [blame] | 10 | ### Translating Make commands to CMake |
| 11 | |
| 12 | With the removal of GNU Make support, all build, test, and installation operations must now be performed using CMake. |
| 13 | This section provides a quick reference for translating common `make` commands into their CMake equivalents. |
| 14 | |
| 15 | #### Basic build workflow |
| 16 | |
| 17 | Run `cmake -S . -B build` once before building to configure the build and generate native build files (e.g., Makefiles) in the `build` directory. |
| 18 | This sets up an out-of-tree build, which is recommended. |
| 19 | |
| 20 | | Make command | CMake equivalent | Description | |
| 21 | |----------------|------------------------------------------------|--------------------------------------------------------------------| |
| 22 | | `make` | `cmake --build build` | Build the libraries, programs, and tests in the `build` directory. | |
| 23 | | `make test` | `ctest --test-dir build` | Run the tests produced by the previous build. | |
| 24 | | `make clean` | `cmake --build build --target clean` | Remove build artifacts produced by the previous build. | |
| 25 | | `make install` | `cmake --install build --prefix build/install` | Install the built libraries, headers, and tests to `build/install`. | |
| 26 | |
| 27 | #### Building specific targets |
| 28 | |
| 29 | 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. |
| 30 | |
| 31 | | Make command | CMake equivalent | Description | |
| 32 | |-----------------|---------------------------------------------------------------------|---------------------------| |
| 33 | | `make lib` | `cmake --build build --target lib` | Build only the libraries. | |
| 34 | | `make tests` | `cmake -S . -B build -DENABLE_PROGRAMS=Off && cmake --build build` | Build test suites. | |
| 35 | | `make programs` | `cmake --build build --target programs` | Build example programs. | |
| 36 | | `make apidoc` | `cmake --build build --target mbedtls-apidoc` | Build documentation. | |
| 37 | |
| 38 | Target names may differ slightly; use `cmake --build build --target help` to list all available CMake targets. |
| 39 | |
| 40 | There is no CMake equivalent for `make generated_files` or `make neat`. |
| 41 | Generated files are automatically created in the build tree with `cmake --build build` and removed with `cmake --build build --target clean`. |
| 42 | If you need to build the generated files in the source tree without involving CMake, you can call `framework/scripts/make_generated_files.py`. |
| 43 | |
| 44 | There is no CMake equivalent for `make uninstall`. |
| 45 | To remove an installation, simply delete the directory specified as the installation prefix. |
| 46 | |
| 47 | #### Common build options |
| 48 | |
| 49 | | Make usage | CMake usage | Description | |
| 50 | |----------------------------|-------------------------------------------------------|----------------------| |
| 51 | | `make DEBUG=1` | `cmake -S . -B build -DCMAKE_BUILD_TYPE=Debug` | Build in debug mode. | |
| 52 | | `make SHARED=1` | `cmake -S . -B build -DUSE_SHARED_MBEDTLS_LIBRARY=On` | Also build shared libraries. | |
| 53 | | `make GEN_FILES=""` | `cmake -S . -B build -DGEN_FILES=OFF` | Skip generating files (not a strict equivalent). | |
| 54 | | `make DESTDIR=install_dir` | `cmake --install build --prefix install_dir` | Specify installation path. | |
| 55 | | `make CC=clang` | `cmake -S . -B build -DCMAKE_C_COMPILER=clang` | Set the compiler. | |
| 56 | | `make CFLAGS='-O2 -Wall'` | `cmake -S . -B build -DCMAKE_C_FLAGS="-O2 -Wall"` | Set compiler flags. | |
| 57 | |
Ronald Cron | 9228e4a | 2025-10-05 16:25:43 +0200 | [diff] [blame] | 58 | ## Repository split |
| 59 | In Mbed TLS 4.0, the project was split into two repositories: |
| 60 | - [Mbed TLS](https://github.com/Mbed-TLS/mbedtls): provides TLS and X.509 functionality. |
| 61 | - [TF-PSA-Crypto](https://github.com/Mbed-TLS/TF-PSA-Crypto): provides the standalone cryptography library, implementing the PSA Cryptography API. |
| 62 | Mbed TLS consumes TF-PSA-Crypto as a submodule. |
Ronald Cron | c764624 | 2025-10-08 09:59:01 +0200 | [diff] [blame] | 63 | You should stay with Mbed TLS if you use TLS or X.509 functionality. You still have direct access to the cryptography library. |
Ronald Cron | 9228e4a | 2025-10-05 16:25:43 +0200 | [diff] [blame] | 64 | |
| 65 | ### File and directory relocations |
| 66 | |
| 67 | The following table summarizes the file and directory relocations resulting from the repository split between Mbed TLS and TF-PSA-Crypto. |
| 68 | These changes reflect the move of cryptographic, cryptographic-adjacent, and platform components from Mbed TLS into the new TF-PSA-Crypto repository. |
| 69 | |
Ronald Cron | d3f02cd | 2025-10-08 09:52:59 +0200 | [diff] [blame] | 70 | | Original location | New location(s) | Notes | |
| 71 | |-----------------------------------------|--------------------------------------------------------------------------------------|-------| |
Ronald Cron | de8bb96 | 2025-10-09 10:45:36 +0200 | [diff] [blame^] | 72 | | `library/*` (<sup>†</sup>) | `tf-psa-crypto/core/`<br>`tf-psa-crypto/drivers/builtin/src/` | Contains cryptographic, cryptographic-adjacent (e.g., ASN.1, Base64), and platform C modules and headers. | |
| 73 | | `include/mbedtls/*` (<sup>†</sup>) | `tf-psa-crypto/include/mbedtls/`<br>`tf-psa-crypto/drivers/builtin/include/private/` | Public headers moved to `include/mbedtls`; now internal headers moved to `include/private`. | |
Ronald Cron | d3f02cd | 2025-10-08 09:52:59 +0200 | [diff] [blame] | 74 | | `include/psa` | `tf-psa-crypto/include/psa` | All PSA headers consolidated here. | |
| 75 | | `3rdparty/everest`<br>`3rdparty/p256-m` | `tf-psa-crypto/drivers/everest`<br>`tf-psa-crypto/drivers/p256-m` | Third-party crypto driver implementations. | |
Ronald Cron | 9228e4a | 2025-10-05 16:25:43 +0200 | [diff] [blame] | 76 | |
Ronald Cron | de8bb96 | 2025-10-09 10:45:36 +0200 | [diff] [blame^] | 77 | (<sup>†</sup>) The `library` and `include/mbedtls` directories still exist in Mbed TLS, but not contain only TLS and X.509 components. |
Ronald Cron | 9228e4a | 2025-10-05 16:25:43 +0200 | [diff] [blame] | 78 | |
| 79 | ### Configuration file split |
Ronald Cron | 79a2631 | 2025-10-08 11:29:52 +0200 | [diff] [blame] | 80 | 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. |
| 81 | See [Compile-time configuration](#compile-time-configuration). |
| 82 | |
| 83 | The header `include/mbedtls/mbedtls_config.h` still exists and now contains only the TLS and X.509 configuration options. |
| 84 | |
| 85 | 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. |
| 86 | |
| 87 | There has been significant changes in the configuration options, primarily affecting cryptography. |
| 88 | |
| 89 | #### Cryptography configuration |
| 90 | - See [psa-transition.md](https://github.com/Mbed-TLS/TF-PSA-Crypto/blob/development/docs/psa-transition.md#compile-time-configuration). |
| 91 | - See also the following sections in the TF-PSA-Crypto 1.0 migration guide: |
| 92 | - *PSA as the Only Cryptography API* and its sub-section *Impact on the Library Configuration* |
| 93 | - *Random Number Generation Configuration* |
| 94 | |
| 95 | #### TLS configuration |
| 96 | For details about TLS-related changes, see [Changes to TLS options](#changes-to-tls-options). |
Ronald Cron | 9228e4a | 2025-10-05 16:25:43 +0200 | [diff] [blame] | 97 | |
| 98 | ### Impact on some usages of the library |
| 99 | |
| 100 | #### Checking out a branch or a tag |
| 101 | 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: |
| 102 | ``` |
| 103 | git submodule update --init --recursive |
| 104 | ``` |
| 105 | |
| 106 | #### Linking directly to a built library |
Ronald Cron | 9228e4a | 2025-10-05 16:25:43 +0200 | [diff] [blame] | 107 | |
Ronald Cron | 25b1a02 | 2025-10-08 17:15:30 +0200 | [diff] [blame] | 108 | The Mbed TLS CMake build system still provides the cryptography libraries under their legacy name, `libmbedcrypto.<ext>`, so you can continue linking against them. |
| 109 | These libraries are still located in the `library` directory within the build tree. |
| 110 | |
| 111 | The cryptography libraries are also now provided as `libtfpsacrypto.<ext>`, consistent with the naming used in the TF-PSA-Crypto repository. |
| 112 | |
| 113 | You may need to update include paths to the public header files, see [File and Directory Relocations](#file-and-directory-relocations) for details. |
| 114 | |
| 115 | #### Using Mbed TLS as a CMake subproject |
| 116 | |
Ronald Cron | 9228e4a | 2025-10-05 16:25:43 +0200 | [diff] [blame] | 117 | The base name of the CMake cryptography library target has been changed from `mbedcrypto` to `tfpsacrypto`. |
Ronald Cron | 25b1a02 | 2025-10-08 17:15:30 +0200 | [diff] [blame] | 118 | If no target prefix is specified through the `MBEDTLS_TARGET_PREFIX` option, the associated CMake target is now `tfpsacrypto`, and you will need to update it in your CMake scripts. |
| 119 | |
| 120 | You can refer to the following example demonstrating how to consume Mbed TLS as a CMake subproject: |
| 121 | - `programs/test/cmake_subproject` |
| 122 | |
| 123 | #### Using Mbed TLS as a CMake package |
Ronald Cron | 9228e4a | 2025-10-05 16:25:43 +0200 | [diff] [blame] | 124 | |
| 125 | The same renaming applies to the cryptography library targets declared as part of the Mbed TLS CMake package. |
| 126 | When no global target prefix is defined, use `MbedTLS::tfpsacrypto` instead of `MbedTLS::mbedcrypto`. |
| 127 | |
Ronald Cron | 25b1a02 | 2025-10-08 17:15:30 +0200 | [diff] [blame] | 128 | For example, the following CMake code: |
Ronald Cron | 9228e4a | 2025-10-05 16:25:43 +0200 | [diff] [blame] | 129 | ``` |
| 130 | find_package(MbedTLS REQUIRED) |
| 131 | target_link_libraries(myapp PRIVATE MbedTLS::mbedtls MbedTLS::mbedx509 MbedTLS::mbedcrypto) |
Ronald Cron | 9228e4a | 2025-10-05 16:25:43 +0200 | [diff] [blame] | 132 | ``` |
Ronald Cron | 25b1a02 | 2025-10-08 17:15:30 +0200 | [diff] [blame] | 133 | should be updated to: |
Ronald Cron | 9228e4a | 2025-10-05 16:25:43 +0200 | [diff] [blame] | 134 | ``` |
| 135 | find_package(MbedTLS REQUIRED) |
| 136 | target_link_libraries(myapp PRIVATE MbedTLS::mbedtls MbedTLS::mbedx509 MbedTLS::tfpsacrypto) |
| 137 | ``` |
Ronald Cron | 25b1a02 | 2025-10-08 17:15:30 +0200 | [diff] [blame] | 138 | You can also refer to the following example programs demonstrating how to consume Mbed TLS as a CMake package: |
| 139 | - programs/test/cmake_package |
| 140 | - programs/test/cmake_package_install |
Ronald Cron | 9228e4a | 2025-10-05 16:25:43 +0200 | [diff] [blame] | 141 | |
Ronald Cron | 25b1a02 | 2025-10-08 17:15:30 +0200 | [diff] [blame] | 142 | #### Using the Mbed TLS Crypto pkg-config file |
Ronald Cron | 9228e4a | 2025-10-05 16:25:43 +0200 | [diff] [blame] | 143 | |
Ronald Cron | 25b1a02 | 2025-10-08 17:15:30 +0200 | [diff] [blame] | 144 | The Mbed TLS CMake build system still provides the pkg-config file mbedcrypto.pc, so you can continue using it. |
| 145 | Internally, it now references the tfpsacrypto library. |
| 146 | |
| 147 | A new pkg-config file, tfpsacrypto.pc, is also provided. |
| 148 | Both mbedcrypto.pc and tfpsacrypto.pc are functionally equivalent, providing the same compiler and linker flags. |
| 149 | |
| 150 | #### Using Mbed TLS as an installed library |
| 151 | |
| 152 | The Mbed TLS CMake build system still installs the cryptography libraries under their legacy name, `libmbedcrypto.<ext>`, so you can continue linking against them. |
| 153 | The cryptography library is also now provided as `libtfpsacrypto.<ext>`. |
| 154 | |
| 155 | Regarding the headers, the main change is the relocation of some headers to private directories. |
| 156 | These headers are installed primarily to satisfy compiler dependencies. |
| 157 | Others remain for historical reasons and may be cleaned up in later versions of the library. |
| 158 | |
| 159 | We strongly recommend not relying on the declarations in these headers, as they may be removed or modified without notice. |
| 160 | See the section Private Declarations in the TF-PSA-Crypto 1.0 migration guide for more information. |
| 161 | |
| 162 | Finally, note the new include/tf-psa-crypto directory, which contains the TF-PSA-Crypto version and build-time configuration headers. |
Ronald Cron | 9228e4a | 2025-10-05 16:25:43 +0200 | [diff] [blame] | 163 | |
| 164 | ### Audience-Specific Notes |
| 165 | |
| 166 | #### Application Developers using a distribution package |
Ronald Cron | 9228e4a | 2025-10-05 16:25:43 +0200 | [diff] [blame] | 167 | - See [Impact on usages of the library](#impact-on-some-usages-of-the-library) for the possible impacts on: |
| 168 | - Linking against the cryptography library or CMake targets. |
| 169 | - Use the updated `pkg-config` files (`mbedcrypto.pc` / `tfpsacrypto.pc`). |
| 170 | |
| 171 | ### Developer or package maintainers |
| 172 | If you build or distribute Mbed TLS: |
| 173 | - The build system is now CMake only, Makefiles and Visual Studio projects are removed. |
| 174 | - You may need to adapt packaging scripts to handle the TF-PSA-Crypto submodule. |
| 175 | - You should update submodules recursively after checkout. |
| 176 | - Review [File and directory relocations](#file-and-directory-relocations) for updated paths. |
| 177 | - See [Impact on usages of the library](#impact-on-some-usages-of-the-library) for the possible impacts on: |
| 178 | - Linking against the cryptography library or CMake targets. |
| 179 | - Use the updated `pkg-config` files (`mbedcrypto.pc` / `tfpsacrypto.pc`). |
| 180 | - Configuration note: cryptography and platform options are now in `crypto_config.h` (see [Configuration file split](#configuration-file-split)). |
| 181 | |
| 182 | ### Platform Integrators |
| 183 | If you integrate Mbed TLS with a platform or hardware drivers: |
| 184 | - TF-PSA-Crypto is now a submodule, update integration scripts to initialize submodules recursively. |
| 185 | - The PSA driver wrapper is now generated in TF-PSA-Crypto. |
| 186 | - Platform-specific configuration are now handled in `crypto_config.h`. |
| 187 | - See [Repository split](#repository-split) for how platform components moved to TF-PSA-Crypto. |