Where do we document template dependencies?

[technosophos]

The Rust template requires the wasm32-wasi target. The Go templates require TinyGo. Where do we document these requirements? Specifically, say a developer does this:

$ spin templates list
# sees some templates, chooses one they've never used before
$ spin new http-go myapp
$ spin build

The build will fail if TinyGo is not installed. What does the user then do to figure out why the build failed?

[technosophos]

I'm asking specifically because #628 requires that a user install SwiftWasm >= 5.5.0, and I don't know where to document that requirement.

[radu-matei]

We've been using https://spin.fermyon.dev/other-languages/ as the place to document languages we don't have a dedicated SDK for. (source in https://github.com/fermyon/spin/blob/main/docs/content/other-languages.md)

[technosophos]

The assumption, then, is that if the user has a local build failure, they'll go to spin.fermyon.dev and try to find an answer? Would it be easier/preferable to add a BUILD.txt or some similarly standard text file that tells people what is necessary for a successful build?

[itowlson]

I like that idea.

Another idea is to provide a prerequisites section which would be a bunch of command lines that need to 'pass' (for some value of 'pass') or it would print a message saying "you need X." But that feels risky because a malicious template author could include command lines that deleted, corrupted or exfiltrated customer data.

[technosophos]

I do like the idea of prerequisites. And I am not sure it's any riskier than the build command (which could equally be hijacked to do dastardly deeds)

[lann]

Or simpler: some kind of notes field that will just be printed on template instantiation. At least for our templates we could point at TinyGo et al there.

[itowlson]

Thinking more about this... this doesn't belong on templates, but in the [component.build] section, so that if Alice creates an application from a template, commits it, and then Bob checks it out, Bob can still get the prerequisites info, even though Bob never sees or uses the original template.

It doesn't matter much at the tyre-kicking phase, I guess. And of course we could run checks/print prereqs/etc. on instantiation as well. Just thinking of the post-instantiation lifecycle.

[itowlson]

I had a look at scanning the build output to detect tool setup issues (as opposed to code that just doesn't build), and it kinda works, but I can't see an easy way to have the build output stream to the terminal and capture it to examine the failure. We could do it using a lower-level API, but I bet that would still end up compromised because of things like terminal-based output colouration. Sigh.

[itowlson]

Which possibly pushes us back in the direction of a separate "check prerequisites" action a la spin build --check. But how to get people to discover it?

[mikkelhegn]

Would be good if part of the notes also included whether a template uses a Spin SDK or not. Mainly to help understand the level of support for said template.

[itowlson]

As opposed to what - are you thinking of WAGI?

I'm not sure what the goal is here or whether it relates to "what the user needs to build the application." Modern toolchains would usually download the SDK automatically so from that point of view I don't think we need to call it out explicitly. But perhaps that's not the concern you're thinking about?

[mikkelhegn]

The list of templates we have today is becoming a little bit of a mixed bag of things: Wasi components (I believe that's a better designation than what I used above, unless we have Wasi components not using SDKs?), WAGI components and then reference components (#898).

It would be good if e.g., spin templates list, spin new and spin add either categorized by these groups (sort or grouped), or a third column was introduced to convey that information to the user. And even better a link to something documenting the template and how to use it.

[itowlson]

The language templates use the Spin or WAGI model according to whether the language supports the component model. I don't really see value in categorising by that axis. If I want to use Swift, I want the Swift template; if I want to use Go, I want the Go template. The meaningful choice is language and trigger: once that's made, the architecture follows.

But it depends on how you see users using the information. For example, when I've generated a component, then it's useful to know whether it's WAGI or Spin, e.g. so I know whether to look at environment variables or headers and what their names are. (This relates to your "how to use it" comment.) But that info should come after spin new, and - like the build toolchain - should be accessible even once the template is long forgotten and a maintenance dev is checking the application out of Git.

I agree a way to surface off-the-shelf components, without having to search through Bring Your Own Code ones, would be useful. I do have work in progress (fine, fine, it's barely started) to provide feedback during list/new/add about where a template can be used (can it be run here, does it support add/new, etc.). This might tangentially relate to that. The original template proposal suggested allowing filtering by language which would also relate; or we could implement a tag system which could subsume language but also other categories.

I feel like we should maybe decouple this from the current "template dependencies" issue or it's going to turn into a scattergun brainstorm thing - perhaps we should isolate it into "where do we document/surface component toolchain requirements" and "where do we document/surface component usage"...?

[mikkelhegn]

What I believe we should achieve with this is when a person, who is educating themselves by exploring Spin using the CLI, will be able to easily identify what a given Spin template gives them in terms of functionality and availability in programming languages. If I'm a developer who prefers writing code in Go, I can easily identify the templates (using spin new, spin add and spin templates list, that are available for Go, sorted by their key features (e.g., type of trigger). I am also able to find a reference to a document (a link), where I can find more information about the specific template (e.g., if it's a pre-built component, a link to the components GitHub repo would be a good example. If it's an http-trigger component, a link to the description of http-triggers would be a good option).

[fibonacci1729]

IIUC during the release-workflow the fastly-cli generates a structured description of various prerequisite / compatibility requirements on language toolchains / how to source developer kits and injects it into the fastly-cli binary. We might consider adopting a similar approach to maintain toolchain compatibility requirements (e.g. MSRV, tinygo required version, etc.). Additionally we might also include the known set of blessed templates the spin cli can by default install in this embedded static file.