diff --git a/docs/source/InstallationAndUsage.rst b/docs/source/InstallationAndUsage.rst index 5c0b138d..9b6ea9a5 100644 --- a/docs/source/InstallationAndUsage.rst +++ b/docs/source/InstallationAndUsage.rst @@ -1,7 +1,7 @@ Installation And Usage -------------------- -Installation from source +Installation from source (non wasm build instructions) ======================== To ensure that the installation works, it is preferable to install `xeus-cpp` in a @@ -42,6 +42,68 @@ with a custom installation prefix if need be) -D CMAKE_INSTALL_LIBDIR=lib make && make install +Installation within a mamba environment (wasm build instructions) +======================== + +These instructions will assume you have cmake installed on your system. First clone the repository, and move into that directory +.. code-block:: bash + git clone --depth=1 https://github.com/compiler-research/xeus-cpp.git + cd ./xeus-cpp + + +You'll now want to make sure you're using emsdk version "3.1.45" and activate it. You can get this by executing the following + +.. code-block:: bash + cd $HOME + git clone https://github.com/emscripten-core/emsdk.git + cd emsdk + ./emsdk install 3.1.45 + ./emsdk activate 3.1.45 + source $HOME/emsdk/emsdk_env.sh + + +You are now in a position to build the xeus-cpp kernel. You build it by executing the following + +.. code-block:: bash + micromamba create -f environment-wasm-host.yml --platform=emscripten-wasm32 + mkdir build + pushd build + export PREFIX=$MAMBA_ROOT_PREFIX/envs/xeus-cpp-wasm-host + export CMAKE_PREFIX_PATH=$PREFIX + export CMAKE_SYSTEM_PREFIX_PATH=$PREFIX + export SYSROOT_PATH=$HOME/emsdk/upstream/emscripten/cache/sysroot + emcmake cmake \ + -DCMAKE_BUILD_TYPE=Release \ + -DCMAKE_PREFIX_PATH=$PREFIX \ + -DCMAKE_INSTALL_PREFIX=$PREFIX \ + -DXEUS_CPP_EMSCRIPTEN_WASM_BUILD=ON \ + -DCMAKE_FIND_ROOT_PATH_MODE_PACKAGE=ON \ + -DSYSROOT_PATH=$SYSROOT_PATH \ + .. + emmake make install + + +To build Jupyter Lite with this kernel without creating a website you can execute the following + +.. code-block:: bash + micromamba create -n xeus-lite-host jupyterlite-core + micromamba activate xeus-lite-host + python -m pip install jupyterlite-xeus + jupyter lite build --XeusAddon.prefix=$PREFIX + +We now need to shift necessary files like `xcpp.data` which contains the binary representation of the file(s) +we want to include in our application. As of now this would contain all important files like Standard Headers, +Libraries etc coming out of emscripten's sysroot. Assuming we are still inside build we should do the following + +.. code-block:: bash + cp $PREFIX/bin/xcpp.data _output/extensions/@jupyterlite/xeus/static + cp $PREFIX/lib/libclangCppInterOp.so _output/extensions/@jupyterlite/xeus/static + +Once the Jupyter Lite site has built you can test the website locally by executing + +.. code-block:: bash + jupyter lite serve --XeusAddon.prefix=$PREFIX + Installing from conda-forge =========================== @@ -51,4 +113,4 @@ If you have conda installed then you can install xeus-cpp using the follwing com conda install conda-forge::xeus-cpp -Xeus-cpp is available for Linux, MacOS and Windows. \ No newline at end of file +Xeus-cpp is available for Linux, MacOS and Windows.