johanmabille/xeus-cpp

Jupyter kernel for the C++ programming language

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

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.2 cppzmq xtl 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)

First clone the repository, and move into that directory

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

Now you'll want to create a clean mamba environment containing the tools you'll need to do a wasm build. This can be done by executing the following

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

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

emsdk install 3.1.45
emsdk activate 3.1.45
source $CONDA_EMSDK_DIR/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 EMPACK_PREFIX=$MAMBA_ROOT_PREFIX/envs/xeus-cpp-wasm-build
export PREFIX=$MAMBA_ROOT_PREFIX/envs/xeus-cpp-wasm-host 
export CMAKE_PREFIX_PATH=$PREFIX
export CMAKE_SYSTEM_PREFIX_PATH=$PREFIX

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            \
        ..
EMCC_CFLAGS='-sERROR_ON_UNDEFINED_SYMBOLS=0' 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

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
• cppzmq
• argparse
• CppInterOp

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

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

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.