2023-11-11 02:51:04 +08:00
Smithy Rust [](https://github.com/smithy-lang/smithy-rs/actions/workflows/ci-main.yml)
2022-01-28 05:05:31 +08:00
==================================================================================
2020-10-28 21:37:45 +08:00
2022-01-28 05:05:31 +08:00
Smithy code generators for Rust that generate clients, servers, and the entire AWS SDK.
The latest unreleased SDK build can be found in [aws-sdk-rust/next ](https://github.com/awslabs/aws-sdk-rust/tree/next ).
2021-01-27 01:30:42 +08:00
2023-11-18 01:46:13 +08:00
[Design documentation ](https://smithy-lang.github.io/smithy-rs/design/ )
2021-05-07 06:59:12 +08:00
2021-01-27 01:30:42 +08:00
**All internal and external interfaces are considered unstable and subject to change without notice.**
2022-02-02 10:15:20 +08:00
Setup
-----
2022-06-24 00:27:43 +08:00
1. `./gradlew` will setup gradle for you. JDK 17 is required.
2020-11-05 11:09:00 +08:00
2. Running tests requires a working Rust installation. See [Rust docs ](https://www.rust-lang.org/learn/get-started ) for
2022-09-30 23:50:42 +08:00
installation instructions on your platform. The MSRV (**M**inimum **S**upported **R**ust **V**ersion) for the crates in this project is `stable-2` , i.e. the current `stable` Rust version and the prior two versions. Older versions may work.
2020-10-28 21:37:45 +08:00
2022-02-02 10:15:20 +08:00
Development
-----------
2020-10-28 21:37:45 +08:00
2022-02-02 10:15:20 +08:00
For development, pre-commit hooks make it easier to pass automated linting when opening a pull request. Setup:
```bash
2020-11-05 11:09:00 +08:00
brew install pre-commit # (or appropriate for your platform: https://pre-commit.com/)
pre-commit install
```
2021-01-20 04:23:07 +08:00
2022-02-02 10:15:20 +08:00
Project Layout
--------------
2021-01-20 04:23:07 +08:00
* `aws` : AWS specific codegen & Rust code (signing, endpoints, customizations, etc.)
2021-05-07 06:59:12 +08:00
Common commands:
2022-02-02 10:15:20 +08:00
* `./gradlew :aws:sdk:assemble` : Generate (but do not test / compile etc.) a fresh SDK into `sdk/build/aws-sdk`
Renaming gradle task `:aws:sdk:test` to `sdkTest` avoid task name collision (#3650)
It is now called :aws:sdk:sdkTest and the README has been updated to
align with this.
## Motivation and Context
<!--- Why is this change required? What problem does it solve? -->
<!--- If it fixes an open issue, please link to the issue here -->
The gradle task `:aws:sdk:test` mentioned in our `README` has been
broken for sometime. This seems to be because one of the plugins we are
using (I was unable to determine exactly which one) is registering a
task named `test` and it was conflicting with ours.
## Description
<!--- Describe your changes in detail -->
I changed the name of the broken task to `:aws:sdk:sdkTest`, explicitly
registered it, and added the appropriate dependencies and steps for the
task. I also updated the `README` to reflect this new name and added a
note to indicate that these tests require Go to be installed (because
they tests some FIPS functionality).
## Testing
<!--- Please describe in detail how you tested your changes -->
<!--- Include details of your testing environment, and the tests you ran
to -->
<!--- see how your change affects other areas of the code, etc. -->
I was able to successfully run `./gradlew :aws:sdk:sdkTest` on my local
machine (after installing Go which I was initially missing).
## Checklist
<!--- If a checkbox below is not applicable, then please DELETE it
rather than leaving it unchecked -->
No changes to any published code in this PR
----
_By submitting this pull request, I confirm that you can use, modify,
copy, and redistribute this contribution, under the terms of your
choice._
2024-05-21 05:51:24 +08:00
* `./gradlew :aws:sdk:sdkTest` : Generate & run all tests for a fresh SDK. (Note that these tests require Go to be
installed for FIP support to compile properly)
2022-02-02 10:15:20 +08:00
* `./gradlew :aws:sdk:{cargoCheck, cargoTest, cargoDocs, cargoClippy}` : Generate & run specified cargo command.
2022-09-08 00:31:46 +08:00
* `codegen-core` : Common code generation logic useful for clients and servers
* `codegen-client` : Whitelabel Smithy client code generation
* `codegen-client-test` : Smithy protocol test generation & integration tests for Smithy client whitelabel code
2021-05-07 06:59:12 +08:00
* [`design` ](design ): Design documentation. See the [design/README.md ](design/README.md ) for details about building / viewing.
2021-11-10 20:51:31 +08:00
* `codegen-server` : Whitelabel Smithy server code generation
* `codegen-server-test` : Smithy protocol test generation & integration tests for Smithy server whitelabel code
2023-03-22 22:00:21 +08:00
* `examples` : A collection of server implementation examples
2022-02-02 10:15:20 +08:00
Testing
-------
Running all of smithy-rs's tests can take a very long time, so it's better to know which parts
to test based on the changes being made, and allow continuous integration to find other issues
when posting a pull request.
In general, the components of smithy-rs affect each other in the following order (with earlier affecting later):
1. `rust-runtime`
2. `codegen` and `codegen-server`
3. `aws/rust-runtime`
4. `aws/sdk-codegen`
2022-09-08 00:31:46 +08:00
Some components, such as `codegen-client-test` and `codegen-server-test` , are purely for testing other components.
2022-02-02 10:15:20 +08:00
### Testing `rust-runtime` and `aws/rust-runtime`
To test the `rust-runtime` crates:
```bash
2022-11-01 00:47:27 +08:00
# Run all Rust tests for `rust-runtime/` (from repo root):
cargo test --manifest-path=rust-runtime/Cargo.toml
# Run clippy for `rust-runtime/` (from repo root):
cargo clippy --manifest-path=rust-runtime/Cargo.toml
# Or
cd rust-runtime
cargo test
cargo clippy
2022-02-02 10:15:20 +08:00
```
2022-11-01 00:47:27 +08:00
To test the `aws/rust-runtime` crates:
2022-02-02 10:15:20 +08:00
```bash
2022-11-01 00:47:27 +08:00
# Run all Rust tests for `aws/rust-runtime/` (from repo root):
cargo test --manifest-path=aws/rust-runtime/Cargo.toml
# Run clippy for `aws/rust-runtime/` (from repo root):
cargo clippy --manifest-path=aws/rust-runtime/Cargo.toml
# Or
cd aws/rust-runtime
cargo test
cargo clippy
2022-02-02 10:15:20 +08:00
```
Some runtime crates have a `additional-ci` script that can also be run. These scripts often require
[`cargo-hack` ](https://github.com/taiki-e/cargo-hack ) and [`cargo-udeps` ](https://github.com/est31/cargo-udeps )
to be installed.
### Testing Client/Server Codegen
To test the code generation, the following can be used:
```bash
# Run Kotlin codegen unit tests
2022-09-08 00:31:46 +08:00
./gradlew codegen-core:check
./gradlew codegen-client:check
./gradlew codegen-server:check
2022-02-02 10:15:20 +08:00
# Run client codegen tests
2022-09-08 00:31:46 +08:00
./gradlew codegen-client-test:check
2022-02-02 10:15:20 +08:00
# Run server codegen tests
./gradlew codegen-server-test:check
```
Several Kotlin unit tests generate Rust projects and compile them. When these fail, they typically
output links to the location of the generated code so that it can be inspected.
To look at generated code when the codegen tests fail, check these paths depending on the test suite that's failing:
2022-09-08 00:31:46 +08:00
- For codegen-client-test: `codegen-client-test/build/smithyprojections/codegen-client-test`
- For codegen-server-test: `codegen-server-test/build/smithyprojections/codegen-server-test`
2022-02-02 10:15:20 +08:00
### Testing SDK Codegen
See the readme in `aws/sdk/` for more information about these targets as they can be configured
to generate more or less AWS service clients.
```bash
# Run Kotlin codegen unit tests
./gradlew aws:sdk-codegen:check
# Generate an SDK, but do not attempt to compile / run tests. Useful for inspecting generated code
./gradlew :aws:sdk:assemble
# Run all the tests
Renaming gradle task `:aws:sdk:test` to `sdkTest` avoid task name collision (#3650)
It is now called :aws:sdk:sdkTest and the README has been updated to
align with this.
## Motivation and Context
<!--- Why is this change required? What problem does it solve? -->
<!--- If it fixes an open issue, please link to the issue here -->
The gradle task `:aws:sdk:test` mentioned in our `README` has been
broken for sometime. This seems to be because one of the plugins we are
using (I was unable to determine exactly which one) is registering a
task named `test` and it was conflicting with ours.
## Description
<!--- Describe your changes in detail -->
I changed the name of the broken task to `:aws:sdk:sdkTest`, explicitly
registered it, and added the appropriate dependencies and steps for the
task. I also updated the `README` to reflect this new name and added a
note to indicate that these tests require Go to be installed (because
they tests some FIPS functionality).
## Testing
<!--- Please describe in detail how you tested your changes -->
<!--- Include details of your testing environment, and the tests you ran
to -->
<!--- see how your change affects other areas of the code, etc. -->
I was able to successfully run `./gradlew :aws:sdk:sdkTest` on my local
machine (after installing Go which I was initially missing).
## Checklist
<!--- If a checkbox below is not applicable, then please DELETE it
rather than leaving it unchecked -->
No changes to any published code in this PR
----
_By submitting this pull request, I confirm that you can use, modify,
copy, and redistribute this contribution, under the terms of your
choice._
2024-05-21 05:51:24 +08:00
./gradlew :aws:sdk:sdkTest
2022-02-02 10:15:20 +08:00
# Validate that the generated code compiles
./gradlew :aws:sdk:cargoCheck
# Validate that the generated code passes Clippy
./gradlew :aws:sdk:cargoClippy
# Validate the generated docs
./gradlew :aws:sdk:cargoDoc
```
The generated SDK will be placed in `aws/sdk/build/aws-sdk` .
