Quick Start

This guide introduces [smithy4rs] with a simple working example of generating (de)serializable types .

Prerequisites

• Ensure you have installed rust and cargo
• Ensure you have the Smithy CLI installed.
  • To check if you have the CLI installed, Run smithy --version in your terminal.
  • If you need to install the CLI, see the Smithy CLI installation guide.

Setup

Create a new rust project

First, create a new Rust project by running cargo init in a new directory. This will set up the basic boilerplate for our crate.

Next, add smithy-cargo as a build dependency:

cargo add --build smithy-cargo

This tool will integrate the Smithy build tooling with Cargo.

Also add smithy4rs-core as a dependency:

cargo add smithy4rs-core

This package defines the Smithy data model in rust and adds all the core functionality (such as serialization) for generate shapes.

Set up Smithy build tooling

We will now set up smithy-cargo to execute the Smithy CLI as part of the cargo build process.

First, create a build.rs file at the root of your project and add the following build script:

use smithy_cargo::SmithyBuild;

fn main() {
  /// Executes the `smithy` CLI `build` command from cargo
  /// and configures some environment variables to point to the 
  /// generated output folder.
  SmithyBuild::new().execute().expect("Smithy Build failed");
}

Then, add a smithy-build.json file to the root of your project to configure the Smithy build:

{
  "version": "1.0",
  "maven": {
    "dependencies": [
      "dev.hmellema.smithy4rs:type-codegen:1.0.0"
    ]
  },
  "plugins": {
    "rust-types": {
      "TODO": "ADD REAL CONFIG"
    }
  }
}

Now, we are ready to create our model!

Event Model

For this quickstart we are going to generate a few event shapes.

TODO: Come up with a bit more interesting framing

namespace com.quickstart.example

/// Doc comment
structure EventA {
    int: Integer
}

Using the generated shapes

To use our generated shapes, simply create a module add import them using the generated_shapes! macro.

#![allow(unused)]
fn main() {
mod shapes {
    use smithy4rs_core::generated_shapes;

    generated_shapes![];
}
}

We can now use our generated shapes elsewhere in our rust code:

fn main() {
  // Create a new, validated event instance
  let event = EventA::builder()
          .int(42)
          .build()
          .expect("Should Build");
  // pretty-print the event
  println!("{:#?}", event)
}