Skip to content

Commit

Permalink
Merge pull request #18 from jtpio/fix-lint
Browse files Browse the repository at this point in the history
Fix lint failure on CI
  • Loading branch information
martinRenou authored Jan 8, 2024
2 parents de99795 + a5cd244 commit ca75437
Showing 1 changed file with 20 additions and 22 deletions.
42 changes: 20 additions & 22 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -20,33 +20,37 @@ pip install jupyterlite_xeus
### From environment.yaml

#### xeus-python kernel
To create a `xeus-python` kernel with a custom environment, one creates an `environment.yaml` file with `xeus-python` and the desiered dependencies. Here is an example with `numpy` as a additional dependency:

To create a `xeus-python` kernel with a custom environment, one creates an `environment.yaml` file with `xeus-python` and the desiered dependencies. Here is an example with `numpy` as a additional dependency:

```yaml
name: xeus-lite-wasm
channels:
- https://repo.mamba.pm/emscripten-forge
- https://repo.mamba.pm/emscripten-forge
- conda-forge
dependencies:
- xeus-python
- xeus-python
- numpy
```
To build the jupyterlite run the following command, where `environment.yaml` is the path to the file you just created
To build the jupyterlite run the following command, where `environment.yaml` is the path to the file you just created

```bash
jupyter lite build --XeusAddon.environment_file=some_path/to/environment.yaml
```

#### xeus-lua / xeus-sqlite / xeus-\<mylang\>
#### xeus-lua / xeus-sqlite / xeus-\<mylang\>

To create a `xeus-lua` or `xeus-sqlite` kernel you can
do the same as above, just with
do the same as above, just with

```yaml
dependencies:
- xeus-lua
```

or

```yaml
dependencies:
- xeus-sqlite
Expand All @@ -59,27 +63,25 @@ To build the jupyterlite, run again:
jupyter lite build --XeusAddon.environment_file=environment.yaml
```


#### Multiple kernels

To create a deployment with multiple kernels, you can just add them to the `environment.yaml` file:

```yaml
name: xeus-lite-wasm
channels:
- https://repo.mamba.pm/emscripten-forge
- https://repo.mamba.pm/emscripten-forge
- conda-forge
dependencies:
- xeus-python
- xeus-python
- xeus-lua
- xeus-sqlite
- numpy
```

### From local environment / prefix

When developing a xeus-kernel, it is very usefull to be able to test it in a jupyterlite without having to publish it to emscripten-forge. Therefore you can also use a local environment / prefix to build a jupyterlite with a custom kernel.

When developing a xeus-kernel, it is very usefull to be able to test it in a jupyterlite without having to publish it to emscripten-forge. Therefore you can also use a local environment / prefix to build a jupyterlite with a custom kernel.

#### Create a local environment / prefix

Expand All @@ -93,8 +95,9 @@ micromamba create -n xeus-python-dev \
--yes \
"python>=3.11" pybind11 nlohmann_json pybind11_json numpy pytest \
bzip2 sqlite zlib libffi xtl pyjs \
xeus xeus-sqlite
xeus xeus-sqlite
```

#### Build the kernel

This dependes on your kernel but will look smth like this:
Expand All @@ -117,37 +120,34 @@ cd build_wasm
emcmake cmake \
-DCMAKE_BUILD_TYPE=Release \
-DCMAKE_FIND_ROOT_PATH_MODE_PACKAGE=ON \
-DCMAKE_INSTALL_PREFIX=$PREFIX
-DCMAKE_INSTALL_PREFIX=$PREFIX
..
emmake make -j8 install
```

When running `jupyter lite build` we pass the `prefix` options and point it to the local environment / prefix we just created:

```bash
jupyter lite build --XeusAddon.prefix=$WASM_ENV_PREFIX
jupyter lite build --XeusAddon.prefix=$WASM_ENV_PREFIX
```

### Mounting additional files

To copy additional files and directories into the virtual filesytem of the xeus-lite kernels you can use the `--XeusAddon.mount` option.
To copy additional files and directories into the virtual filesytem of the xeus-lite kernels you can use the `--XeusAddon.mount` option.
Each mount is specified as a pair of paths separated by a colon `:`. The first path is the path to the file or directory on the host machine, the second path is the path to the file or directory in the virtual filesystem of the kernel.

```bash
jupyter lite build \
--XeusAddon.environment_file=environment.yaml \
--XeusAddon.mounts=/some/path/on/host_machine:/some/path/in/virtual/filesystem
--XeusAddon.mounts=/some/path/on/host_machine:/some/path/in/virtual/filesystem
```




## Contributing

### Development install from a conda / mamba environment

Create the conda environment with `conda`/`mamba`/`micromamba` (replace `micromamba` with `conda` or `mamba` according to your preference):


```bash
micromamba create -f environment-dev.yml -n xeus-lite-dev
```
Expand All @@ -158,12 +158,10 @@ Activate the environment:
micromamba activate xeus-lite-dev
```


```bash
python -m pip install -e . -v --no-build-isolation
```


### Packaging the extension

See [RELEASE](RELEASE.md)

0 comments on commit ca75437

Please sign in to comment.