xeus-cpp is a Jupyter kernel for cpp based on the native implementation of the Jupyter protocol xeus.

Try Jupyter Lite demo by clicking below

Installation within a mamba environment (non wasm build instructions)

To ensure that the installation works, it is preferable to install xeus-cpp in a fresh environment. It is also needed to use a miniforge or miniconda installation because with the full anaconda you may have a conflict with the zeromq library which is already installed in the anaconda distribution.

First clone the repository, and move into that directory

git clone --depth=1 https://github.com/compiler-research/xeus-cpp.git
cd ./xeus-cpp

The safest usage of xeus-cpp from source is to build and install it within a clean environment named xeus-cpp. You can create and activate this environment with mamba by executing the following

mamba create -n  "xeus-cpp"
source activate  "xeus-cpp"

We will now install the dependencies needed to compile xeux-cpp from source within this environment by executing the following

mamba install notebook cmake cxx-compiler xeus-zmq nlohmann_json=3.11.3 jupyterlab CppInterOp cpp-argparse"<3.1" pugixml doctest -c conda-forge

Now you can compile the kernel from the source by executing (replace $CONDA_PREFIX with a custom installation prefix if need be)

mkdir build
cd build
cmake .. -D CMAKE_PREFIX_PATH=$CONDA_PREFIX -D CMAKE_INSTALL_PREFIX=$CONDA_PREFIX -D CMAKE_INSTALL_LIBDIR=lib
make install

To test the build you execute the following to test the C++ tests

cd test
./test_xeus_cpp

and

cd ../../test
pytest -sv test_xcpp_kernel.py

to perform the python tests.

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

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

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

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

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

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

jupyter lite serve --XeusAddon.prefix=$PREFIX

Trying it online

To try out xeus-cpp interactively in your web browser, just click on the binder link:

Documentation

To get started with using xeus-cpp, check out the full documentation

http://xeus-cpp.readthedocs.io

Dependencies

xeus-cpp depends on

• xeus-zmq
• nlohmann_json
• argparse
• CppInterOp

xeus-cpp	xeus-zmq	CppInterOp	pugixml	cpp-argparse	nlohmann_json
main	>=3.0.0,<4.0.0	>=1.4.0	~1.8.1	<3.1	>=3.11.3,<4.0
0.5.0	>=3.0.0,<4.0.0	>=1.3.0	~1.8.1	<3.1	>=3.11.3,<4.0

Versions prior to 0.5.0 have an additional dependency on xtl, clang & cppzmq

xeus-cpp	xeus-zmq	xtl	clang	pugixml	cppzmq	cpp-argparse	nlohmann_json
0.4.0	>=1.0.0,<2.0.0	>=0.7.7,<0.8.0	>=16,<17	~1.8.1	~4.3.0	~2.9	>=3.6.1,<4.0
0.3.0	>=1.0.0,<2.0.0	>=0.7.7,<0.8.0	>=16,<17	~1.8.1	~4.3.0	~2.9	>=3.6.1,<4.0
0.2.0	>=1.0.0,<2.0.0	>=0.7.7,<0.8.0	>=16,<17	~1.8.1	~4.3.0	~2.9	>=3.6.1,<4.0
0.1.0	>=1.0.0,<2.0.0	>=0.7.0,<0.8.0	>=16,<17	~1.8.1	~4.3.0	~2.9	>=3.6.1,<4.0

Contributing

See CONTRIBUTING.md to know how to contribute and set up a development environment.

License

This software is licensed under the BSD 3-Clause License. See the LICENSE file for details.