diff --git a/.github/workflows/main.yml b/.github/workflows/main.yml deleted file mode 100644 index 0305f7f32..000000000 --- a/.github/workflows/main.yml +++ /dev/null @@ -1,47 +0,0 @@ -name: CI -on: [push, pull_request] - -jobs: - test: - name: Test witx tools - runs-on: ${{ matrix.os }} - strategy: - matrix: - os: [ubuntu-latest, macos-latest, windows-latest] - steps: - - uses: actions/checkout@v1 - - name: Install Rust (rustup) - shell: bash - run: rustup update stable --no-self-update && rustup default stable - if: matrix.os != 'macos-latest' - - name: Install Rust (macos) - run: | - curl https://sh.rustup.rs | sh -s -- -y - echo "$HOME/.cargo/bin" >> $GITHUB_PATH - if: matrix.os == 'macos-latest' - - run: cargo fetch - working-directory: tools/witx - - run: cargo test --all - working-directory: tools/witx - - validate: - name: Validate witx files and docs - runs-on: ubuntu-latest - steps: - - uses: actions/checkout@v1 - - name: Install Rust (rustup) - shell: bash - run: rustup update stable --no-self-update && rustup default stable - - - name: Check that repository docs reflect witx - run: ./tools/repo_docs.sh --check - - rustfmt: - name: Rustfmt - runs-on: ubuntu-latest - steps: - - uses: actions/checkout@v1 - - name: Install Rust - run: rustup update stable && rustup default stable && rustup component add rustfmt - - run: cargo fmt --all -- --check - working-directory: tools/witx diff --git a/.gitignore b/.gitignore deleted file mode 100644 index c0476d12f..000000000 --- a/.gitignore +++ /dev/null @@ -1,11 +0,0 @@ -*.bk -*.swp -*.swo -*.swx -tags -target -Cargo.lock -.*.rustfmt -rusty-tags.* -*~ -\#*\# diff --git a/Contributing.md b/Contributing.md index 1cc607fa4..f89499afe 100644 --- a/Contributing.md +++ b/Contributing.md @@ -1,4 +1,4 @@ -# Contributing to WebAssembly +# Contributing to WASI Interested in participating? Please follow [the same contributing guidelines as the design repository][]. @@ -6,3 +6,56 @@ Interested in participating? Please follow [the same contributing guidelines as the design repository]: https://github.com/WebAssembly/design/blob/master/Contributing.md Also, please be sure to read [the README.md](README.md) for this repository. + +## Championing a Proposal + +If you want to champion a new proposal, here's what you need to do in each phase: + +### Phase 0: Gauge interest + +You have an idea for an API. To see whether others are interested in pursuing the idea, you should work up a rough description of the API and post it somewhere that is publicly visible. This could be in the WASI issue queue, or in a gist or as its own repo. You can use the [proposal template] if you like, but it's not required in this phase. + +Once you've done this, you can optionally have the subgroup discuss the idea by adding a discussion item to the [WASI meeting agenda]. + +Once you feel ready, you can add a vote to the [WASI meeting agenda] to move to the next stage. + +### Phase 1: Write spec text + +At this point, the WASI SG chair will create a new repo for the proposal in the WebAssembly GitHub org. This will follow the conventions of the [proposal template]. If you have any questions about how to fill in the spec template, you can reach out to the WASI SG chair. + +As part of moving to the next phase, the champions need to define the acceptance criteria for Phase 4. This is because WASI includes APIs that cover a diversity of different domains and use cases, so the . + +Some examples of potential criteria: + +- multiple independent production implementations +- implementations on multiple host platforms +- polyfill implementations +- bindings in toolchains and libraries + +Note: portability requirements may vary between proposals, as not all features will necessarily make sense in all host environments. + +With all this in place, you can add a vote to [WASI meeting agenda] to move to the next stage. + +### Phase 2: Work with implementers to prototype and refine the design + +At this point, you should be prototyping the API to make sure it works in practice, and you should develop a test suite which can be used by other implementations to validate their spec compliance. + +Once the implmentation has stabilized, it's again time to add a vote to [WASI meeting agenda] to move to the next stage. + +### Phase 3: Validate the design through multiple implmentations + +At this point, you'll need to get more implementers involved. How many implementations you need depends on the Phase 4 acceptance criteria that you set in Phase 2. + +You may need to make changes in response to implementer feedback, but we expect the API to be pretty stable by this point. If implementors uncover especially challenging design issues, the proposal may be sent back to Phase 2 for more development. + +Once the implementations are in place, you can add the final WASI SG vote to [WASI meeting agenda]. After this, the proposal advances to a vote in the broader WebAssembly CG. + +### Phases 4 & 5: Push it over the finish line + +The specific process in Phases 4 and 5 will be determined when we have a proposal ready for them. + +Note: While we mostly follow the [WebAssembly CG's Phase Process], the requirements around Web VM implementation, formal notation and the reference interpreter don't apply in the context of WASI. + +[proposal template]: https://github.com/WebAssembly/wasi-proposal-template +[WASI meeting agenda]: https://github.com/WebAssembly/meetings/tree/main/wasi +[WebAssembly CG's Phase Process]: https://github.com/WebAssembly/meetings/blob/main/process/phases.md diff --git a/Proposals.md b/Proposals.md new file mode 100644 index 000000000..e9754903a --- /dev/null +++ b/Proposals.md @@ -0,0 +1,86 @@ +# WASI proposals + +WASI APIs are developed as proposals. These proposals go through 5 phases of development (following the [WebAssembly CG's Phase Process]). + +You can learn more about contributing new proposals (and other ways to contribute) in our [Contributing] guide. + +[WebAssembly CG's Phase Process]: https://github.com/WebAssembly/meetings/blob/main/process/phases.md +[Contributing]: https://github.com/WebAssembly/WASI/blob/main/Contributing.md + +## Active Proposals + +### Phase 5 - The Feature is Standardized (WG) + +| Proposal | Champion | Versions | +| ------------------------------------------------------------------------------ | -------------------------------------- | -------- | + +### Phase 4 - Standardize the Feature (WG) + +| Proposal | Champion | Versions | +| ------------------------------------------------------------------------------ | -------------------------------------- | -------- | + +### Phase 3 - Implementation Phase (CG + WG) + +| Proposal | Champion | Versions | +| ------------------------------------------------------------------------------ | -------------------------------------- | -------- | + +### Phase 2 - Proposed Spec Text Available (CG + WG) + +| Proposal | Champion | Versions | +| ------------------------------------------------------------------------------ | -------------------------------------- | -------- | +| [I/O][wasi-io] | Dan Gohman | | +| [Filesystem][wasi-filesystem] | Dan Gohman | | +| ["Classic" Command-Line][wasi-classic-command] (Legacy, to be deprecated in Q4 2022)| Dan Gohman | | +| [Clocks][wasi-clocks] | Dan Gohman | | +| [Random][wasi-random] | Dan Gohman | | +| [Handle Index][wasi-handle-index] | Dan Gohman | | +| [Poll][wasi-poll] | Dan Gohman | | +| [Machine Learning (wasi-nn)][wasi-nn] | Andrew Brown and Mingqiu Sun | | + +### Phase 1 - Feature Proposal (CG) + +| Proposal | Champion | Versions | +| ------------------------------------------------------------------------------ | -------------------------------------- | -------- | +| [Crypto][wasi-crypto] | Frank Denis and Daiki Ueno | | +| [HTTP][wasi-http] | Piotr Sikora | | +| [Parallel][wasi-parallel] | Andrew Brown | | + +### Phase 0 - Pre-Proposal (CG) + +**Note:** The pre-proposal phase is simply meant as a way to share ideas. This means that there may be overlap between pre-proposals. It also means that the WASI subgroup has not yet decided that the pre-proposal is in scope for WASI. + +| Proposal | Champion | Versions | +| ------------------------------------------------------------------------------ | -------------------------------------- | -------- | +| [singlestore-labs/wasi-data][wasi-data] | Bailey Hayes | | +| [proxy-wasm/spec][wasi-proxy-wasm] (will advance as multiple, smaller proposals) | Piotr Sikora | | +| [badeend/WASI-Networking][wasi-networking] | Dave Bakker | + +## Versioning + +Once a proposal reaches Phase 3, we expect the champions to start creating releases, following the conventions of semantic versioning (semver). Releases for active proposals are linked in the chart above. + +Proposals remain in the 0.x semver range until they reach Phase 5 and are fully standardized. At that point, a 1.0 release should be made available. + +For some APIs, it makes sense to add new features after the API itself has reached Phase 5. These feature additions should go through the same standardization process. Once they have reached Phase 5, the minor version number of the release should be incremented. + +Some APIs may require backwards-incompatible changes over time. In these cases, we allow proposals to increment the major version number _only if_ the old API can be implmented in terms of the new API. As part of the new version, champions are expected to provide a tool that enables this backwards-compatibility. If that is not possible, then a new API proposal with a new name should be started. The original API can then be deprecated over time if it makes sense to do so. + +[WebAssembly CG Phases process]: https://github.com/WebAssembly/meetings/blob/master/process/phases.md +[witx]: https://github.com/WebAssembly/WASI/blob/master/docs/witx.md +[ephemeral/snapshot/old process]: https://github.com/WebAssembly/WASI/blob/master/phases/README.md + +[wasi-clocks]: https://github.com/WebAssembly/wasi-clocks +[wasi-classic-command]: https://github.com/WebAssembly/wasi-classic-command +[wasi-crypto]: https://github.com/WebAssembly/wasi-crypto +[wasi-data]: https://github.com/singlestore-labs/wasi-data +[wasi-filesystem]: https://github.com/WebAssembly/wasi-filesystem +[wasi-io]: https://github.com/WebAssembly/wasi-io +[wasi-misc]: https://github.com/WebAssembly/wasi-misc +[wasi-nn]: https://github.com/WebAssembly/wasi-nn +[wasi-proxy-wasm]: https://github.com/proxy-wasm/spec +[wasi-random]: https://github.com/WebAssembly/wasi-random +[wasi-handle-index]: https://github.com/WebAssembly/wasi-handle-index +[wasi-http]: https://github.com/WebAssembly/wasi-http +[wasi-parallel]: https://github.com/WebAssembly/wasi-parallel +[wasi-poll]: https://github.com/WebAssembly/wasi-poll +[wasi-networking]: https://github.com/badeend/WASI-Networking diff --git a/README.md b/README.md index 976972ef1..0bdaf3af4 100644 --- a/README.md +++ b/README.md @@ -4,23 +4,159 @@ ![WASI](WASI.png) -This repository is for the WebAssembly System Interface (WASI) Subgroup of the -[WebAssembly Community Group]. It includes: - - [charter]: describes the goals, scope and deliverables of the group - - [docs]: learn more about WASI - - [meetings]: schedules and agendas for video conference and in-person meetings - - [phases]: the current WASI specifications - - [proposals]: the status of each new specification proposal - -[charter]: Charter.md -[docs]: docs/README.md -[meetings]: https://github.com/WebAssembly/meetings/tree/master/wasi -[phases]: phases/README.md -[proposals]: docs/Proposals.md -[WebAssembly Community Group]: https://www.w3.org/community/webassembly/ - -### Contributing - -The [issue tracker] is the place to ask questions, make suggestions, and start discussions. - -[issue tracker]: https://github.com/WebAssembly/WASI/issues +The WebAssembly System Interface is not a monolithic standard system interface, +but is instead a modular collection of standardized APIs. None of the APIs are +required to be implemented to have a compliant runtime. Instead, host +environments can choose which APIs make sense for their use cases. + +--- +## Important Note: WASI is in transition + +WASI is transitioning away from the `witx` format and its early experimental ABI. We are transitioning to Interface Types using the `wit` format and the canonical ABI. + +All new API proposals should use the new format and the new repo structure that is shown in the [proposal template](https://github.com/WebAssembly/wasi-proposal-template). + +Some APIs can not yet be supported in the `wit` format. The advancement of these proposals will be unblocked with work that is ongoing: + +- Proposals that require async/streams are expected to be unblocked in early Q2 2022 +- Proposals that depend on libc are expected to be unblocked by work in `wasi-libc` and elsewhere. Until then, implementers of these APIs should continue to use the snapshots in this repo, which use the `witx` format. We will provide updates on the progress of this work in the bi-weekly meetings. + +--- + +## Find the APIs + +Development of each API happens in its own repo, which you can access +from the [proposals list](Proposals.md). + +This repo is for general discussion, as well as documenting how we work +and high-level goals. + +## Propose a new API + +If you would like to create a new proposal, get started with our +[Contributing guide](Contributing.md). + +## WASI High Level Goals + +(In the spirit of [WebAssembly's High-Level Goals] +(https://github.com/WebAssembly/design/blob/master/HighLevelGoals.md).) + +1. Define a set of portable, modular, runtime-independent, and + WebAssembly-native APIs which can be used by WebAssembly code to interact + with the outside world. These APIs preserve essential sandboxed nature of + WebAssembly through a [Capability-based] API design. +2. Specify and implement incrementally. Start with a Minimum Viable Product + (MVP), then adding additional features, prioritized by feedback and + experience. +3. Supplement API designs with documentation and tests, and, when feasible, + reference implementations which can be shared between wasm engines. +4. Make a great platform: + * Work with WebAssembly tool and library authors to help them provide + WASI support for their users. + * When being WebAssembly-native means the platform isn't directly + compatible with existing applications written for other platforms, + design to enable compatibility to be provided by tools and libraries. + * Allow the overall API to evolve over time; to make changes to API + modules that have been standardized, build implementations of them + using libraries on top of new API modules to provide compatibility. + +[Capability-based]: https://en.wikipedia.org/wiki/Capability-based_security + +## WASI Design Principles + +### Capability-based security + +WASI is built using capability-based security principles. Access to +external resources is always represented by *handles*, which are special +values that are *unforgeable*, meaning there's no way to coerce an +arbitrary integer or other type of value into a handle. WASI is also +aiming to have no *ambient authorities*, meaning that there should +be no way to request a handle purely by providing a string or other +user-controlled identifier providing the name of a resource. With these +two properties, the only ways to obtain access to resources are to be +explicitly given handles, or to perform operations on handles which +return new handles. + +Note that this is a different sense of "capability" than [Linux +capabilities](http://man7.org/linux/man-pages/man7/capabilities.7.html) +or the withdrawn [POSIX +capabilities](https://archive.org/details/posix_1003.1e-990310), which +are per-process rather than per-resource. + +The simplest representation of handles are values of [reference +type](https://github.com/WebAssembly/reference-types). References in +wasm are inherently unforgeable, so they can represent handles directly. + +Some programming languages operate primarily within linear memory, +such as C, C++, and Rust, and there currently is no easy way for +these languages to use references in normal code. And even if it does +become possible, it's likely that source code will still require +annotations to fully opt into references, so it won't always be +feasible to use. For these languages, references are stored in a +[table](https://webassembly.github.io/spec/core/bikeshed/index.html#tables%E2%91%A0) +called a *c-list*. Integer indices into the table then identify +resources, which can be easily passed around or stored in memory. In +some contexts, these indices are called *file descriptors* since they're +similar to what POSIX uses that term for. There are even some tools, +such as wasm-bindgen, which make this fairly easy. (Internally, tools +and engines don't always use actual WebAssembly tables to do this, +however those are implementation details. Conceptually, they work as if +they had tables.) + +Integer indices are themselves forgeable, however a program can only +access handles within the c-list it has access to, so isolation can still +be achieved, even between libraries which internally use integer indices, +by witholding access to each library's c-list to the other libraries. +Instances can be given access to some c-lists and not others, or even +no c-lists at all, so it's still possible to establish isolation between +instances. + +Witx-specified APIs use a special `handle` keyword to mark parameters +and return values which are handles. In the short term, these are +lowered to integer indices, with an implied table, so that the APIs +can be easily used from C and similar languages today. Once [interface +types](https://github.com/WebAssembly/interface-types) is +ready, we expect to make use of them to provide APIs which can be used +either from languages using references or from languages using integer +indices, with tables being used and managed automatically. + +### Interposition + +Interposition in the context of WASI interfaces is the ability for a +Webassembly instance to implement a given WASI interface, and for a +consumer WebAssembly instance to be able to use this implementation +transparently. This can be used to adapt or attenuate the functionality +of a WASI API without changing the code using it. + +In WASI, we envision interposition will primarily be configured +through the mechanisms in the module linking' [link-time virtualization +](https://github.com/WebAssembly/module-linking/blob/master/proposals/module-linking/Explainer.md#link-time-virtualization). +Imports are resolved when a module is instantiated, which may happen +during the runtime of a larger logical application, so we can support +interposition of WASI APIs without defining them in terms of explicit +dynamic dispatch mechanisms. + +Interposition is sometimes referred to as "virtualization", however we +use "interposition" here because the word "virtualization" has several +related meanings. + +### Compatibility + +Compatibility with existing applications and libraries, as well as +existing host platforms, is important, but will sometimes be in conflict +with overall API cleanliness, safety, performance, or portability. +Where practical, WASI seeks to keep the WASI API itself free of +compatibility concerns, and provides compatibility through libraries, +such as WASI libc, and tools. This way, applications which don't require +compatibility for compatibility' sake aren't burdened by it. + +### Portability + +Portability is important to WASI, however the meaning of portability +will be specific to each API. + +WASI's modular nature means that engines don't need to implement every +API in WASI, so we don't need to exclude APIs just because some host +environments can't implement them. We prefer APIs which can run across +a wide variety of engines when feasible, but we'll ultimately decide +whether something is "portable enough" on an API-by-API basis. diff --git a/docs/DesignPrinciples.md b/docs/DesignPrinciples.md deleted file mode 100644 index df82c8692..000000000 --- a/docs/DesignPrinciples.md +++ /dev/null @@ -1,291 +0,0 @@ -# WASI Design Principles - -## Capability-based security - -WASI is built using capability-based security principles. Access to -external resources is always represented by *handles*, which are special -values that are *unforgeable*, meaning there's no way to coerce an -arbitrary integer or other type of value into a handle. WASI is also -aiming to have no *ambient authorities*, meaning that there should -be no way to request a handle purely by providing a string or other -user-controlled identifier providing the name of a resource. With these -two properties, the only ways to obtain access to resources are to be -explicitly given handles, or to perform operations on handles which -return new handles. - -Note that this is a different sense of "capability" than [Linux -capabilities](http://man7.org/linux/man-pages/man7/capabilities.7.html) -or the withdrawn [POSIX -capabilities](https://archive.org/details/posix_1003.1e-990310), which -are per-process rather than per-resource. - -The simplest representation of handles are values of [reference -type](https://github.com/WebAssembly/reference-types). References in -wasm are inherently unforgeable, so they can represent handles directly. - -Some programming languages operate primarily within linear memory, -such as C, C++, and Rust, and there currently is no easy way for -these languages to use references in normal code. And even if it does -become possible, it's likely that source code will still require -annotations to fully opt into references, so it won't always be -feasible to use. For these languages, references are stored in a -[table](https://webassembly.github.io/spec/core/bikeshed/index.html#tables%E2%91%A0) -called a *c-list*. Integer indices into the table then identify -resources, which can be easily passed around or stored in memory. In -some contexts, these indices are called *file descriptors* since they're -similar to what POSIX uses that term for. There are even some tools, -such as wasm-bindgen, which make this fairly easy. (Internally, tools -and engines don't always use actual WebAssembly tables to do this, -however those are implementation details. Conceptually, they work as if -they had tables.) - -Integer indices are themselves forgeable, however a program can only -access handles within the c-list it has access to, so isolation can still -be achieved, even between libraries which internally use integer indices, -by witholding access to each library's c-list to the other libraries. -Instances can be given access to some c-lists and not others, or even -no c-lists at all, so it's still possible to establish isolation between -instances. - -Witx-specified APIs use a special `handle` keyword to mark parameters -and return values which are handles. In the short term, these are -lowered to integer indices, with an implied table, so that the APIs -can be easily used from C and similar languages today. Once [interface -types](https://github.com/WebAssembly/interface-types) and [type -imports](https://github.com/WebAssembly/proposal-type-imports) are -ready, we expect to make use of them to provide APIs which can be used -either from languages using references or from languages using integer -indices, with tables being used and managed automatically. - -## WASI's Scope - -WASI started out with a very POSIX-like API, however WASI will grow to -include many APIs that are outside of the scope of POSIX. WASI is a -forum for cooperatively designing APIs, along with a W3C CG Subgroup for -eventually standardizing them. - -For example, WASI may include high-level network APIs, such as APIs for -HTTP. This is outside the scope of POSIX, and while some WebAssembly -engines are very interested in implementing it natively, others will -find it too complex and high-level. But one of the great things about -WebAssembly is that there's no syscall instruction, so "syscalls" -in WebAssembly are just calls to imported functions, which could be -native functions provided by the runtime, or could be other WebAssembly -modules. We expect to leverage this capability to provide polyfill -implementations of things like high-level network APIs on top of -low-level APIs, such as a raw socket API, so that engines which wish to -keep things simple and just implement the low-level socket APIs can do -so. - -WASI also aims to include domain-specific APIs, such as -database, blockchain, or specialized APIs for embedded -systems. Another key building block for WASI is [optional -imports](https://github.com/WebAssembly/WASI/blob/main/design/optional-imports.md), -which give applications the ability to dynamically test for the -availability of APIs. - -## Relationship to POSIX - -POSIX specifies a C API rather than an actual system call ABI, with -the expectation that implementation details will differ at the system -call level. In the same way, the primary vehicle for WASI's POSIX -compatibility is libraries such as WASI libc, rather than the WASI API -itself. WASI libc provides a wide range of POSIX-compatible APIs. - -In the parts of WASI which do correspond to POSIX functionality, WASI -follows POSIX when it doesn't conflict with WASI's other goals. And, -we consult POSIX even when we aren't strictly following it. POSIX is -valuable for several reasons: POSIX represents a large body of lessons -learned about systems programming, portability, and robustness. POSIX -is available on many existing hosts that we want to port WASI to. And, -there's a large amount of application code that we want to port to WASI -that uses POSIX-style interfaces. - -All this said, maximal POSIX conformance is not WASI's primary goal. -Some reasons include: - - - `fork` -- It's not that we can't make `fork` work -- we can, it's -that `fork` carries with it the assumption of copy-on-write memory -optimizations which won't be feasible in many environments where we -want to run WASI, such as nano-processes. There may eventually be -compatibility layers that provide `fork` to help people port POSIX -code to WASI, however there's a difference between providing `fork` as -an optional compatibility layer and having it as a cornerstone of an -ecosystem as it is in POSIX. - - And when we take `fork` out of the focus, it changes the way we think -about a lot of other things, such as `execve`, `dup`, `fcntl`-style file -locking, and even processes. - - - Users and Groups -- POSIX's Users and Groups subsystem are -notoriously inflexible, to the point where much of the computing world -has moved to using containers and VMs and other forms of single-user -environments because traditional multi-user OS functionality doesn't do -what's needed. - - And, when running untrusted code, it isn't desirable to run it as a -user's normal identity, because it shouldn't inherit all of the rights a -user has, but it also doesn't help to run it as user "nobody", as it's -still useful to grant it some rights and restrict it from others. - - And, we are aiming for portability to OS's which don't have -POSIX-style users and groups, and systems which don't have OS's at all. - - - Asynchronous signals and handlers -- The core WebAssembly semantics -don't support these, which would need to change before WASI could -consider supporting them, and there are currently no proposals for doing -so. In POSIX, some interfaces are designed with the assumption that -signals like `SIGPIPE`, `SIGALRM`, `SIGCHLD`, `SIGIO` and others exist -and can cover certain situations, so in the absence of these signals, -those interfaces won't always make sense. - - - Shared filesystem views - One of the unique capabilities WebAssembly -brings to the table is the possibility of shared-nothing linking between -applications and libraries. Shared-nothing means that all communication -is via explicit calls, and the libraries don't share an address space -or any other implicit shared state. But if we run both sides within -the same filesystem view, that would give them a large body of shared -state. Union mounts, mandatory access control systems, user namespaces, -and other techniques can help, but often require complex configuration, -heavy-weight boundaries, and sometimes even admin privileges to set up. - -This has wide-ranging implications. Much of POSIX is oriented around -passing around strings, whether through command-line arguments, -environment variables, or paths embedded in files, with the assumption -that there's a shared filesystem view between components. As we said -above, we're de-emphasizing strings, which dovetails with de-emphasizing -shared filesystem views. Instead of having shared state and passing -around values which identify things within the shared state, WASI -prefers to share as little as possible, and use handles which represent -the things which need to be shared. - -Compatibility with existing host environments and applications is -important, and we have put a lot of work into WASI libc to provide POSIX -compatibility and support existing applications. There's a lot more work -that can be done, and a lot more we can do to improve compatibility and -user convenience. We're continuing to make progress -- and users are -encouraged to [file bugs](https://github.com/WebAssembly/WASI/issues) -when they find things that don't work or are awkward. This approach -supports existing applications, while also supporting applications and -libraries willing to opt in to enable stronger and more fine-grained -security properties than are possible in regular POSIX. - -For example, a typical POSIX-style API might include a function that -accepts a file name to open. That requires the implementation to -have a filesystem view, and to have appropriate permissions within -that filesystem view. WASI APIs typically prefer to instead have a -function which accepts a handle for an already-open file. That way, the -implementation doesn't need a filesystem view, or permissions within -the filesystem. It doesn't even need to care whether there even is a -filesystem. When needed, compatibility with POSIX-style APIs is then -provided as a thin layer on top implementing a simple name-to-handle -mapping. - -We recognize that this approach has trade-offs. It often does take more -work to design and implement the compatibility layers needed to support -existing applications than if we just made WASI always expose -POSIX-style APIs directly. It will take more work to port existing -libraries to work with shared-nothing linking. And, even when we do have -compatibility mechanisms, they aren't always the most locally optimal -ones. The compatibility layer overhead is usually quite modest, but it -is present. - -However, libraries built to use shared-nothing linking can be used in -more circumstances, because you don't have to have the trust implied by -a shared filesystem view, or the complexity of configuring filesystem -rules for each library. With a better story for libraries and tools to -work together in cooperation with the sandbox, we can build a stronger -ecosystem which makes up for the downsides in the long run. - -## Relationship to the Web - -It is possible to run WASI code on the Web with the help of polyfills, -however WASI isn't limited to APIs which run well or are easy or -efficient to polyfill on the Web. - -That said, where other considerations don't interfere, WASI should use -existing Web standards and work with Web standardization efforts rather -than gratuitously inventing its own versions of them and/or duplicating -efforts. - -When using Web standards, WASI APIs should be careful to avoid depending -on JavaScript in the engine in APIs where it isn't essential. - -## Use WebAssembly standards and proposals - -WASI should align with and build on WebAssembly standards and proposals -where applicable. - -For example, WASI seeks to align with and build on [interface -types](https://github.com/WebAssembly/interface-types), [multiple -return values](https://github.com/WebAssembly/multi-value/), [reference -types](https://github.com/WebAssembly/reference-types), [type -imports](https://github.com/WebAssembly/proposal-type-imports), and -more. As of this writing, some of these are early-stage proposals, so -we're not actually depending on them yet, however we are carefully -aligning with them so that we'll be ready when they are. - -As another example, WASI's -[witx](https://github.com/WebAssembly/WASI/blob/main/docs/witx.md) -file format is designed to be a -straightforward superset of the [module linking -proposal](https://github.com/WebAssembly/module-linking/blob/master/proposals/module-linking/Explainer.md)'s -.wit format and the [annotations -proposal](https://github.com/WebAssembly/annotations/)'s annotation -syntax. - -## Interposition - -Interposition in the context of WASI interfaces is the ability for a -Webassembly instance to implement a given WASI interface, and for a -consumer WebAssembly instance to be able to use this implementation -transparently. This can be used to adapt or attenuate the functionality -of a WASI API without changing the code using it. - -In WASI, we envision interposition will primarily be configured -through the mechanisms in the module linking' [link-time virtualization -](https://github.com/WebAssembly/module-linking/blob/master/proposals/module-linking/Explainer.md#link-time-virtualization). -Imports are resolved when a module is instantiated, which may happen -during the runtime of a larger logical application, so we can support -interposition of WASI APIs without defining them in terms of explicit -dynamic dispatch mechanisms. - -Interposition is sometimes referred to as "virtualization", however we -use "interposition" here because the word "virtualization" has several -related meanings. - -## Compatibility - -Compatibility with existing applications and libraries, as well as -existing host platforms, is important, but will sometimes be in conflict -with overall API cleanliness, safety, performance, or portability. -Where practical, WASI seeks to keep the WASI API itself free of -compatibility concerns, and provides compatibility through libraries, -such as WASI libc, and tools. This way, applications which don't require -compatibility for compatibility' sake aren't burdened by it. - -## Portability - -Portability is important to WASI, however the meaning of portability -will be specific to each API. - -WASI's modular nature means that engines don't need to implement every -API in WASI, so we don't need to exclude APIs just because some host -environments can't implement them. We prefer APIs which can run across -a wide variety of engines when feasible, but we'll ultimately decide -whether something is "portable enough" on an API-by-API basis. - -## Strings - -WASI in general de-emphasizes strings in areas where typed interfaces -can be sufficient, and especially when the strings would be serving as -identifiers in a global shared resource pool. - -Where strings are passed through APIs, WASI will use [interface -types](https://github.com/WebAssembly/interface-types) to manage the -strings. - -Where string encodings are exposed, WASI prefers to use UTF-8 -encodings for strings, and to provide explicit length values -rather than NUL-terminated strings, (as [WebAssembly itself -does](https://webassembly.github.io/spec/core/bikeshed/index.html#binary-utf8)). diff --git a/docs/HighLevelGoals.md b/docs/HighLevelGoals.md deleted file mode 100644 index e871cfd08..000000000 --- a/docs/HighLevelGoals.md +++ /dev/null @@ -1,25 +0,0 @@ -# WASI High-Level Goals - -(In the spirit of [WebAssembly's High-Level Goals](https://github.com/WebAssembly/design/blob/master/HighLevelGoals.md).) - -1. Define a portable, modular, runtime-independent, and WebAssembly-native API - to serve as a system interface which can be used by WebAssembly code to - interact with the outside world, that preserves the essential sandboxed - nature of WebAssembly through a [Capability-based] API design. -2. Specify and implement incrementally: - * Start with a Minimum Viable Product (MVP) for the standard, covering - basic API versioning, feature detection, and namespacing. - * Then add additional features, prioritized by feedback and experience. -3. Supplement API designs with documentation and tests, and, when feasible, - reference implementations which can be shared between wasm engines. -4. Make a great platform: - * Work with WebAssembly tool and library authors to help them provide - WASI support for their users. - * When being WebAssembly-native means the platform isn't directly - compatible with existing applications written for other platforms, - build tools and libraries to provide compatibility. - * Allow the overall API to evolve over time; to make changes to API - modules that have been standardized, build implementations of them - using libraries on top of new API modules to provide compatibility. - -[Capability-based]: https://en.wikipedia.org/wiki/Capability-based_security diff --git a/docs/Process.md b/docs/Process.md deleted file mode 100644 index 3b4affc3c..000000000 --- a/docs/Process.md +++ /dev/null @@ -1,37 +0,0 @@ -# WASI Standardization Process - -WASI follows the [WebAssembly CG Phases process], with the following adaptations: - - - Entry into Stage 2 requires [witx] specifications. - - - Starting in Stage 2, proposals may follow WASI's [ephemeral/snapshot/old] process - to provide a balance between the need for stability so that toolchains and engines - can sync up, and the need for evolution. - - - The Phase 4's entry requirements for "Two or more Web VMs implement the feature", - "At least one toolchain implements the feature", and "The formalization and the - reference interpreter are usually updated (though these two can be done as part - of step 3 at the Working Group chair's discretion)." are waived. - - In their place, as an additional entry requirement into Phase 2, champion(s) must - include a set of entry criteria into Phase 4 in their proposal, which the Subgroup - will vote on as part of Phase 2 approval. - - Phase 4 criteria will vary depending on the API and its expected use cases, - but may include things like multiple independent production implementations, - implementations on multiple host platforms, polyfill implementations, and - bindings in toolchains and libraries. Note that, portability requirements may - vary between proposals, as not all features will necessarily make sense in all - host environments. - - - The specific process in Phases 4 and 5 will be determined when we have a - proposal ready for them. - - - Requirements around the reference interpreter don't apply. - - - WASI proposals don't require formal notation. Formal notation may be used in the - documentation of a feature, but it isn't expected to be practical for all APIs. - -[WebAssembly CG Phases process]: https://github.com/WebAssembly/meetings/blob/master/process/phases.md -[witx]: https://github.com/WebAssembly/WASI/blob/master/docs/witx.md -[ephemeral/snapshot/old process]: https://github.com/WebAssembly/WASI/blob/master/phases/README.md diff --git a/docs/Proposals.md b/docs/Proposals.md deleted file mode 100644 index 2400d711f..000000000 --- a/docs/Proposals.md +++ /dev/null @@ -1,72 +0,0 @@ -# WASI proposals - -This page is under construction. The intent is to follow the CG's -[proposals page], but adapted for [WASI]. Some of the proposals predate our -adoption of this process and so don't fit exactly into the defined phases, -however our intention is to align them going forward. - -[WASI]: https://github.com/WebAssembly/WASI -[proposals page]: https://github.com/WebAssembly/proposals/blob/master/README.md - -## Active proposals - -Proposals follow [this process document](https://github.com/WebAssembly/WASI/blob/main/docs/Process.md). - -### Phase 4 - Standardize the Feature (WG) - -| Proposal | Champion | -| ------------------------------------------------------------------------------ | -------------------------------------- | - -### Phase 3 - Implementation Phase (CG + WG) - -| Proposal | Champion | -| ------------------------------------------------------------------------------ | -------------------------------------- | - -### Phase 2 - Proposed Spec Text Available (CG + WG) - -| Proposal | Champion | -| ------------------------------------------------------------------------------ | -------------------------------------- | -| [I/O][wasi-io] | Dan Gohman | -| [Filesystem][wasi-filesystem] | Dan Gohman | -| ["Classic" Command-Line][wasi-classic-command] | Dan Gohman | -| [Clocks][wasi-clocks] | Dan Gohman | -| [Random][wasi-random] | Dan Gohman | -| [Handle Index][wasi-handle-index] | Dan Gohman | -| [Poll][wasi-poll] | Dan Gohman | -| [Machine Learning (wasi-nn)][wasi-nn] | Andrew Brown and Mingqiu Sun | - -### Phase 1 - Feature Proposal (CG) - -| Proposal | Champion | -| ------------------------------------------------------------------------------ | -------------------------------------- | -| [Crypto][wasi-crypto] | Frank Denis and Daiki Ueno | -| [HTTP][wasi-http] | Piotr Sikora | -| [Parallel][wasi-parallel] | Andrew Brown | - -### Phase 0 - Pre-Proposal (CG) - -| Proposal | Champion | -| ------------------------------------------------------------------------------ | -------------------------------------- | -| [Data][wasi-data] | Bailey Hayes | -| [proxy-wasm][wasi-proxy-wasm] (will advance as multiple, smaller proposals) | Piotr Sikora | -| [Networking][wasi-networking] | Dave Bakker | - -### Contributing new proposals - -Please see [Contributing to WebAssembly](https://github.com/WebAssembly/WASI/blob/master/Contributing.md) for the most up-to-date information on contributing proposals to standard. - -[wasi-clocks]: https://github.com/WebAssembly/wasi-clocks -[wasi-classic-command]: https://github.com/WebAssembly/wasi-classic-command -[wasi-crypto]: https://github.com/WebAssembly/wasi-crypto -[wasi-data]: https://github.com/singlestore-labs/wasi-data -[wasi-filesystem]: https://github.com/WebAssembly/wasi-filesystem -[wasi-io]: https://github.com/WebAssembly/wasi-io -[wasi-misc]: https://github.com/WebAssembly/wasi-misc -[wasi-nn]: https://github.com/WebAssembly/wasi-nn -[wasi-proxy-wasm]: https://github.com/proxy-wasm/spec -[wasi-random]: https://github.com/WebAssembly/wasi-random -[wasi-handle-index]: https://github.com/WebAssembly/wasi-handle-index -[wasi-http]: https://github.com/WebAssembly/wasi-http -[wasi-parallel]: https://github.com/WebAssembly/wasi-parallel -[wasi-poll]: https://github.com/WebAssembly/wasi-poll -[wasi-networking]: https://github.com/badeend/WASI-Networking diff --git a/docs/README.md b/docs/README.md deleted file mode 100644 index bb6d81b25..000000000 --- a/docs/README.md +++ /dev/null @@ -1,15 +0,0 @@ -# Documentation - -WASI documentation includes: - - [Overview](WASI-overview.md): provides an introduction to WASI and its history - - [Goals](HighLevelGoals.md): a succinct list of WASI's design goals - - [Design Principles](DesignPrinciples.md): discusses details on the principles of capability-based security, scope, - POSIX/Web, etc. - - [WITX](witx.md): an introduction to the WITX specification language - - [Process](Process.md): describes how to move a WASI proposal in to the specification - - [Proposals](Proposals.md): lists the current WASI proposals by phase - -Additionally, here are some links that may be helpful in understanding WASI: - - The blog post introducing WASI: [Standardizing WASI: A system interface to run WebAssembly outside the web](https://hacks.mozilla.org/2019/03/standardizing-wasi-a-webassembly-system-interface/) - - The [wasi.dev](https://wasi.dev) web site includes links to more information about WASI, including how to get started using it - - This repository's [issue tracker](https://github.com/WebAssembly/WASI/issues) \ No newline at end of file diff --git a/docs/WASI-overview.md b/docs/WASI-overview.md deleted file mode 100644 index faabc2eff..000000000 --- a/docs/WASI-overview.md +++ /dev/null @@ -1,147 +0,0 @@ -# WASI: WebAssembly System Interface - -WebAssembly System Interface, or WASI, is a family of APIs for WebAssembly -being designed and standardized through the WASI Subgroup of the W3C -WebAssembly Commmunity Group. Initially, the focus is on system-oriented APIs, -covering files, networking, and a few other things. Additional domains are -expected to be added in the future. - -WebAssembly is designed to run well on the Web, however it's -[not limited to the Web](https://github.com/WebAssembly/design/blob/master/NonWeb.md). -The core WebAssembly language is independent of its surrounding -environment, and WebAssembly interacts with the outside world -exclusively through APIs. On the Web, it naturally uses the -existing Web APIs provided by browsers. - -WASI is an effort to provide general-purpose APIs for supporting -non-Web use cases. The focus is on designing clean and portable APIs which -can be implemented on multiple platforms by multiple engines, and which -don't depend on browser functionality (although they still can run in -browsers; see below). - -## Capability-Oriented - -WASI's core design follows -[CloudABI](https://cloudabi.org/)'s -(and in turn -[Capsicum](https://www.cl.cam.ac.uk/research/security/capsicum/))'s concept of -[capability-based security](https://en.wikipedia.org/wiki/Capability-based_security), -which fits well into WebAssembly's sandbox model. Files, -directories, network sockets, and other resources are identified -by UNIX-like file descriptors, which are indices into external -tables whose elements represent capabilities. Similar to how core -WebAssembly provides no ability to access the outside world without -calling imported functions, WASI APIs provide no ability to access -the outside world without an associated capability. - -For example, instead of a typical -[open](http://pubs.opengroup.org/onlinepubs/009695399/functions/open.html) -system call, WASI provides an -[openat](https://linux.die.net/man/2/openat)-like -system call, requiring the calling process to have a file -descriptor for a directory that contains the file, representing the -capability to open files within that directory. (These ideas are -common in capability-based systems.) - -However, the WASI libc implementation still does provide an -implementation of open, by taking the approach of -[libpreopen](https://github.com/musec/libpreopen). -Programs may be granted capabilities for directories on launch, and -the library maintains a mapping from their filesystem path to the -file descriptor indices representing the associated capabilities. -When a program calls open, they look up the file name in the map, -and automatically supply the appropriate directory capability. It -also means WASI doesn't require the use of CloudABI's `program_main` -construct. This eases porting of existing applications without -compromising the underlying capability model. See the diagram below -for how libpreopen fits into the overall software architecture. - -WASI also automatically provides file descriptors for standard -input and output, and WASI libc provides a normal `printf`. In -general, WASI is aiming to support a fairly full-featured libc -implementation, with the current implementation work being based on -[musl](http://www.musl-libc.org/). - -## Portable System Interface for WebAssembly - -WASI is being designed from the ground up for WebAssembly, with -sandboxing, portability, and API tidiness in mind, making natural -use of WebAssembly features such as i64, import functions with -descriptive names and typed arguments, and aiming to avoid being -tied to a particular implementation. - -We often call functions in these APIs "syscalls", because they -serve an analogous purpose to system calls in native executables. -However, they're just functions that are provided by the -surrounding environment that can do I/O on behalf of the program. - -WASI is starting with a basic POSIX-like set of syscall functions, -though adapted to suit the needs of WebAssembly, such as in -excluding functions such as fork and exec which aren't easily -implementable in some of the places people want to run WebAssembly, -and such as in adopting a capabilities-oriented design. - -And, as WebAssembly grows support for -[host bindings](https://github.com/webassembly/host-bindings) -and related features, capabilities can evolve to being represented -as opaque, unforgeable -[reference typed values](https://github.com/WebAssembly/reference-types), -which can allow for finer-grained control over capabilities, and -make the API more accessible beyond the C-like languages that -POSIX-style APIs are typically aimed at. - -## WASI Software Architecture - -To facilitate use of the WASI API, a libc -implementation called WASI libc is being developed, which presents -a relatively normal musl-based libc interface, implemented on top -of a libpreopen-like layer and a system call wrapper layer (derived -from the "bottom half" of -[cloudlibc](https://github.com/NuxiNL/cloudlibc)). -The system call wrapper layer makes calls to the actual WASI -implementation, which may map these calls to whatever the -surrounding environment provides, whether it's native OS resources, -JS runtime resources, or something else entirely. - -[This libc is part of a "sysroot"](https://github.com/CraneStation/wasi-sysroot), -which is a directory containing compiled libraries and C/C++ header -files providing standard library and related facilities laid out in -a standard way to allow compilers to use it directly. - -With the [LLVM 8.0](http://llvm.org/) -release, the WebAssembly backend is now officially stable, but LLVM -itself doesn't provide a libc - a standard C library, which you -need to build anything with clang. This is what the WASI-enabled -sysroot provides, so the combination of clang in LLVM 8.0 and the -new WASI-enabled sysroot provides usable Rust and C compilation -environments that can produce executable wasm programs. - -![WASI software architecture diagram](wasi-software-architecture.png "WASI software architecture diagram") - -## Future Evolution - -The first version of WASI is relatively simple, small, and -POSIX-like in order to make it easy for implementers to prototype -it and port existing code to it, making it a good way to start -building momentum and allow us to start getting feedback based on -experience. - -Future versions will change based on experience -and feedback with the first version, and add features to address -new use cases. They may also see significant architectural -changes. Because all of the APIs are accessed through regular -WebAssembly imports, APIs can be implemented either by wasm -runtimes directly or by other WebAssembly modules. So if WASI APIs -change significantly, the old APIs can be implemented as a library -on top of the new APIs. - -## Can WASI apps run on the Web? - -While this isn't the initial focus, it's possible to implement WASI -APIs from JavaScript, since they're just regular WebAssembly imports, -so it's possible to run WASI modules on the Web. - -And in the future, it's possible that -[builtin modules](https://github.com/tc39/ecma262/issues/395) -could take these ideas even further allowing easier and tighter -integration between .wasm modules importing WASI and the Web. diff --git a/docs/wasi-software-architecture.png b/docs/wasi-software-architecture.png deleted file mode 100644 index 6cb8345cc..000000000 Binary files a/docs/wasi-software-architecture.png and /dev/null differ diff --git a/legacy/README.md b/legacy/README.md new file mode 100644 index 000000000..14fca2cba --- /dev/null +++ b/legacy/README.md @@ -0,0 +1,5 @@ +# Legacy WASI docs + +In the early days of WASI, we developed design ideas around the ABI and imports. These ideas have made their way into the WebAssembly component model, though sometimes in a greatly modified form. + +We will continue to keep these documents in the repo through the end of 2023. After that point, we expect all WASI implmentations to be implmented in terms of the new design. diff --git a/design/application-abi.md b/legacy/application-abi.md similarity index 100% rename from design/application-abi.md rename to legacy/application-abi.md diff --git a/design/optional-imports.md b/legacy/optional-imports.md similarity index 100% rename from design/optional-imports.md rename to legacy/optional-imports.md diff --git a/proposal-template/README.md b/proposal-template/README.md deleted file mode 100644 index b97035935..000000000 --- a/proposal-template/README.md +++ /dev/null @@ -1,4 +0,0 @@ -# Proposal template - -This directory will hold a template for creating new proposals, to help people -get started. diff --git a/proposals/README.md b/proposals/README.md deleted file mode 100644 index 45c2c2852..000000000 --- a/proposals/README.md +++ /dev/null @@ -1,8 +0,0 @@ -# Proposals - -This directory contains overviews for proposals that are included in this -repository. - -This is analogous to [the correpsonding directory in the spec repository]. - -[the correpsonding directory in the spec repository]: https://github.com/WebAssembly/spec/tree/master/proposals diff --git a/snapshots/README.md b/snapshots/README.md deleted file mode 100644 index af94dbdef..000000000 --- a/snapshots/README.md +++ /dev/null @@ -1,5 +0,0 @@ -# WASI Snapshots - -To balance between the needs of development and stability, snapshots -represent the state of all active proposals at a moment in time. Individual -Snapshots are stable, but WASI as a whole is evolving. diff --git a/snapshots/make-snapshot.sh b/snapshots/make-snapshot.sh deleted file mode 100755 index b30dfa2e5..000000000 --- a/snapshots/make-snapshot.sh +++ /dev/null @@ -1,159 +0,0 @@ -#!/bin/bash -# Creates a snapshot based on upstream proposal repositories. -# Derived from update-testsuite.sh in https://github.com/WebAssembly/testsuite -set -e -set -u -set -o pipefail - -ignore_dirs='' - -# TODO: Add the rest. -repos=' - WASI - wasi-filesystem - wasi-clocks - wasi-random -' - -log_and_run() { - echo ">>" $* - if ! $*; then - echo "sub-command failed: $*" - exit - fi -} - -try_log_and_run() { - echo ">>" $* - $* -} - -pushdir() { - pushd $1 >/dev/null || exit -} - -popdir() { - popd >/dev/null || exit -} - -update_repo() { - local repo=$1 - pushdir repos - if [ -d ${repo} ]; then - log_and_run git -C ${repo} fetch origin - log_and_run git -C ${repo} reset origin/main --hard - else - log_and_run git clone https://github.com/WebAssembly/${repo} - fi - - # Add upstream WASI as "WASI" remote. - if [ "${repo}" != "WASI" ]; then - pushdir ${repo} - if ! git remote | grep WASI >/dev/null; then - log_and_run git remote add WASI https://github.com/WebAssembly/WASI - fi - - log_and_run git fetch WASI - popdir - fi - popdir -} - -merge_with_WASI() { - local repo=$1 - - [ "${repo}" == "WASI" ] && return - - pushdir repos/${repo} - # Create and checkout "try-merge" branch. - if ! git branch | grep try-merge >/dev/null; then - log_and_run git branch try-merge origin/main - fi - log_and_run git checkout try-merge - - # Attempt to merge with WASI/main. - log_and_run git reset origin/main --hard - try_log_and_run git merge -q WASI/main -m "merged" - if [ $? -ne 0 ]; then - # Ignore merge conflicts in non-test directories. - # We don't care about those changes. - try_log_and_run git checkout --ours ${ignore_dirs} - try_log_and_run git add ${ignore_dirs} - try_log_and_run git -c core.editor=true merge --continue - if [ $? -ne 0 ]; then - git merge --abort - popdir - return 1 - fi - fi - popdir - return 0 -} - -snapshot_name=$(date --iso-8601) -snapshot_dir=snapshots/$snapshot_name -mkdir -p $snapshot_dir - -commit_message_file=$PWD/commit_message -echo -e "Update repos\n" > $commit_message_file - -failed_repos= - -for repo in ${repos}; do - echo "++ updating ${repo}" - update_repo ${repo} - - if ! merge_with_WASI ${repo}; then - echo -e "!! error merging ${repo}, skipping\n" - failed_repos="${failed_repos} ${repo}" - continue - fi - - if [ "${repo}" = "WASI" ]; then - dest_dir=$snapshot_dir - log_and_run cp -r repos/${repo}/standard ${dest_dir} - else - dest_dir=$snapshot_dir/proposals/${repo} - mkdir -p ${dest_dir} - - # Don't add tests from proposal that are the same as WASI. - pushdir repos/${repo} - for new in $(find standard -type f); do - old=../../repos/WASI/${new} - if [[ ! -f ${old} ]] || ! diff ${old} ${new} >/dev/null; then - log_and_run cp ${new} ../../${dest_dir} - fi - done - popdir - fi - - # Check whether any files were removed. - for old in $(find ${dest_dir} -type f); do - new=$(find repos/${repo}/standard -name ${old##*/}) - if [[ ! -f ${new} ]]; then - log_and_run git rm ${old} - fi - done - - # Check whether any files were updated. - if [ $(git status -s ${dest_dir} | wc -l) -ne 0 ]; then - log_and_run git add ${dest_dir}/* - - repo_sha=$(git -C repos/${repo} log --max-count=1 --oneline origin/main| sed -e 's/ .*//') - echo " ${repo}:" >> $commit_message_file - echo " https://github.com/WebAssembly/${repo}/commit/${repo_sha}" >> $commit_message_file - fi - - echo -e "-- ${repo}\n" -done - -echo "" >> $commit_message_file -echo "This change was automatically generated by \`make-snapshot.sh\`" >> $commit_message_file -git commit -a -F $commit_message_file -# git push - -echo "done" - -if [ -n "${failed_repos}" ]; then - echo "!! failed to update repos: ${failed_repos}" -fi diff --git a/standard/README.md b/standard/README.md deleted file mode 100644 index ad6f93c7c..000000000 --- a/standard/README.md +++ /dev/null @@ -1,12 +0,0 @@ -# WASI Standard - -In the [main WASI repository], this directory holds proposals which have -[completed the standardization process]. - -In a proposal repository, which is a fork of the main WASI repository, -this directory holds the current proposal, including witx specifications, -tests, and documentation. When the proposal is standardized, the fork is -merged into the main repository. - -[main WASI repository]: https://github.com/WebAssembly/WASI/issues/360 -[completed the standardization process]: https://github.com/WebAssembly/meetings/blob/master/process/phases.md#5-the-feature-is-standardized-working-group diff --git a/test/minimal-command.wasm b/test/minimal-command.wasm deleted file mode 100644 index ca050857c..000000000 Binary files a/test/minimal-command.wasm and /dev/null differ diff --git a/test/sources/generate-wasm.sh b/test/sources/generate-wasm.sh deleted file mode 100755 index 9d5c5fa1d..000000000 --- a/test/sources/generate-wasm.sh +++ /dev/null @@ -1,8 +0,0 @@ -#!/bin/bash -set -ueo pipefail - -for wat in wat/*.wat; do - wat2wasm "$wat" -done - -mv *.wasm .. diff --git a/test/sources/wat/minimal-command.wat b/test/sources/wat/minimal-command.wat deleted file mode 100644 index 6e9f4f5ff..000000000 --- a/test/sources/wat/minimal-command.wat +++ /dev/null @@ -1,3 +0,0 @@ -(module - (func (export "_start")) -) diff --git a/tools/test-harness/exit_status_zero b/tools/test-harness/exit_status_zero deleted file mode 100644 index 573541ac9..000000000 --- a/tools/test-harness/exit_status_zero +++ /dev/null @@ -1 +0,0 @@ -0 diff --git a/tools/test-harness/run.sh b/tools/test-harness/run.sh deleted file mode 100755 index 218856a23..000000000 --- a/tools/test-harness/run.sh +++ /dev/null @@ -1,17 +0,0 @@ -#!/bin/bash -set -ueo pipefail - -# Top-level test runner. Usage is "run.sh" to run tests in compile-only mode, -# or "run.sh " where is a WASI-capable runtime to run the -# tests in full compile and execute mode. - -# Determine the wasm runtime to use. -runwasi="$1" - -tooldir=$(dirname $0) - -echo "===== Testing =====" -for file in *.wasm; do - "$tooldir/testcase.sh" "$runwasi" "$file" -done -cd - >/dev/null diff --git a/tools/test-harness/testcase.sh b/tools/test-harness/testcase.sh deleted file mode 100755 index 482fdddcd..000000000 --- a/tools/test-harness/testcase.sh +++ /dev/null @@ -1,90 +0,0 @@ -#!/bin/bash -set -ueo pipefail - -# A simple testcase runner that runs a command, captures all its command-line -# outputs, and compares them against expected outputs. - -# Command-line parsing; this script is meant to be run from a higher-level -# script, so don't do anything fancy. -runwasi="$1" -input="$2" - -# Compile names for generated files. -wasm="$input" -stdout_observed="$input.stdout.observed" -stderr_observed="$input.stderr.observed" -exit_status_observed="$input.exit_status.observed" -tooldir=$(dirname $0) - -echo "Testing $input..." - -# Determine the input file to write to stdin. -if [ -e "$input.stdin" ]; then - stdin="$input.stdin" -else - stdin="/dev/null" -fi - -# Determine any environment variables to set. -if [ -e "$input.env" ]; then - env=$(sed -e 's/^/--env /' < "$input.env") -else - env="" -fi - -# Determine a preopened directory to provide. -if [ -e "$input.dir" ]; then - dir="--dir $input.dir" - dirarg="$input.dir" -else - dir="" - dirarg="" -fi - -# Run the test, capturing stdout, stderr, and the exit status. -exit_status=0 -"$runwasi" $env $dir "$wasm" $dirarg \ - < "$stdin" \ - > "$stdout_observed" \ - 2> "$stderr_observed" \ - || exit_status=$? -echo $exit_status > "$exit_status_observed" - -# Determine the reference files to compare with. -if [ -e "$input.stdout.expected" ]; then - stdout_expected="$input.stdout.expected" - - # Apply output filters. - if [ -e "$input.stdout.expected.filter" ]; then - cat "$stdout_observed" \ - | "$input.stdout.expected.filter" \ - > "${stdout_observed}.filtered" - stdout_observed="${stdout_observed}.filtered" - fi -else - stdout_expected="/dev/null" -fi -if [ -e "$input.stderr.expected" ]; then - stderr_expected="$input.stderr.expected" - - # Apply output filters. - if [ -e "$input.stderr.expected.filter" ]; then - cat "$stderr_observed" \ - | "./$input.stderr.expected.filter" \ - > "${stderr_observed}.filtered" - stderr_observed="${stderr_observed}.filtered" - fi -else - stderr_expected="/dev/null" -fi -if [ -e "$input.exit_status.expected" ]; then - exit_status_expected="$tooldir/$input.exit_status.expected" -else - exit_status_expected="$tooldir/exit_status_zero" -fi - -# If there are any differences, diff will return a non-zero exit status, and -# since this script uses "set -e", it will return a non-zero exit status too. -diff -u "$stderr_expected" "$stderr_observed" -diff -u "$stdout_expected" "$stdout_observed" -diff -u "$exit_status_expected" "$exit_status_observed" diff --git a/docs/witx.md b/tools/witx-docs.md similarity index 100% rename from docs/witx.md rename to tools/witx-docs.md