Skip to content

Latest commit

 

History

History
75 lines (51 loc) · 3.35 KB

README.md

File metadata and controls

75 lines (51 loc) · 3.35 KB
Raw

Rusoto Service Crate Generator

This executable generates crates for AWS services based on their botocore service manifests.

Usage

In order to run the service generator, first make sure that the botocore submodule has been initialized:

$ git submodule update --init

The service generator uses the stable version of rustfmt to format the generated code nicely.

Install the rustfmt component via rustup:

$ rustup component add --toolchain stable rustfmt

From the service_crategen directory, call:

$ cargo +stable run -- generate -c ./services.json -o ../rusoto/services

This will regenerate all services in the rusoto/services directory, updating them with the configuration defined in the services.json file and applying any code generation changes.

It is also possible to limit the set of services generated by the generator. For example, to only generate the s3 and ec2 crates, run the following:

$ cargo +stable run -- generate -c ./services.json -o ../rusoto/services -s s3 -s ec2
    Finished dev [optimized] target(s) in 0.35s
    Running `target/debug/rusoto_service_crategen generate -c ./services.json -o ../rusoto/services -s s3 -s ec2`
Generating crate for Amazon Simple Storage Service @ 2006-03-01...
Generating crate for Amazon Elastic Compute Cloud @ 2016-11-15...

Customizing Generated Crates

Some service crates may require customized code, perhaps as helper code to make it easier to use for end-users or custom tests. Since services are regenerated by the generator, there needs to be a safe place for custom code to sit that won't be destroyed on regeneration.

Every crate is generated with a custom module inside. This module is empty by default, but anything can be added to the custom directory and module after generation and it will not be deleted on regeneration. This does mean, however, that care must be taken to verify that custom code still builds and works on regenerated crates, so it should be well-tested and kept up-to-date.

Testing Generated Crates

After regenerating, all crates should be tested to verify that they still build and their tests pass. This is a fairly simple process. From the rusoto directory, run:

$ cargo +stable test --all --lib

This will tests service crates, in addition to the rusoto_core crate.

Accommodating type name conflicts

At times you will find that botocore definition will define a shape Rusoto translates into a struct whose name conflicts with the name Rusoto sythesizes for error type enum for operations. In those cases, the common approach to accommodate these collisions is to customize the name of the error enum rusoto generates. Do this in service_codegen/src/commands/generate/codgen/mod.rs in the mutate_type_name method.

Checking Services (Missing & Outdated)

The crate generator is also able to check for any missing or outdated services with the check command:

$ cargo +stable run -- check -c ./services.json

If there are any missing or outdated services, they will be output in a formatted list along with useful information.

Crate generation timing

To output timing information on crate generation, run with logging set to debug level:

$ RUST_LOG=rusoto_service_crategen=debug cargo +stable run -- generate -c ./services.json -o ../rusoto/services