2 stable releases
Uses new Rust 2024
1.0.1 | Mar 28, 2025 |
---|---|
1.0.0 | Mar 23, 2025 |
0.1.0 |
|
#209 in Build Utils
343 downloads per month
15KB
193 lines
smithy-cargo
Tooling for building Smithy models from cargo build scripts (build.rs
).
This crate does not build models itself; it calls out to the Smithy CLI, expecting it to be installed on the current machine.
Getting Started
Important
Before you proceed, make sure you have the Smithy CLI installed.
First, create a new cargo project and add smithy-cargo
as a build dependency
cargo new smithy-cargo-example \
&& cd smithy-cargo-example \
&& cargo add --build smithy-cargo
Next, add a smithy-build
config file to the
root of the project. This config file determines how Smithy will build your models.
Now, add any smithy models we want to build to a model/
directory within our cargo project.
smithy-cargo
will automatically discover any smithy files within the model/
directory
and include them as sources for the Smithy build.
Finally, configure smithy-cargo
to run as part of your cargo build script (build.rs
):
use smithy_cargo::SmithyBuild;
fn main() {
SmithyBuild::new().execute().expect("Failed to build Smithy models");
}
Your fully configured cargo project should now look something like:
.
├── Cargo.toml
├── build.rs
├── model
│ └── a.smithy
├── smithy-build.json
└── src
└── main.rs
To run the Smithy build, just run cargo build
as you would normally and the smithy build
will be executed by the build script.
Including generated Rust code
Warning
This package does not provide any Smithy code generation plugins for rust on its own. You will still need to add a rust codegen plugin (such as smithy4rs) to actually generate rust code
Your Smithy build may use a build plugin to generate Rust code that you want to include as part of your crate.
For example the following smithy-build
config:
{
"version": "1.0",
"maven": {
"dependencies": ["com.example:my-rust-code-generator:1.0.0"]
},
"plugins": {
"example-rust-codegen": { }
}
}
Might generate a number of .rs
files as build artifacts.
The smithy-cargo-macros
package provides a add_smithy_files
macro to
make it easy to include generated rust code in your crate.
To use the macro, add the following dependencies to your Cargo.toml
:
[dependencies]
smithy-cargo-macros = "<VERSION>"
crabtime = "<VERSION>"
Then apply the add_smithy_files
macro within your rust code to include the generated
artifacts.
use smithy_cargo_macros::add_smithy_files;
// Module containing all of our generated Smithy shapes
mod shapes {
// Adds generated files from the "example-rust-codegen" plugin in the "source" projection.
// Note: the "source" projection is the default projection for Smithy.
add_smithy_files!("source", "example-rust-codegen");
}
fn my_function(string: String) {
// Example usage
let shapes::GeneratedShapeA { fieldA: 2 };
// ...
}
License
This library is licensed under the Apache 2.0 License.