From 9a826704993a24e9b4f8ae1739efd27ce594fcda Mon Sep 17 00:00:00 2001 From: DerThorsten Date: Thu, 21 Mar 2024 11:23:11 +0100 Subject: [PATCH] added installtion steps --- docs/index.md | 37 ++++++++++++++- docs/installation.md | 106 +++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 142 insertions(+), 1 deletion(-) create mode 100644 docs/installation.md diff --git a/docs/index.md b/docs/index.md index 189f481..553422e 100644 --- a/docs/index.md +++ b/docs/index.md @@ -1,3 +1,38 @@ # Welcome to `pyjs` -Welcome \ No newline at end of file +Pyjs is a python - javascript FFI for webassembly. +It allows you to write python code and run it in the browser. + + +## Quickstart + +Access Javascript from Python: + +```python +import pyjs + +# hello world +pyjs.js.console.log("Hello, World!") + +# create a JavaScript function to add two numbers +js_function = pyjs.js.Function("a", "b", """ + console.log("Adding", a, "and", b) + return a + b +""") + +# call the function +result = js_function(1, 2) +``` + +Access Python from Javascript: + +```JavaScript +// hello world +pyjs.eval("print('Hello, World!')") + +// eval a python expression and get the result +const py_list = pyjs.eval("[i for i in range(10)]") + +/// access +console.log(py_list.get(0)) // same as py_list[0] on the python side +``` diff --git a/docs/installation.md b/docs/installation.md new file mode 100644 index 0000000..22b8128 --- /dev/null +++ b/docs/installation.md @@ -0,0 +1,106 @@ +# Installation + +## Prerequisites: + +https://repo.mamba.pm/emscripten-forge. +Before we start, lets introduce a few concepts and tools that are used in the pyjs workflow. +### Conda-forge Emscripten-Forge + +[Emscripten-forge](https://github.com/emscripten-forge/recipes) is similar to [conda-forge](https://conda-forge.org/) and provides packages compiled to webassembly using emscripten. + +### Empack +https://github.com/emscripten-forge/empack is a tool to "pack" conda environments into a set of files that can be consumed by pyjs. + + + +## Installation Steps + +So we assume there is a directory called `/path/to/deploy` where we will +put all tools which need to be served to the user. + +### Define a conda environment +Pyjs has a conda-like workflow. This means the first step +is to create a environment with the `pyjs` package installed +and all packages required for the project. + +```yaml +name: my-pyjs-env +channels: + - https://repo.mamba.pm/emscripten-forge + - conda-forge +dependencies: + - pyjs + - numpy +``` + +The name of the environment can be choosen by the user. +The `channels` section specifies the conda channels to use. +The `https://repo.mamba.pm/emscripten-forge` is mandatory to install the `pyjs` package. +The `conda-forge` channel is used to install `noarch`. +All compiled packages need to be available in the `emscripten-forge` channel. + +### Create the environment +Assuming the yaml file above is called `environment.yml` and is in the current directory, the environment can be created using `micromamba`: + +```Bash +micromamba create -f environment.yml --platform emscripten-wasm32 --prefix /path/to/env +``` + +### Copy pyjs +Copy the pyjs binary from the environment to the deploy directory. +This should move pyjs_runtime_browser.js and pyjs_runtime_browser.wasm to the deployment directory. + +```Bash +cp /path/to/env/js_bin/pyjs/* /path/to/deploy +``` + + + +### Pack the environment + +After the environment is defined, the next step is to pack the environment using `empack`. + +```Bash +empack pack env --env-prefix /path/to/env --output /path/to/deploy +``` +This will create a tarball for each package in the environment and a `empack_env_meta.json` file that describes the environment. + + +### The html/JavaScript code + +The last step is to create a html file that loads the pyjs runtime and the packed environment. + +```html + + + + Pyjs Example + + + + +

Pyjs Example

+ +``` \ No newline at end of file