Add Language & Build System Support Table

[XAMPPRocky]

Hello this is an issue similar to #733. It is currently very unclear what is and is not supported by this project. So it is hard to know if this project can even fit my use-cases, because it is not clear what projects I can use this for.

One example of this is, is I was interested in using this in one of my Rust projects as that there is support generating Rust APIs, but there is no standalone tool I can use, I have to use Gradle, which for most projects primarily developed in Rust is a non-starter.

It would be nice if there was a section in documentation that detailed what languages and build systems are currently compatible with Smithy codegen, and what language APIs can be generated from smithy's codegen.

[mtdowling]

Good idea. We'll work on getting some kind of status quo added to the docs.

Smithy is only supported in Java today, and the only build tool we offer support for is Gradle. You can use the Dockerfile we provide too, which bundles it all up.

To help me understand -- If you're building something in Rust, do all the build tools you use need to be implemented in Rust? Would you care what Smithy was implemented in if it used Java but was built as a standalone executable?

[XAMPPRocky]

To help me understand -- If you're building something in Rust, do all the build tools you use need to be implemented in Rust? Would you care what Smithy was implemented in if it used Java but was built as a standalone executable?

It doesn't to be implemented in Rust for me to use it, it needs to be at least build.rs friendly. A free-standing binary would be a solution for using what is currently supported. However, I think my follow-up question would be, how would I be able to extend that free-standing binary's functionality beyond what is available?

For example, would I be able to write my own Smithy projection in my preferred language, without needing upstream changes or using Java? If Smithy is a free-standing tool, I would kinda hope that I can integrate with it using a language agnostic protocol.

[mtdowling]

If we shipped a standalone tool for the Java reference implementation, it would likely be done using JLink, which means that it could still load JARs that weren't compiled into the binary. Regardless though of a standalone tool or not, the only supported extension mechanism today is to write code in Java.

We realized in AWS that it takes a huge investment to create build tooling and code generators from scratch in each programming language we support, so every Smithy generator we're building is written in Java using shared tooling (for example, smithy-rs and aws-sdk-rust). We also do what's called model-ignorant code generation, so there's no runtime Java dependency needed to use any of the generated code nor is the model needed at runtime.

smithy-rs is meant to be a generic Smithy code generator for Rust, and aws-sdk-rust extends it to add AWS-specific functionality. Smithy-rs will eventually be polished up to work well with Rust build tools and be able to generate clients and servers, but it's not quite there yet. There's also a project to implement parts of Smithy in Rust, but it's still very early in development: https://github.com/johnstonskj/rust-atelier.

[XAMPPRocky]

We realized in AWS that it takes a huge investment to create build tooling and code generators from scratch in each programming language we support, so every Smithy generator we're building is written in Java using shared tooling (for example, smithy-rs and aws-sdk-rust). We also do what's called model-ignorant code generation, so there's no runtime Java dependency needed to use any of the generated code nor is the model needed at runtime.

I definitely understand why AWS would focus on single language tooling. However I will say that I don't see these two things as incompatible or diverging paths, and a lack of language agnostic extensibility makes this project hard to adopt for non-Java teams even with AWS' own codegen tooling. Most projects I work on where I would want to use Smithy, I want to target platforms and languages that aren't and may never be priority for AWS to provide tooling for, but I still would want to use Smithy as the IDL for those platforms. Writing my own target projection would be acceptable provided that I could write something that would integrate well with the project, but requiring Java is too much of a barrier to use this in a personal project, and there's no way I could get the buy in from a team to add a custom Java package dependency to our build process just to be able to use Smithy for the project if we weren't already using Java.

I'm not sure why additional backends would require JLink. Smithy already provides a language agnostic API in terms of its JSON AST as an intermediate representation language, any other language can read that. So a minimal version of this could just be smithy ./sdk.smithy -o json | smithy-codegen-acme. I think ideally it would output JSON that's more tool/machine friendly, and a less human friendly version of the AST that's gone through validation and trait resolution, so all of that logic can remain part of the mainline smithy tool, and the target backends can focus just on generating code.

[mtdowling]

I appreciate your input! I've updated the docs to list all things we've shipped, what we're working on, and their status. The PR with those doc updates closed this issue. Do you want to update the title and reopen as a feature request?

What I meant with JLink was that if we provided a standalone CLI tool that removed the need for Gradle, it would still be able to load additional JARs. That isn't to say that some kind of process-based smithy-build plugin couldn't be added (e.g., the Smithy CLI could invoke some referenced process as part of this). The JSON AST representation of a Smithy model and the central tool handling validation does make it easier for other tools to use. I think it would end up being significantly more work to build codegen tooling from scratch in another language that can load and traverse the metamodel, but it sounds like that's an acceptable tradeoff in your case.

If you want a use case like ./sdk.smithy -o json | smithy-codegen-acme, then it's not really that far off from what we have now, since the CLI has an ast command. We'd just need to ship a standalone CLI (and I guess in the meantime you could Docker):

./smithy ast MODEL1 MODEL2 ... | smithy-codegen-acme