diff --git a/docs/docs.md b/docs/docs.md index 369ae20..0e3d785 100644 --- a/docs/docs.md +++ b/docs/docs.md @@ -3,10 +3,9 @@ sidebar_position: 1 slug: / --- -# Timecraft Docs +# Timecraft -Timecraft is an application runtime providing a Time Machine and a Task Orchestration capability. -Built on top of Wazero, Timecraft leverage the WebAssembly sandbox. +Timecraft is an application runtime designed to build and run production grade distributed systems. ## Getting Started @@ -17,11 +16,12 @@ First step, install and configure Timecraft: You will then have to compile your application to WebAssembly: -- [Compiling your Go application to WebAssembly](/getting-started/prep-application/compiling-go) -- [Compiling your Python application to WebAssembly](/getting-started/prep-application/compiling-python) +- [Compiling your Go application to WebAssembly](/getting-started/applications/go) +- [Compiling your Python application to WebAssembly](/getting-started/applications/python) ## Community +- [Discord](https://stealthrocket.tech/discord) - [Twitter](https://twitter.com/_stealthrocket) -- [steathrocket.tech](https://twitter.com/_stealthrocket) +- [steathrocket.tech](https://stealthrocket.tech) diff --git a/docs/getting-started/applications/_category_.yml b/docs/getting-started/applications/_category_.yml new file mode 100644 index 0000000..4b7651a --- /dev/null +++ b/docs/getting-started/applications/_category_.yml @@ -0,0 +1,5 @@ +label: "Applications" +position: 1 +link: + type: generated-index + title: "Applications" diff --git a/docs/getting-started/applications/go.md b/docs/getting-started/applications/go.md new file mode 100644 index 0000000..a5616be --- /dev/null +++ b/docs/getting-started/applications/go.md @@ -0,0 +1,55 @@ +# Go + +## Preparing Go + +Go 1.21, due to be released in August 2023, will be able to natively compile Go applications to WebAssembly. + +```console +$ GOOS=wasip1 GOARCH=wasm go build ... +``` + +Since Go 1.21 has not been released yet, you can use [`gotip`](https://pkg.go.dev/golang.org/dl/gotip) to test these features before release: + +```console +$ go install golang.org/dl/gotip@latest +$ gotip download +``` + +```console +$ GOOS=wasip1 GOARCH=wasm gotip build ... +``` + +## Compiling your application + +Instead of using `go build`, use: + +```console +$ GOOS=wasip1 GOARCH=wasm gotip build -o app.wasm +``` + +This will build a WebAssembly module that can be run with Timecraft. + +## Running your application with Timecraft + +To run your application: + +```console +$ timecraft run app.wasm +``` + +Command-line arguments can be specified after the WebAssembly module. To prevent +Timecraft from interpreting command-line options for the application, use: + +```console +$ timecraft run -- app.wasm arg1 arg2 ... +``` + +Note that environment variables passed to Timecraft are automatically passed to the +WebAssembly module. + +## Networking applications + +You may quickly find that the networking capabilities of `GOOS=wasip1` are limited. + +We have created a library to help with common use cases, such as creating HTTP servers +and connecting to databases. See https://github.com/stealthrocket/net for usage details. diff --git a/docs/getting-started/applications/python.md b/docs/getting-started/applications/python.md new file mode 100644 index 0000000..2be60d9 --- /dev/null +++ b/docs/getting-started/applications/python.md @@ -0,0 +1,52 @@ +# Python + +Python applications aren't compiled to WebAssembly. Rather, a Python interpreter (CPython) +is compiled to WebAssembly and interprets your Python application as it would normally. + +Minor patches have been made to both the CPython interpreter and standard library to ensure +that applications are able to create POSIX style sockets. This enables Python applications to +create servers and connect to databases. We intend to upstream our patches at some stage. + +## Preparing Python + +We provide a pre-compiled Python interpreter and patched standard library. You can download them by running + +``` +curl -fsSL https://timecraft.s3.amazonaws.com/python/main/python.wasm -o python.wasm +curl -fsSL https://timecraft.s3.amazonaws.com/python/main/python311.zip -o python311.zip +``` + +To build Python from scratch, see the instructions in the +[`./python`](https://github.com/stealthrocket/timecraft/tree/main/python) dir. + +## Running your application with Timecraft + +### Preparing dependencies + +It's recommended that you install your Python dependencies in a virtualenv: + +```console +$ python3 -m venv env +$ source ./env/bin/activate +(env) $ pip install -r /path/to/requirements.txt +``` + +### Running Timecraft + +The Python interpreter needs to know where dependencies are installed +and where the standard library ZIP is located. + +Assuming both the interpreter (`python.wasm`) and standard library (`python311.zip`) +are located in the current directory, you can pass this information to the +interpreter like so: + +``` +$ export PYTHONHOME=env +$ export PYTHONPATH=python311.zip:$PYTHONHOME +``` + +You can now run your application: + +``` +$ timecraft run python.wasm main.py +```