Awesome
JupyterLite Xeus
JupyterLite loader for Xeus kernels
Requirements
- JupyterLab >= 4.0.0
Install
To install the extension, execute:
pip install jupyterlite_xeus
Usage
From environment.yml
xeus-python kernel
To load a xeus-python
kernel with a custom environment, create an environment.yml
file with xeus-python
and the desired dependencies. Here is an example with numpy
as a additional dependency:
name: xeus-lite-wasm
channels:
- https://repo.mamba.pm/emscripten-forge
- conda-forge
dependencies:
- xeus-python
- numpy
To build JupyterLite, run the following command where environment.yml
is the path to the file you just created
jupyter lite build --XeusAddon.environment_file=some_path/to/environment.yml
xeus-lua / xeus-sqlite / xeus-<mylang>
To load a xeus-lua
or xeus-sqlite
kernel you can
do the same as above, just with
dependencies:
- xeus-lua
or
dependencies:
- xeus-sqlite
Note that xeus-sqlite
and xeus-lua
do not support additional dependencies yet.
To build JupyterLite, run again:
jupyter lite build --XeusAddon.environment_file=environment.yml
Multiple kernels
To create a deployment with multiple kernels, you can simply add them to the environment.yml
file:
name: xeus-lite-wasm
channels:
- https://repo.mamba.pm/emscripten-forge
- conda-forge
dependencies:
- xeus-python
- xeus-lua
- xeus-sqlite
- numpy
From local environment / prefix
When developing a xeus-kernel, it is very useful to be able to test it in JupyterLite without having to publish the kernel to emscripten-forge. Therefore, you can also use a local environment / prefix to build JupyterLite with a custom kernel.
Create a local environment / prefix
This workflow usually starts with creating a local conda environment / prefix for the emscripten-wasm32
platform with all the dependencies required to build your kernel (here we install dependencies for xeus-python
).
micromamba create -n xeus-python-dev \
--platform=emscripten-wasm32 \
-c https://repo.mamba.pm/emscripten-forge \
-c conda-forge \
--yes \
"python>=3.11" pybind11 nlohmann_json pybind11_json numpy pytest \
bzip2 sqlite zlib libffi xtl pyjs \
xeus xeus-lite
Build the kernel
This depends on your kernel, but it will look something like this:
# path to your emscripten emsdk
source $EMSDK_DIR/emsdk_env.sh
WASM_ENV_NAME=xeus-python-dev
WASM_ENV_PREFIX=$MAMBA_ROOT_PREFIX/envs/$WASM_ENV_NAME
# let cmake know where the env is
export PREFIX=$WASM_ENV_PREFIX
export CMAKE_PREFIX_PATH=$PREFIX
export CMAKE_SYSTEM_PREFIX_PATH=$PREFIX
cd /path/to/your/kernel/src
mkdir build_wasm
cd build_wasm
emcmake cmake \
-DCMAKE_BUILD_TYPE=Release \
-DCMAKE_FIND_ROOT_PATH_MODE_PACKAGE=ON \
-DCMAKE_INSTALL_PREFIX=$PREFIX \
..
emmake make -j8 install
Build the JupyterLite site
You will need to create a new environment with the dependencies to build the JupyterLite site.
# create new environment
micromamba create -n xeus-lite-host \
jupyterlite-core
# activate the environment
micromamba activate xeus-lite-host
# install jupyterlite_xeus via pip
python -m pip install jupyterlite-xeus
When running jupyter lite build
, we pass the prefix
option and point it to the local environment / prefix we just created:
jupyter lite build --XeusAddon.prefix=$WASM_ENV_PREFIX
Mounting additional files
To copy additional files and directories into the virtual filesystem 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.
jupyter lite build \
--XeusAddon.environment_file=environment.yml \
--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):
micromamba create -f environment-dev.yml -n xeus-lite-dev
Activate the environment:
micromamba activate xeus-lite-dev
python -m pip install -e . -v --no-build-isolation
Packaging the extension
See RELEASE.