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

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

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.