asir66 opened a new pull request, #263: URL: https://github.com/apache/teaclave-trustzone-sdk/pull/263
# Overview This update is based on PR #245 and focuses on improving the robustness of cargo-optee in several areas, including manifest path resolution, std/no-std argument semantics, and consistency across documentation and CI. Specifically, this PR includes the following changes: 1. Fix issues in cargo-optee related to manifest path resolution, including workspace scenarios 2. Clarify and improve the semantics and parsing logic of `--std` / `--no-std` 3. Normalize JSON file field ordering 4. Update the Quick Start documentation and CI configuration 5. Summarize differences between cargo, cargo-sgx, and cargo-optee based on investigation, and outline potential future directions Related background discussion: https://github.com/apache/teaclave-trustzone-sdk/pull/245#issuecomment-3584945539 # 1. Manifest Path Resolution Fix This issue is fundamentally caused by insufficiently robust manifest path resolution. It manifests differently depending on the project structure: 1. Single-package projects When `--manifest-path Cargo.toml` (without `./`) is explicitly provided, cargo-optee does not correctly handle this edge case when deriving the project path, which may result in failing to locate the project directory. 2. Workspace projects When a relative path containing `./` is used as the manifest path, cargo metadata returns canonicalized manifest paths, while cargo-optee attempts to match them using the original, non-normalized path string. This mismatch causes package discovery to fail. ## Fix and Rationale To address this issue at its root, manifest paths are now canonicalized at the entry point using: ```rust std::fs::canonicalize() ``` This standard library function normalizes paths into absolute form and automatically eliminates: - `./` - `../` # 2. `--std` / `--no-std` Argument Semantics ## Previous Behavior cargo-optee previously used a boolean flag to represent whether std was enabled. When the flag was not explicitly provided, it defaulted to Some(false), which caused cargo-optee to **always fall back to the no-std build mode.** ## Updated Design This update introduces an explicit `--no-std` flag and refactors the argument parsing logic accordingly: - `--std` and `--no-std` are mutually exclusive - If neither is specified, the internal state is set to `None` - The final build mode is determined according to the defined precedence rules This clarifies user intent and improves extensibility for future configuration sources. # 3. JSON File Normalization Relevant JSON files have been updated to ensure that fields are ordered in ascending ASCII order. - This change does not affect functionality, but improves: - file consistency - diff readability alignment with common tooling and formatting conventions # 4. Documentation and CI Updates - The Quick Start guide has been updated to recommend the cargo-optee workflow as the primary approach - Documentation sections that were inconsistent with current behavior have been corrected - The CI configuration has been updated to cover the new arguments and corrected behavior During this process, an additional documentation inconsistency was identified and addressed as part of this PR. # 5. Investigation: Differences Between cargo, cargo-sgx, and cargo-optee The following section summarizes findings from an investigation into the design and usage differences between cargo, cargo-sgx, and cargo-optee. > The content in this section is exploratory and design-oriented, and does not affect the functional fixes or merge decision of this PR. ## 5.1 cargo-optee Is Not a cargo Subcommand Currently, cargo-optee cannot be invoked as a cargo subcommand (i.e. cargo optee). One possible reason is that the customized cargo toolchain used in the environment does not include subcommand extension support. From a pragmatic perspective, the current form is acceptable. However, from a consistency and extensibility standpoint, retaining this capability may be worth considering in the future. ## 5.2 Rationale for `cargo-optee build ta/ca` Unlike cargo-sgx, which does not require explicit sub-target selection, cargo-optee requires specifying either `ta` or `ca`. This difference stems from fundamental architectural distinctions: - In Intel SGX, enclaves are closer to being linked as libraries - In TrustZone, Trusted Applications are standalone secure-world entities As a result, this design choice is both necessary and appropriate. ## 5.3 Default Build Mode Differences <html><head></head><body> Tool | Default Build Mode -- | -- cargo | `--debug` cargo-sgx | `--release` cargo-optee | `--release` </body></html> cargo-optee aligns with cargo-sgx in this respect, which matches the performance and determinism requirements of TEE environments. ## 5.4 `run` vs `sync` Both cargo and cargo-sgx support running applications directly via `run`. In contrast, cargo-optee requires an explicit `sync` step before execution. This difference is driven by runtime environment constraints: - SGX relies on real hardware and encapsulates the toolchain tightly - TrustZone requires explicit deployment of TA and CA artifacts to either an emulator or a physical device Therefore, this behavior reflects architectural constraints rather than a tooling deficiency. That said, it may be worth exploring whether the `sync` step could be optionally integrated into cargo-optee (e.g. via a flag or default behavior) to improve usability. ## 5.5 Features, Targets, and Workflow Overlap In cargo: - features control code paths - targets select toolchains In cargo-optee, these dimensions partially overlap at the workflow level. This has also been a key point in previous discussions(see: https://github.com/apache/teaclave-trustzone-sdk/pull/245#discussion_r2462214183). At present, the main source of complexity comes from the overlap between features and targets in the build workflow. This overlap makes certain parts of the model harder to reason about and evolve. It is possible that this issue could be addressed more cleanly in the future if the toolchain converges on a cargo-only workflow (for example, if xargo is eventually phased out). Under such conditions, the separation of concerns between features and targets may become clearer. For now, however, cargo-optee remains a well-suited tool for this project: it effectively reduces configuration burden, integrates smoothly with the TrustZone SDK, and provides a simple and efficient developer experience. ## 6. Future Directions (Design Considerations) In the long term, cargo-optee could consider adopting a unified and configurable parameter resolution model, for example: ``` CLI arguments > Cargo.toml > environment variables > defaults ``` (Environment variables may also be viewed as overridable defaults.) Such a model could: - reduce the need for verbose command-line invocations - improve build reproducibility - better align cargo-optee with Cargo’s configuration philosophy This would allow for unified configurability without sacrificing explicitness. Thanks the help of @DemesneGH @m4sterchain -- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. To unsubscribe, e-mail: [email protected] For queries about this service, please contact Infrastructure at: [email protected] --------------------------------------------------------------------- To unsubscribe, e-mail: [email protected] For additional commands, e-mail: [email protected]
