Add std-only examples and polish doc for main
#144
There are no files selected for viewing
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -30,3 +30,4 @@ header: | |
| - 'KEYS' | ||
| - 'DISCLAIMER-WIP' | ||
| - '*.json' | ||
| - 'examples/tls_server-rs/ta/test-ca/**' | ||
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,57 @@ | ||
| --- | ||
| permalink: /trustzone-sdk-docs/migrating-to-new-building-env.md | ||
| --- | ||
|
|
||
| ## Migration Guide: Moving from `master` to `main` Branch (Post-Oct 2024) | ||
|
|
||
| Since the `main` branch (after October 2024) introduces breaking changes | ||
| to the build environment, if users of the legacy `master` branch want to | ||
| keep upstream or use a new version of the Rust toolchain, they will need | ||
| to follow these steps to migrate their TA to the new environment. | ||
|
|
||
| ### Step 1: Migrate Old Code to the New Environment | ||
|
|
||
| To migrate an example project (e.g., `tls_server-rs` in `examples/`), you | ||
| can refer to the following shell script and adjust it for your TA: | ||
|
|
||
| ```bash | ||
| TARGET_EXAMPLE="tls_server-rs" | ||
| OLD_ROOT_PATH="/path/to/old/sdk" | ||
| NEW_PATH="/path/to/current/sdk" | ||
|
|
||
| # Duplicate the hello-world example in the new path as a template | ||
| cp -r ${NEW_PATH}/examples/hello_world-rs ${NEW_PATH}/examples/${TARGET_EXAMPLE} | ||
|
|
||
| # Remove the source code directory and copy from the old path to the new path | ||
| # including: src/ and Cargo.toml in host, ta, proto | ||
| (cd ${NEW_PATH}/examples/${TARGET_EXAMPLE}/host && rm -rf src/ Cargo.* && \ | ||
| cp -r ${OLD_ROOT_PATH}/examples/${TARGET_EXAMPLE}/host/src . && \ | ||
| cp ${OLD_ROOT_PATH}/examples/${TARGET_EXAMPLE}/host/Cargo.toml .) | ||
| (cd ${NEW_PATH}/examples/${TARGET_EXAMPLE}/ta && rm -rf src/ Cargo.* && \ | ||
| cp -r ${OLD_ROOT_PATH}/examples/${TARGET_EXAMPLE}/ta/src . && \ | ||
| cp ${OLD_ROOT_PATH}/examples/${TARGET_EXAMPLE}/ta/Cargo.toml .) | ||
| (cd ${NEW_PATH}/examples/${TARGET_EXAMPLE}/proto && rm -rf src/ Cargo.* && \ | ||
| cp -r ${OLD_ROOT_PATH}/examples/${TARGET_EXAMPLE}/proto/src . && \ | ||
| cp ${OLD_ROOT_PATH}/examples/${TARGET_EXAMPLE}/proto/Cargo.toml .) | ||
|
|
||
| # Copy the UUID file from the old path to the new path | ||
| cp ${OLD_ROOT_PATH}/examples/${TARGET_EXAMPLE}/uuid.txt \ | ||
| ${NEW_PATH}/examples/${TARGET_EXAMPLE}/uuid.txt | ||
|
|
||
| # Update binary names in host/Cargo.toml and host/Makefile | ||
| sed -i "s/hello_world-rs/${TARGET_EXAMPLE}/g" \ | ||
| ${NEW_PATH}/examples/${TARGET_EXAMPLE}/host/Cargo.toml | ||
| sed -i "s/hello_world-rs/${TARGET_EXAMPLE}/g" \ | ||
| ${NEW_PATH}/examples/${TARGET_EXAMPLE}/host/Makefile | ||
| ``` | ||
|
|
||
| ### Step 2: Update `Cargo.toml` | ||
|
|
||
| You may need to update your `Cargo.toml` to use newer versions of crates. | ||
| The Rust toolchain for the current build environment can be found in | ||
| `rust-toolchain.toml`. | ||
|
|
||
| ### Step 3: Build and Fix Errors | ||
|
|
||
| After updating, run the build process. Some errors might occur due to the | ||
| crate version upgrades—fix them as necessary. | ||
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,33 @@ | ||
| # Licensed to the Apache Software Foundation (ASF) under one | ||
| # or more contributor license agreements. See the NOTICE file | ||
| # distributed with this work for additional information | ||
| # regarding copyright ownership. The ASF licenses this file | ||
| # to you under the Apache License, Version 2.0 (the | ||
| # "License"); you may not use this file except in compliance | ||
| # with the License. You may obtain a copy of the License at | ||
| # | ||
| # http://www.apache.org/licenses/LICENSE-2.0 | ||
| # | ||
| # Unless required by applicable law or agreed to in writing, | ||
| # software distributed under the License is distributed on an | ||
| # "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY | ||
| # KIND, either express or implied. See the License for the | ||
| # specific language governing permissions and limitations | ||
| # under the License. | ||
|
|
||
| # If _HOST or _TA specific compiler/target are not specified, then use common | ||
| # compiler/target for both | ||
| CROSS_COMPILE_HOST ?= aarch64-linux-gnu- | ||
| CROSS_COMPILE_TA ?= aarch64-linux-gnu- | ||
| TARGET_HOST ?= aarch64-unknown-linux-gnu | ||
| TARGET_TA ?= aarch64-unknown-linux-gnu | ||
|
|
||
| all: | ||
| $(q)make -C host TARGET_HOST=$(TARGET_HOST) \ | ||
| CROSS_COMPILE_HOST=$(CROSS_COMPILE_HOST) | ||
| $(q)make -C ta TARGET_TA=$(TARGET_TA) \ | ||
| CROSS_COMPILE_TA=$(CROSS_COMPILE_TA) | ||
|
|
||
|
There was a problem hiding this comment. I see that at the top level, TARGET_HOST and TARGET_TA are used to differentiate between the build parameters for the host and trusted application (TA), which makes sense. However, at the sub-level (host/Makefile and ta/Makefile), it may be unnecessary to keep differentiating these parameters. The sub-level Makefiles could rely on the variables passed down from the top-level Makefile and use more generic variable names, such as TARGET and CROSS_COMPILE, similar as the Instead of maintaining the separate TARGET_HOST and TARGET_TA at each level, we could streamline the build process by using: There was a problem hiding this comment.
That makes sense because the Currently, the If changed to this:
The There was a problem hiding this comment.
|
||
| clean: | ||
| $(q)make -C host clean | ||
m4sterchain marked this conversation as resolved.
Show resolved
Hide resolved
|
||
| $(q)make -C ta clean | ||
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,33 @@ | ||
| # Licensed to the Apache Software Foundation (ASF) under one | ||
| # or more contributor license agreements. See the NOTICE file | ||
| # distributed with this work for additional information | ||
| # regarding copyright ownership. The ASF licenses this file | ||
| # to you under the Apache License, Version 2.0 (the | ||
| # "License"); you may not use this file except in compliance | ||
| # with the License. You may obtain a copy of the License at | ||
| # | ||
| # http://www.apache.org/licenses/LICENSE-2.0 | ||
| # | ||
| # Unless required by applicable law or agreed to in writing, | ||
| # software distributed under the License is distributed on an | ||
| # "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY | ||
| # KIND, either express or implied. See the License for the | ||
| # specific language governing permissions and limitations | ||
| # under the License. | ||
|
|
||
| [package] | ||
| name = "message_passing_interface-rs" | ||
| version = "0.3.0" | ||
| authors = ["Teaclave Contributors <[email protected]>"] | ||
| license = "Apache-2.0" | ||
| repository = "https://github.com/apache/incubator-teaclave-trustzone-sdk.git" | ||
| description = "An example of Rust OP-TEE TrustZone SDK." | ||
| edition = "2018" | ||
|
|
||
| [dependencies] | ||
| url = "2.5.0" | ||
| proto = { path = "../proto" } | ||
| optee-teec = { path = "../../../optee-teec" } | ||
|
|
||
| [profile.release] | ||
| lto = true |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
The current migration strategy seems to ask developers to duplicate the hello-world example and manually copy their source code into the corresponding subdirectories. However, this approach doesn't clearly highlight what has actually changed and what developers need to focus on during the migration.
The target audience for this section is developers currently using the master branch who have their own code repositories. The key point we need to emphasize is that no code changes are required during the migration—only the build scripts need to be updated.
The message we want to convey is simple: developers should be aware that the build process has changed compared to the legacy master branch, and the build scripts will need to be replaced. Could we clearly outline the differences in the build scripts (e.g. Cargo.toml, build.rs, Makefile, etc), step-by-step, and perhaps reference a specific commit for further clarification? This way, developers can focus on adapting their build environment without being concerned about unnecessary code modifications.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
IMHO, we should rather be describing the build environment for the
mainbranch as to how it's structured. This will help developers writing new TAs or updating existing TAs to the build environment onmainbranch.A few words for each file under following directory structure should be sufficient:
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Doc updated, thanks for all comments