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.0,<4.0" 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 are using the same emsdk as the rest of our dependencies. This can be achieved by executing the following

micromamba create -f environment-wasm-build.yml -y
micromamba activate xeus-cpp-wasm-build

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
cd build
export BUILD_PREFIX=$MAMBA_ROOT_PREFIX/envs/xeus-cpp-wasm-build
export PREFIX=$MAMBA_ROOT_PREFIX/envs/xeus-cpp-wasm-host
export SYSROOT_PATH=$BUILD_PREFIX/opt/emsdk/upstream/emscripten/cache/sysroot

emcmake cmake \
        -DCMAKE_BUILD_TYPE=Release                        \
        -DCMAKE_INSTALL_PREFIX=$PREFIX                    \
        -DXEUS_CPP_EMSCRIPTEN_WASM_BUILD=ON               \
        -DCMAKE_FIND_ROOT_PATH=$PREFIX                    \
        -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 -c conda-forge
micromamba activate xeus-lite-host
python -m pip install jupyterlite-xeus
jupyter lite build --XeusAddon.prefix=$PREFIX

Once the Jupyter Lite site has built you can test the website locally by executing

jupyter lite serve --XeusAddon.prefix=$PREFIX

To test the lite build you can execute the following to run the C++ tests built against emscripten

cd test
node test_xeus_cpp.js

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.5.0	~1.8.1	>=3.0,<4.0	>=3.11.3,<4.0
0.6.0	>=3.0.0,<4.0.0	>=1.5.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.