This is an automated email from the ASF dual-hosted git repository.
ivila pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/teaclave-trustzone-sdk.git
The following commit(s) were added to refs/heads/main by this push:
new 1727d05 docs: fix docs.rs build and add document-features integration
1727d05 is described below
commit 1727d054558016bf7409631fd77ffd66cc97bff1
Author: ivila <[email protected]>
AuthorDate: Wed May 13 09:22:45 2026 +0800
docs: fix docs.rs build and add document-features integration
* Add comments to all feature flags across `optee-utee`, `optee-utee-sys`,
`optee-teec`, and `optee-teec-sys` crates, also add
`[package.metadata.docs.rs]` config for each crate.
* Integrate the `document-features` crate so that feature descriptions are
rendered in `docs.rs` output.
---
crates/Cargo.toml | 1 +
crates/optee-teec-build/src/lib.rs | 6 ++++++
crates/optee-teec-build/src/plugin.rs | 29 +++++++++++++++++++++++++++++
crates/optee-teec-sys/Cargo.toml | 14 ++++++++++++--
crates/optee-teec-sys/src/lib.rs | 6 ++++++
crates/optee-teec/Cargo.toml | 9 +++++++++
crates/optee-teec/src/lib.rs | 7 +++++++
crates/optee-utee-sys/Cargo.toml | 14 ++++++++++++++
crates/optee-utee-sys/src/lib.rs | 6 ++++++
crates/optee-utee/Cargo.toml | 13 +++++++++++++
crates/optee-utee/src/lib.rs | 6 ++++++
11 files changed, 109 insertions(+), 2 deletions(-)
diff --git a/crates/Cargo.toml b/crates/Cargo.toml
index 5995452..9ca5aa0 100644
--- a/crates/Cargo.toml
+++ b/crates/Cargo.toml
@@ -62,3 +62,4 @@ once_cell = "1.20.2"
serde = { version = "1.0.228" }
serde_json = { version = "1.0.149" }
log = "0.4.29"
+document-features = "0.2.12"
diff --git a/crates/optee-teec-build/src/lib.rs
b/crates/optee-teec-build/src/lib.rs
index 453636d..1864260 100644
--- a/crates/optee-teec-build/src/lib.rs
+++ b/crates/optee-teec-build/src/lib.rs
@@ -15,6 +15,12 @@
// specific language governing permissions and limitations
// under the License.
+//! Build-time helper for OP-TEE supplicant plugins.
+//!
+//! This crate provides [`PluginConfig`] which generates a Rust source file
+//! containing the static `plugin_method` symbol required by the OP-TEE
+//! plugin ABI. It is intended to be used in a `build.rs` script.
+
mod plugin;
pub use uuid;
diff --git a/crates/optee-teec-build/src/plugin.rs
b/crates/optee-teec-build/src/plugin.rs
index 1d0c986..c2d1f41 100644
--- a/crates/optee-teec-build/src/plugin.rs
+++ b/crates/optee-teec-build/src/plugin.rs
@@ -18,9 +18,17 @@
use std::path::PathBuf;
pub use uuid;
+/// Default name for the plugin init function.
pub const DEFAULT_INIT_FN_NAME: &str = "__plugin_bindgen_init";
+/// Default name for the plugin invoke function.
pub const DEFAULT_INVOKE_FN_NAME: &str = "__plugin_bindgen_invoke";
+/// Configuration for building an OP-TEE supplicant plugin binding.
+///
+/// Holds the plugin name, UUID, init/invoke function names, and optional
+/// output destination. Use the builder-style API (`with_*` methods) to
+/// customize defaults, then call [`PluginConfig::build`] to generate the
+/// `plugin_static.rs` file.
pub struct PluginConfig {
name: String,
uuid: uuid::Uuid,
@@ -30,6 +38,11 @@ pub struct PluginConfig {
}
impl PluginConfig {
+ /// Creates a new `PluginConfig` with the given UUID.
+ ///
+ /// The plugin name defaults to `CARGO_PKG_NAME`, and the init/invoke
+ /// function names default to [`DEFAULT_INIT_FN_NAME`] and
+ /// [`DEFAULT_INVOKE_FN_NAME`] respectively.
pub fn new(uuid: uuid::Uuid) -> Self {
Self {
name: env!("CARGO_PKG_NAME").to_string(),
@@ -39,18 +52,30 @@ impl PluginConfig {
dest: None,
}
}
+ /// Sets a custom plugin name.
pub fn with_name(mut self, name: &str) -> Self {
self.name = name.to_string();
self
}
+ /// Sets a custom init function name (overriding [`DEFAULT_INIT_FN_NAME`]).
pub fn with_init_fn_name(mut self, fn_name: &str) -> Self {
self.init_fn_name = fn_name.to_string();
self
}
+ /// Sets a custom invoke function name (overriding
[`DEFAULT_INVOKE_FN_NAME`]).
pub fn with_invoke_fn_name(mut self, fn_name: &str) -> Self {
self.invoke_fn_name = fn_name.to_string();
self
}
+ /// Sets a custom output file path
+ pub fn with_dest(mut self, out_path: PathBuf) -> Self {
+ self.dest = Some(out_path);
+ self
+ }
+ /// Generates the plugin binding source and writes it to the output file.
+ ///
+ /// If the output file already exists with identical content, the write is
+ /// skipped. The default output path is `$OUT_DIR/plugin_static.rs`.
pub fn build(&self) -> std::io::Result<()> {
let codes = generate_binding(
&self.name,
@@ -74,6 +99,10 @@ impl PluginConfig {
}
impl PluginConfig {
+ /// Returns the output file path for the generated binding.
+ ///
+ /// Uses the custom destination if set, otherwise defaults to
+ /// `$OUT_DIR/plugin_static.rs`.
fn get_out_path(&self) -> PathBuf {
match self.dest.as_ref() {
Some(v) => v.clone(),
diff --git a/crates/optee-teec-sys/Cargo.toml b/crates/optee-teec-sys/Cargo.toml
index 9a2ecc6..44a697e 100644
--- a/crates/optee-teec-sys/Cargo.toml
+++ b/crates/optee-teec-sys/Cargo.toml
@@ -26,5 +26,15 @@ edition.workspace = true
links = "teec"
[features]
-default=[]
-no_link=[]
+## enables nothing.
+default = []
+## prevents the build script from emitting linker directives for the native
+## `libteec` library. This is needed for environments where the OP-TEE client
+## library is not available, such as docs.rs or host-side testing.
+no_link = []
+
+[package.metadata.docs.rs]
+features = ["no_link"]
+
+[dependencies]
+document-features.workspace = true
diff --git a/crates/optee-teec-sys/src/lib.rs b/crates/optee-teec-sys/src/lib.rs
index f667972..a8c8336 100644
--- a/crates/optee-teec-sys/src/lib.rs
+++ b/crates/optee-teec-sys/src/lib.rs
@@ -15,6 +15,12 @@
// specific language governing permissions and limitations
// under the License.
+#![cfg_attr(doc, doc = concat!(
+ env!("CARGO_PKG_DESCRIPTION"),
+ "\n",
+ "## Feature flags\n",
+ document_features::document_features!(),
+))]
#![allow(non_camel_case_types, non_snake_case)]
pub use plugin_method::*;
diff --git a/crates/optee-teec/Cargo.toml b/crates/optee-teec/Cargo.toml
index 70b10e4..dc3327f 100644
--- a/crates/optee-teec/Cargo.toml
+++ b/crates/optee-teec/Cargo.toml
@@ -25,8 +25,13 @@ repository.workspace = true
edition.workspace = true
[features]
+## enables nothing.
default = []
+## re-exports the `optee-teec-macros` crate as `optee_teec::macros`, providing
+## the `#[plugin_init]` and `#[plugin_invoke]` proc-macro attributes.
macros = ["dep:optee-teec-macros"]
+## used for docs.rs to generate docs. It disables native `libteec` linking.
+doc = ["optee-teec-sys/no_link"]
[dependencies]
optee-teec-sys.workspace = true
@@ -35,6 +40,10 @@ uuid.workspace = true
hex.workspace = true
num_enum.workspace = true
log.workspace = true
+document-features.workspace = true
[dev-dependencies]
optee-teec-sys = { workspace = true, features = ["no_link"] }
+
+[package.metadata.docs.rs]
+features = ["doc"]
diff --git a/crates/optee-teec/src/lib.rs b/crates/optee-teec/src/lib.rs
index 8510e54..1b7f230 100644
--- a/crates/optee-teec/src/lib.rs
+++ b/crates/optee-teec/src/lib.rs
@@ -15,6 +15,13 @@
// specific language governing permissions and limitations
// under the License.
+#![cfg_attr(doc, doc = concat!(
+ env!("CARGO_PKG_DESCRIPTION"),
+ "\n",
+ "## Feature flags\n",
+ document_features::document_features!(),
+))]
+
pub use self::context::Context;
pub use self::error::{Error, ErrorKind, ErrorOrigin, Result};
pub use self::extension::*;
diff --git a/crates/optee-utee-sys/Cargo.toml b/crates/optee-utee-sys/Cargo.toml
index 92d38ec..3a0de86 100644
--- a/crates/optee-utee-sys/Cargo.toml
+++ b/crates/optee-utee-sys/Cargo.toml
@@ -27,9 +27,23 @@ links = "utee"
[dependencies]
mockall = { version = "0.14.0", optional = true }
+document-features.workspace = true
[features]
+## enables nothing.
default = []
+## enables the standard library. Without it, the crate is compiled as `no_std`
std = []
+## prevents the build script from emitting linker directives for the OP-TEE
+## native libraries (libutee, libutils, libmbedtls). This is needed for
+## environments where those libraries are not available, such as docs.rs or
+## host-side testing.
no_link = []
+## enables host-side unit testing of TA code by using the `mockall` crate to
+## auto-generate mock implementations of the TEE internal API FFI declarations.
+## It implicitly enables `std` (required by mockall) and `no_link` (no real TEE
+## libraries should be linked during host-side tests).
mock = ["dep:mockall", "std", "no_link"]
+
+[package.metadata.docs.rs]
+features = ["no_link"]
diff --git a/crates/optee-utee-sys/src/lib.rs b/crates/optee-utee-sys/src/lib.rs
index b17d69a..a14a4d5 100644
--- a/crates/optee-utee-sys/src/lib.rs
+++ b/crates/optee-utee-sys/src/lib.rs
@@ -17,6 +17,12 @@
#![cfg_attr(not(feature = "std"), no_std)]
#![allow(non_camel_case_types, non_snake_case)]
+#![cfg_attr(doc, doc = concat!(
+ env!("CARGO_PKG_DESCRIPTION"),
+ "\n",
+ "## Feature flags\n",
+ document_features::document_features!(),
+))]
pub use tee_api::api::*;
pub use tee_api_defines::*;
diff --git a/crates/optee-utee/Cargo.toml b/crates/optee-utee/Cargo.toml
index 5a5606b..51b49e5 100644
--- a/crates/optee-utee/Cargo.toml
+++ b/crates/optee-utee/Cargo.toml
@@ -32,6 +32,7 @@ uuid.workspace = true
hex.workspace = true
libc_alloc = "1.0.5"
strum = { version = "0.28", default-features = false, features = ["derive"] }
+document-features.workspace = true
[dev-dependencies]
rand.workspace = true
@@ -41,7 +42,19 @@ serde_json.workspace = true
optee-utee-sys = { workspace = true, features = ["mock"] }
[features]
+## enables nothing.
default = []
+## enables the ability to use the standard library.
std = ["optee-utee-sys/std", "optee-utee-macros/std"]
+## disables the default panic handler (which calls `TEE_Panic`), allowing TA
+## developers to provide a custom `#[panic_handler]`.
no_panic_handler = []
+## provides linker stubs for `_Unwind_Resume` and `rust_eh_personality`. These
+## are required by the precompiled sysroot when not using `-Z build-std`, even
+## though `panic=abort` guarantees they are never called at runtime.
unwind_stubs = []
+## used for docs.rs to generate docs.
+doc = ["optee-utee-sys/no_link"]
+
+[package.metadata.docs.rs]
+features = ["doc"]
diff --git a/crates/optee-utee/src/lib.rs b/crates/optee-utee/src/lib.rs
index 4d4e0de..08acf35 100644
--- a/crates/optee-utee/src/lib.rs
+++ b/crates/optee-utee/src/lib.rs
@@ -16,6 +16,12 @@
// under the License.
#![cfg_attr(not(feature = "std"), no_std)]
+#![cfg_attr(doc, doc = concat!(
+ env!("CARGO_PKG_DESCRIPTION"),
+ "\n",
+ "## Feature flags\n",
+ document_features::document_features!(),
+))]
// Requires `alloc`.
#[macro_use]
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
