Struct Builder 

pub struct Builder { /* private fields */ }

What to generate, and where.

Every method takes and returns the builder, so a build.rs reads as one expression.

Implementations

impl Builder

pub fn out_dir(self, dir: impl Into<PathBuf>) -> Self

Writes generated files to dir instead of OUT_DIR.

A build script needs this only when it writes somewhere it also reads from, such as a checked-in copy; OUT_DIR is the ordinary destination, and where openusd::include_schema! looks.

pub fn plug_info(self, path: impl Into<PathBuf>) -> Self

Reads what a plugInfo.json declares beside its schemas, the way C++ registers it: the metadata fields of each plugin’s SdfMetadata block and the kinds of its Kinds block.

Each plugin’s declarations belong to the library whose libraryName is the plugin’s Name. They are registered with that library’s schemas; a field is also named in its tokens, and read and written through extension traits on the handles it applies to (AttributeMetadata and its siblings). A plugin with no schema library is named with declaration_family, and one file may hold plugins of both sorts. A plugin that is neither is an error when generate runs.

pub fn declaration_family(self, name: impl Into<String>) -> Self

Generates the plugin called name as a family of its own, for a plugin that declares kinds or metadata fields and has no schema library. Repeatable.

The plugin is read from a file plug_info names. Its file is written as <name>.rs and included with openusd::include_schema! like a schema library’s, and its SCHEMAS registers the declarations and no schema. A name no configured plugInfo.json declares is an error when generate runs.

pub fn shader_defs( self, library: impl Into<String>, path: impl Into<PathBuf>, ) -> Self

Generates a view of each shader node the layer at path defines, as usdShaders’s shaderDefs.usda defines UsdPreviewSurface and its companions.

Each def Shader prim authoring an info:id is a node, and its view wraps the usdShade library’s Shader view, so that library must be placed with extern_library. The file is written as <library>.rs and included with openusd::include_schema! like a schema library’s.

pub fn search_path(self, dir: impl Into<PathBuf>) -> Self

Adds a directory that a schema.usda’s sublayers resolve through, the way ar::DefaultResolver::with_search_paths takes them.

Upstream schemas sublayer each other by bare path (subLayers = [@usd/schema.usda@]), which is what a search path resolves. Repeatable, and searched in the order given.

pub fn extern_library( self, library: impl Into<String>, rust_path: impl Into<String>, ) -> Self

Declares where a library this run does not generate already lives, so the generated code can name types from it.

library is the libraryName that library’s schema.usda declares and rust_path the module path its views are reachable at, as in ("usdGeom", "openusd_schemas::geom"). A class inheriting from, or reflecting, a schema of a library this run does not generate needs it declared here; a class of a declared library that a schema’s prose names is linked to where it lives, and one of an undeclared library is left as prose. The path is to the library’s views, so a library generated for its schema data alone has nothing to declare. Keyed by library name, so declaring one twice keeps the last.

pub fn schema(self, path: impl Into<PathBuf>) -> Self

Adds a schema.usda to generate a library from. Repeatable.

pub fn schema_data(self, path: impl Into<PathBuf>) -> Self

Adds a schema.usda to generate schema data from, without its views.

The generated file still carries the tokens and the declaration table a registry is built from; what it leaves out is the trait and view per schema. That is what a crate whose API for these schemas is written by hand wants: the declarations a registry needs, without a generated set of views beside its own to collide with.

A schema that declares skipCodeGeneration is treated this way whether or not it is named here.

pub fn token_enum(self, declared: TokenEnum) -> Self

Adds a Rust enum over a token property’s allowedTokens. Repeatable.

See TokenEnum for what it takes and why it is named rather than derived. The enum joins the generated file of the library its source property belongs to, beside that library’s token constants; a library no configured enum names generates exactly what it did before.

An enum whose library this run does not build generates nothing, so one list of enums describes families that are each behind their own feature. Naming a library this build neither generates nor declares with extern_library is an error.

pub fn generate(self) -> Result<(), Error>

Generates every configured library.

Configuring no schemas, shader definitions or declaration families is not an error and writes nothing: a consumer whose families are feature-gated generates none of them when its features are off, and its build.rs should not have to know that.

Otherwise the output directory must be known, from out_dir or from the OUT_DIR a build script runs with, and is created if it does not exist.

Each library writes one file, <library>.rs, named after the libraryName its /GLOBAL declares and included by openusd::include_schema!. It carries both the views and the schema data, the latter as the declaration table usd::SchemaRegistryBuilder::register takes. A library that asked for skipCodeGeneration writes that file too, carrying its tokens and its schema data without the views — the data is what a registry is built from, so a library declining an API still has to ship it.

Two schemas declaring the same libraryName would write one file, and are refused before anything is written. A file already holding what this run generates is left untouched, its modification time with it.

pub fn build_library( &self, schema: impl AsRef<Path>, views: Views, ) -> Result<Output, Error>

Generates one schema library, writing nothing.

The whole pipeline, for a caller that wants the result rather than the files: generate runs this over every schema schema named and writes what comes back. The schema is named here instead, so that list has no bearing on this call. A schema asking for skipCodeGeneration gets no views whatever views says.

pub fn build_declarations(&self, family: &str) -> Result<Output, Error>

Generates the declaration-only family of the plugin called family, writing nothing: the file generate writes for a name declaration_family gave.

pub fn build_shader_defs( &self, library: &str, path: impl AsRef<Path>, ) -> Result<NodeOutput, Error>

Generates the views of the shader nodes the layer at path defines, writing nothing: the file generate writes for a library shader_defs named.

Trait Implementations

impl Debug for Builder

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.