#smithy #build-dependencies #smithy-cargo

build smithy-cargo-macros

Macros for use alongside smithy-cargo build tool

2 stable releases

Uses new Rust 2024

1.0.1 Mar 28, 2025
1.0.0 Mar 23, 2025

#464 in Build Utils

Download history 91/week @ 2025-03-19 134/week @ 2025-03-26

225 downloads per month

Custom license

8KB

smithy-cargo

CI Status License Crates.io dependency status

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.

Dependencies

~0.5–1MB
~24K SLoC