Skip to content

Commit 5394731

Browse files
gilles-peskine-armgilles-peskine-arm
authored
Merge pull request #10441 from ronald-cron-arm/migration-guide
Add repo-split migration guide
2 parents 2f13c8c + 7c39b60 commit 5394731

File tree

1 file changed

+200
-0
lines changed

1 file changed

+200
-0
lines changed

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

Lines changed: 200 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,200 @@
1+
## CMake as the only build system
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.
4+
5+
The previous `.sln` and `.vcxproj` files are no longer distributed or generated.
6+
7+
See the `Compiling` section in README.md for instructions on building the Mbed TLS libraries and tests with CMake.
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+
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 currently no equivalent for `make uninstall` in the Mbed TLS CMake build system.
45+
46+
#### Common build options
47+
48+
The following table illustrates the approximate CMake equivalents of common make commands.
49+
Most CMake examples show only the configuration step, others (like installation) correspond to different stages of the build process.
50+
51+
| Make usage | CMake usage | Description |
52+
|----------------------------|-------------------------------------------------------|----------------------|
53+
| `make DEBUG=1` | `cmake -S . -B build -DCMAKE_BUILD_TYPE=Debug` | Build in debug mode. |
54+
| `make SHARED=1` | `cmake -S . -B build -DUSE_SHARED_MBEDTLS_LIBRARY=On` | Also build shared libraries. |
55+
| `make GEN_FILES=""` | `cmake -S . -B build -DGEN_FILES=OFF` | Skip generating files (not a strict equivalent). |
56+
| `make DESTDIR=install_dir` | `cmake --install build --prefix install_dir` | Specify installation path. |
57+
| `make CC=clang` | `cmake -S . -B build -DCMAKE_C_COMPILER=clang` | Set the compiler. |
58+
| `make CFLAGS='-O2 -Wall'` | `cmake -S . -B build -DCMAKE_C_FLAGS="-O2 -Wall"` | Set compiler flags. |
59+
60+
## Repository split
61+
In Mbed TLS 4.0, the project was split into two repositories:
62+
- [Mbed TLS](https://github.com/Mbed-TLS/mbedtls): provides TLS and X.509 functionality.
63+
- [TF-PSA-Crypto](https://github.com/Mbed-TLS/TF-PSA-Crypto): provides the standalone cryptography library, implementing the PSA Cryptography API.
64+
Mbed TLS consumes TF-PSA-Crypto as a submodule.
65+
You should stay with Mbed TLS if you use TLS or X.509 functionality. You still have direct access to the cryptography library.
66+
67+
### File and directory relocations
68+
69+
The following table summarizes the file and directory relocations resulting from the repository split between Mbed TLS and TF-PSA-Crypto.
70+
These changes reflect the move of cryptographic, cryptographic-adjacent, and platform components from Mbed TLS into the new TF-PSA-Crypto repository.
71+
72+
| Original location | New location(s) | Notes |
73+
|-----------------------------------------|--------------------------------------------------------------------------------------|-------|
74+
| `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. |
75+
| `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`. |
76+
| `include/psa` | `tf-psa-crypto/include/psa` | All PSA headers consolidated here. |
77+
| `3rdparty/everest`<br>`3rdparty/p256-m` | `tf-psa-crypto/drivers/everest`<br>`tf-psa-crypto/drivers/p256-m` | Third-party crypto driver implementations. |
78+
79+
(<sup>†</sup>) The `library` and `include/mbedtls` directories still exist in Mbed TLS, but now contain only TLS and X.509 components.
80+
81+
### Configuration file split
82+
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.
83+
See [Compile-time configuration](#compile-time-configuration).
84+
85+
The header `include/mbedtls/mbedtls_config.h` still exists and now contains only the TLS and X.509 configuration options.
86+
87+
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.
88+
89+
There have been significant changes in the configuration options, primarily affecting cryptography.
90+
91+
#### Cryptography configuration
92+
- See [psa-transition.md](https://github.com/Mbed-TLS/TF-PSA-Crypto/blob/development/docs/psa-transition.md#compile-time-configuration).
93+
- See also the following sections in the TF-PSA-Crypto 1.0 migration guide:
94+
- *PSA as the Only Cryptography API* and its sub-section *Impact on the Library Configuration*
95+
- *Random Number Generation Configuration*
96+
97+
#### TLS configuration
98+
For details about TLS-related changes, see [Changes to TLS options](#changes-to-tls-options).
99+
100+
### Impact on some usages of the library
101+
102+
#### Checking out a branch or a tag
103+
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:
104+
```
105+
git submodule update --init --recursive
106+
```
107+
108+
#### Linking directly to a built library
109+
110+
The Mbed TLS CMake build system still provides the cryptography libraries under their legacy name, `libmbedcrypto.<ext>`, so you can continue linking against them.
111+
These libraries are still located in the `library` directory within the build tree.
112+
113+
The cryptography libraries are also now provided as `libtfpsacrypto.<ext>`, consistent with the naming used in the TF-PSA-Crypto repository.
114+
115+
You may need to update include paths to the public header files, see [File and Directory Relocations](#file-and-directory-relocations) for details.
116+
117+
#### Using Mbed TLS as a CMake subproject
118+
119+
The base name of the libraries are now `tfpsacrypto` (formely `mbedcrypto`), `mbedx509` and `mbedtls`.
120+
As before, these base names are also the names of CMake targets to build each library.
121+
If your CMake scripts reference a cryptography library target, you need to update its name accordingly.
122+
123+
For example, the following CMake code:
124+
```
125+
target_link_libraries(mytarget PRIVATE mbedcrypto)
126+
```
127+
should be updated to:
128+
```
129+
target_link_libraries(mytarget PRIVATE tfpsacrypto)
130+
```
131+
132+
You can refer to the following example demonstrating how to consume Mbed TLS as a CMake subproject:
133+
- `programs/test/cmake_subproject`
134+
135+
#### Using Mbed TLS as a CMake package
136+
137+
The same renaming applies to the cryptography library targets declared as part of the Mbed TLS CMake package, use `MbedTLS::tfpsacrypto` instead of `MbedTLS::mbedcrypto`.
138+
139+
For example, the following CMake code:
140+
```
141+
find_package(MbedTLS REQUIRED)
142+
target_link_libraries(myapp PRIVATE MbedTLS::mbedcrypto)
143+
```
144+
should be updated to:
145+
```
146+
find_package(MbedTLS REQUIRED)
147+
target_link_libraries(myapp PRIVATE MbedTLS::tfpsacrypto)
148+
```
149+
You can also refer to the following example programs demonstrating how to consume Mbed TLS as a CMake package:
150+
- `programs/test/cmake_package`
151+
- `programs/test/cmake_package_install`
152+
153+
#### Using the Mbed TLS Crypto pkg-config file
154+
155+
The Mbed TLS CMake build system still provides the pkg-config file mbedcrypto.pc, so you can continue using it.
156+
Internally, it now references the tfpsacrypto library.
157+
158+
A new pkg-config file, `tfpsacrypto.pc`, is also provided.
159+
Both `mbedcrypto.pc` and `tfpsacrypto.pc` are functionally equivalent, providing the same compiler and linker flags.
160+
161+
#### Using Mbed TLS as an installed library
162+
163+
The Mbed TLS CMake build system still installs the cryptography libraries under their legacy name, `libmbedcrypto.<ext>`, so you can continue linking against them.
164+
The cryptography library is also now provided as `libtfpsacrypto.<ext>`.
165+
166+
Regarding the headers, the main change is the relocation of some headers to subdirectories called `private`.
167+
These headers are installed primarily to satisfy compiler dependencies.
168+
Others remain for historical reasons and may be cleaned up in later versions of the library.
169+
170+
We strongly recommend not relying on the declarations in these headers, as they may be removed or modified without notice.
171+
See the section Private Declarations in the TF-PSA-Crypto 1.0 migration guide for more information.
172+
173+
Finally, note the new `include/tf-psa-crypto` directory, which contains the TF-PSA-Crypto version and build-time configuration headers.
174+
175+
### Audience-Specific Notes
176+
177+
#### Application Developers using a distribution package
178+
- See [Impact on usages of the library](#impact-on-some-usages-of-the-library) for the possible impacts on:
179+
- Linking against the cryptography library or CMake targets.
180+
- Using the Mbed TLS Crypto pkg-config file.
181+
- Using Mbed TLS as an installed library
182+
183+
### Developer or package maintainers
184+
If you build or distribute Mbed TLS:
185+
- The build system is now CMake only, Makefiles and Visual Studio projects are removed.
186+
- You may need to adapt packaging scripts to handle the TF-PSA-Crypto submodule.
187+
- You should update submodules recursively after checkout.
188+
- Review [File and directory relocations](#file-and-directory-relocations) for updated paths.
189+
- See [Impact on usages of the library](#impact-on-some-usages-of-the-library) for the possible impacts on:
190+
- Linking against the cryptography library or CMake targets.
191+
- Using the Mbed TLS Crypto pkg-config file (`mbedcrypto.pc` or `tfpsacrypto.pc`).
192+
- Using Mbed TLS as an installed library
193+
- Configuration note: cryptography and platform options are now in `crypto_config.h` (see [Configuration file split](#configuration-file-split)).
194+
195+
### Platform Integrators
196+
If you integrate Mbed TLS with a platform or hardware drivers:
197+
- TF-PSA-Crypto is now a submodule, update integration scripts to initialize submodules recursively.
198+
- The PSA driver wrapper is now generated in TF-PSA-Crypto.
199+
- Platform-specific configuration are now handled in `crypto_config.h`.
200+
- See [Repository split](#repository-split) for how platform components moved to TF-PSA-Crypto.

0 commit comments

Comments
 (0)