Skip to content

Latest commit

 

History

History
158 lines (125 loc) · 6.88 KB

README.md

File metadata and controls

158 lines (125 loc) · 6.88 KB
Raw

xeus-cpp

Build Status Documentation Status Binder codecov

Conda-Forge Anaconda-Server Badge Conda Platforms Anaconda-Server Badge

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

lite-badge

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

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            \
        ..
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:

Binder

Documentation

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

http://xeus-cpp.readthedocs.io

Dependencies

xeus-cpp depends on

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.