Merge pull request #1177 from tpmccallum/migrate-wasm-languages-to-de…

…v-docs

Migrate wasm languages to dev docs

content/wasm-languages/CONTRIBUTING.md

@@ -0,0 +1,59 @@
+date = "2024-02-18T01:01:01Z"
+title = "Contributing"
+description = "Contributing the WebAssembly Language Guide"
+tags = ["wasm", "webassembly"]
+template = "page"
+[extra]
+author = "Fermyon Staff"
+type = "page"
+url = "https://github.com/fermyon/developer/blob/main/content/wasm-languages/CONTRIBUTING.md"
+
+---
+
+We welcome contributors. To make changes or additions, create new pull requests against this repository.
+
+The [content template](https://github.com/fermyon/developer/tree/main/content/wasm-languages/tpl.md) provides the scaffolding for adding a new language. The [About Examples](./about-examples.md) explains how an example should work. (Examples are not required. But when provided, we like to keep them consistent.)
+
+All community members must abide by the [Code of Conduct](https://www.fermyon.com/code-of-conduct)
+
+### Adding New Languages
+
+The guide is arranged to break down languages into three categories:
+
+- Top Languages: This section is reserved for only the languages that trend into the [top RedMonk rankings](https://redmonk.com/sogrady/2021/08/05/language-rankings-6-21/).
+- WebAssembly Languages: These are languages specifically built for WebAssembly. While we love research languages, we do require that languages in this category have reached certain stability levels as well as a moderate amount of usage.
+- Other Notable Languages: This section is the most permissive. Usually, we focus on historically important languages, languages that didn't quite make the top 20, or languages that seem to be gaining momentum.
+
+To add a new language, open a PR that includes a new language page (see [tpl.md](https://github.com/fermyon/developer/tree/main/content/wasm-languages/tpl.md) for a template) and also add the language to either the [webassembly-specific-languages](./webassembly-language-support.md#webassembly-specific-languages) or [other-notable-languages](./webassembly-language-support.md#other-notable-languages) section of the [webassembly-language-support.md](./webassembly-language-support.md)` page. Please adhere to the format we have provided. Uniformity is an important quality of entries.
+
+#### Examples
+
+We have chosen a very specific example, which is explained in `about-examples.md`. Specifically, we want examples that can execute in `wasmtime` (the reference implementation of the Bytecode Alliance and WASI work), and that can run as [Wagi](https://github.com/deislabs/wagi) modules. Wagi is an important testbed for two reasons:
+
+1. Wagi only requires core Wasm and WASI support, and does not require any non-standard host runtime features
+2. Fermyon's goal is to articulate how WebAssembly can run on the cloud, and Wagi is the easiest way to do so
+
+While we appreciate that other runtimes offer their own APIs and features, we do not accept examples that are based on those features.
+
+### Updating Existing Entries
+
+We are always interested in updates to the content on language pages. We do have a few brief guidelines:
+
+- *The pros and cons.* The tone of pros/cons is objective, oriented toward the developer, and friendly in tone. We will request changes on (or close) PRs that take a negative tone or attempt to use the pros/cons to air grievances or get really nit-picky.
+- *Learn More:* Include new references, tutorials, or discussions that focus on compiling the language to WebAssembly or using WebAssembly-specific features in the language.
+    - For example, we would welcome the addition of a link to an article entitled "Compiling a C++ app to WebAssembly".
+    - While the text on the page should focus on core WebAssembly and WASI features, we allow linking to browser, cloud, and specialty projects that support the language on the page.
+- *Examples:* Read the previous section and the [About Examples](./about-examples.md) document.
+
+There are some pieces of information that we are not interested in:
+
+- Whether a language _has a runtime_ for WebAssembly. We are not interested in "embedding a Wasm runtime in C++", for example.
+- Non-language projects (like tools or other runtimes). In the future, we might add a section for these. But for now, the guide is focused exclusively on languages.
+
+## License
+
+The contents of this repository are licensed under the [Creative Commons 4.0 Attribution Share-Alike license](https://creativecommons.org/licenses/by-sa/4.0/legalcode), usually abbreviated _cc4.0-by-sa_.
+
+## Contributing Guide
+
+To learn more about formatting options, testing your new content, previewing your contributions locally before submitting etc. read the [Contributing guide](https://developer.fermyon.com/spin/v2/contributing-docs).

content/wasm-languages/about-examples.md

@@ -0,0 +1,103 @@
+date = "2024-02-18T01:01:01Z"
+title = "About WebAssembly Examples"
+description = "The WebAssembly examples all follow some common patterns. This page explains them"
+template = "page"
+tags = ["webassembly", "examples"]
+[extra]
+author = "Fermyon Staff"  # Use "Fermyon Staff" for general content
+type = "page"
+url = "https://github.com/fermyon/developer/blob/main/content/wasm-languages/about-examples.md"
+
+---
+
+The [Fermyon WebAssembly Language Guide](/wasm-languages/webassembly-language-support) tracks languages that can be executed within a WebAssembly runtime. We do our best to keep things consistent across pages. This page explains how we create our examples.
+
+## The Typical Example
+
+Providing detailed language-specific examples is beyond the scope of the language guide. Instead, we try to provide the following pieces of relevant information:
+
+- How to get the tools necessary to work with the language
+- How to create a simple "Hello World" style program
+- How to compile that program
+- How to execute that program
+
+Our canonical example is to build a simple web page that prints `Hello, World` in plain text. In order to serve it as a web page, we try to write the script using one of two tools:
+
+- [Spin](https://spin.fermyon.dev/), a framework for building WebAssembly-based web applications and microservices.
+- [Wagi](https://github.com/deislabs/wagi), used in older content from before Spin was released. All Wagi applications run on Spin (though you must use a `spin.toml` instead of a `modules.toml`).
+
+For command line examples, the example runs with [wasmtime](https://wasmtime.dev/), which is committed to implementing the WASI specification.
+
+Other runtimes and execution environments are out of the scope of this documentation. However, you may find links to examples in the _Learn More_ section at the bottom of each language page
+
+To that end, the simplest example, written in Swift, looks like this:
+
+```swift
+print("content-type: text/plain\n\n");
+print("Hello, World\n");
+```
+
+When run on `wasmtime`, it should produce output like this:
+
+```console
+$ wasmtime hello.wasm
+content-type: text/plain
+
+Hello, World
+```
+
+When executed on Spin (or Wagi) and accessed via Curl, it should look like this:
+
+```console
+$ curl localhost:3000                                       
+Hello, World
+```
+
+## Libraries, SDKs, and Helpers
+
+Generally, if there is a useful library, SDK, or helper, examples will use the best one. Many times, a language's CGI library can be used with Wagi-style invocations on Spin or Wagi. Additionally, Spin has SDKs for a growing list of languages.
+
+In the end, though, every Wagi executor (on Spin) [uses the same CGI-like mechanism](https://github.com/deislabs/wagi/blob/main/docs/architecture.md) to read a request and write a response.
+
+## Spin Configuration
+
+Newer examples use a `spin.toml` to show how the program is executed with Spin. The generic `spin.toml` looks something like this:
+
+```toml
+spin_manifest_version = 2
+
+[application]
+name = "spin-hello"
+version = "0.1.0"
+authors = ["Fermyon Engineering <[email protected]>"]
+description = "Hello world app."
+
+[[trigger.http]]
+route = "/..."
+component = "spin-hello"
+
+[component.spin-hello]
+source = "target/wasm32-wasi/release/spin_hello.wasm"
+allowed_outbound_hosts = []
+[component.spin-hello.build]
+command = "cargo build --target wasm32-wasi --release"
+watch = ["src/**/*.rs", "Cargo.toml"]
+```
+
+The format and fields are defined in the [official Spin configuration docs](https://developer.fermyon.com/spin/v2/manifest-reference).
+
+The command to build and start a Spin application is `spin build --up`. This will typically start a server on `http://localhost:3000` unless you specify otherwise.
+
+## Wagi Configuration
+
+Older examples us Wagi instead of Spin. They may provide examples that use a `modules.toml` file instead of a `spin.toml` file. A simple example looks like this:
+
+```toml
+[[module]]
+module = "hello.wasm"
+route = "/"
+```
+
+Then we start `wagi` with `wagi -c modules.toml`.
+
+>> If you are interested in contributing to this guide, head on over to [the GitHub repo](https://github.com/fermyon/wasm-languages).