Add repo-split migration guide #511

2025-10-09T13:36:51-05:00

ronald-cron-arm commented

2025-10-09 13:36:51 -05:00

(Migrated from github.com)

Description

Fixes https://github.com/Mbed-TLS/mbedtls/issues/10248

PR checklist

changelog not required because: new documentation
framework PR not required
mbedtls development PR provided Mbed-TLS/mbedtls#10441
mbedtls 3.6 PR not required because: 4.0 only documentation
tests not required because: documentation only PR

## Description Fixes https://github.com/Mbed-TLS/mbedtls/issues/10248 ## PR checklist - [x] **changelog** not required because: new documentation - [x] **framework PR** not required - [x] **mbedtls development PR** provided Mbed-TLS/mbedtls#10441 - [x] **mbedtls 3.6 PR** not required because: 4.0 only documentation - **tests** not required because: documentation only PR

gilles-peskine-arm (Migrated from github.com) requested changes

2025-10-09 15:07:02 -05:00

gilles-peskine-arm (Migrated from github.com) left a comment

LGTM except that a couple of things are different in TF-PSA-Crypto.

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

					
				@ -0,0 +1,172 @@

				## CMake as the only build system

There's no lib target. (I've already grumbled about that.)

| `make lib`      | `cmake --build build --target tfpsacrypto`                          | Build only the library. |

There's no `lib` target. (I've already grumbled about that.) ```suggestion | `make lib` | `cmake --build build --target tfpsacrypto` | Build only the library. | ```

| `make programs` | `cmake --build build --target tfpsacrypto-programs`                 | Build example programs. |

```suggestion | `make programs` | `cmake --build build --target tfpsacrypto-programs` | Build example programs. | ```

If you use only the cryptography part, you should consider migrating to TF-PSA-Crypto.

```suggestion If you use only the cryptography part, you should consider migrating to TF-PSA-Crypto. ```

I already mentioned this in mbedtls, and it's more important to be accurate here: not just the PSA Cryptography API, there are a few extensions. These extensions are available in TF-PSA-Crypto even though most of them have function names that begin with mbedtls_, so it's especially important to be clear that the distinction is crypto vs the rest, not PSA vs the rest.

Suggested wording:

provides the standalone cryptography library, notably including the PSA Cryptography API.

I already mentioned this in mbedtls, and it's more important to be accurate here: not just the PSA Cryptography API, there are a few extensions. These extensions are available in TF-PSA-Crypto even though most of them have function names that begin with `mbedtls_`, so it's especially important to be clear that the distinction is crypto vs the rest, not PSA vs the rest. Suggested wording: > provides the standalone cryptography library, notably including the PSA Cryptography API.

The run-on sentence makes it look like there's a build system with three parts, and then the words “are not supported” breaks the grammar.

- The build system is CMake. Makefiles and Visual Studio projects are not supported.

The run-on sentence makes it look like there's a build system with three parts, and then the words “are not supported” breaks the grammar. ```suggestion - The build system is CMake. Makefiles and Visual Studio projects are not supported. ```

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

					
				@ -0,0 +155,4 @@

				  - Using the TF-PSA-Crypto pkg-config file.

				  - Using TF-PSA-Crypto as an installed library.

				### Developer or package maintainers

Here, an important note is that if you want to provide both crypto and X.509(+TLS), you need to package Mbed TLS and its bundled TF-PSA-Crypto. You can't have both Mbed TLS and the standalone TF-PSA-Crypto.

ronald-cron-arm (Migrated from github.com) reviewed

2025-10-10 02:22:45 -05:00

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

					
				@ -0,0 +155,4 @@

				  - Using the TF-PSA-Crypto pkg-config file.

				  - Using TF-PSA-Crypto as an installed library.

				### Developer or package maintainers

I've added a new point but I do not really understand what you want to convey here thus I am not sure about it.

gilles-peskine-arm (Migrated from github.com) approved these changes

2025-10-10 03:17:40 -05:00

gilles-peskine-arm (Migrated from github.com) left a comment

LGTM

gilles-peskine-arm (Migrated from github.com) reviewed

2025-10-10 03:19:38 -05:00

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

					
				@ -0,0 +155,4 @@

				  - Using the TF-PSA-Crypto pkg-config file.

				  - Using TF-PSA-Crypto as an installed library.

				### Developer or package maintainers

TF-PSA-Crypto and Mbed TLS now appear to be separate products. If a distribution means to include both, the natural expectation is to first configure and build TF-PSA-Crypto, then configure and build Mbed TLS against the TF-PSA-Crypto that was previously built. But we don't offer a way to do that. Instead, to provide both TF-PSA-Crypto and Mbed TLS, you need to configure and build Mbed TLS, and ship the TF-PSA-Crypto that it bundles.

davidhorstmann-arm (Migrated from github.com) approved these changes

2025-10-10 04:07:22 -05:00

davidhorstmann-arm (Migrated from github.com) left a comment

LGTM, I found some small nits but they are not a blocker on their own.

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

					
				@ -0,0 +95,4 @@

				#### Using TF-PSA-Crypto as a CMake subproject

				The base name of the static and shared cryptography libraries is now `tfpsacrypto`, formerly `mbedcrypto`.

				As before, this base name is also the base name of CMake targets to build the libraries.

Non-blocker nit: Pluralisation and "formely" -> "formerly"

The TF-PSA-Crypto CMake build system provides the cryptography library under the name, `libtfpsacrypto.<ext>` in the `core` directory.
Thus both the name of the library and its location have changed compared to Mbed TLS.
You may also need to update include paths to the public header files, see [File and Directory Relocations](#file-and-directory-relocations) for details.

#### Using TF-PSA-Crypto as a CMake subproject

The base name of the static and shared cryptography library is now `tfpsacrypto`, formerly `mbedcrypto`.
As before, this base name is also the base name of CMake targets to build the library.

Non-blocker nit: Pluralisation and "formely" -> "formerly" ```suggestion The TF-PSA-Crypto CMake build system provides the cryptography library under the name, `libtfpsacrypto.<ext>` in the `core` directory. Thus both the name of the library and its location have changed compared to Mbed TLS. You may also need to update include paths to the public header files, see [File and Directory Relocations](#file-and-directory-relocations) for details. #### Using TF-PSA-Crypto as a CMake subproject The base name of the static and shared cryptography library is now `tfpsacrypto`, formerly `mbedcrypto`. As before, this base name is also the base name of CMake targets to build the library. ```

ronald-cron-arm (Migrated from github.com) reviewed

2025-10-10 04:19:29 -05:00

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

					
				@ -0,0 +95,4 @@

				#### Using TF-PSA-Crypto as a CMake subproject

				The base name of the static and shared cryptography libraries is now `tfpsacrypto`, formerly `mbedcrypto`.

				As before, this base name is also the base name of CMake targets to build the libraries.

I've used the plural because we build potentially two libraries: the static and the shared one. I've kept that. I've fixed "formely".

gilles-peskine-arm (Migrated from github.com) approved these changes

2025-10-10 04:23:58 -05:00

gilles-peskine-arm (Migrated from github.com) left a comment

LGTM

davidhorstmann-arm (Migrated from github.com) approved these changes

2025-10-10 06:06:13 -05:00

davidhorstmann-arm (Migrated from github.com) left a comment

LGTM, thanks!

Sign in to join this conversation.

No reviewers

gilles-peskine-arm

davidhorstmann-arm

No milestone

No assignees

1 participant

Notifications

Due date

The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set

Reference

gh-Mbed-TLS/TF-PSA-Crypto!511

Rows
Columns