Skip to content

Latest commit

 

History

History
167 lines (132 loc) · 6.66 KB

CONTRIBUTING.md

File metadata and controls

167 lines (132 loc) · 6.66 KB

Contributing to xeus-cpp

Xeus and xeus-cpp are subprojects of Project Jupyter and subject to the Jupyter governance and Code of conduct.

General Guidelines

For general documentation about contributing to Jupyter projects, see the Project Jupyter Contributor Documentation.

Community

The Xeus team organizes public video meetings. The schedule for future meetings and minutes of past meetings can be found on our team compass.

Setting up a development environment

First, you need to fork the project. After you have done this clone your forked repo. You can do this by executing the following

git clone https://github.com/<your-github-username>/xeus-cpp.git

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. Once you have miniforge or miniconda installed cd into the xeus-cpp directory and set setup your environment:

cd xeus-cpp
micromamba create -f environment-dev.yml -y
micromamba activate xeus-cpp

Now you can compile the kernel from the source and run the C++ tests 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 check-xeus-cpp
make install

and

cd ../test
pytest -sv test_xcpp_kernel.py

to perform the python tests.

Setting up a development environment (wasm instructions)

First, you need to fork the project. After you have done this clone your forked repo. You can do this by executing the following

git clone https://github.com/<your-github-username>/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 and test it in node by executing the following. Once the test pass, run the install command.

micromamba create -f environment-wasm-host.yml \
--platform=emscripten-wasm32 \
-c https://prefix.dev/emscripten-forge-4x \
-c https://prefix.dev/conda-forge

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                    \
        -DCMAKE_FIND_ROOT_PATH=$PREFIX                    \
        -DSYSROOT_PATH=$SYSROOT_PATH                      \
        ..

emmake make check-xeus-cpp
emmake make install

It is possible to run the Emscripten tests in a headless browser. We will run our tests in a fresh installed browser. Installing the browsers, and running the tests within the installed browsers will be platform dependent. To do this for Chrome and Firefox on MacOS execute the following from the build folder

cd test
wget "https://download.mozilla.org/?product=firefox-latest&os=osx&lang=en-US" -O Firefox-latest.dmg
hdiutil attach Firefox-latest.dmg
cp -r /Volumes/Firefox/Firefox.app $PWD
hdiutil detach /Volumes/Firefox
cd ./Firefox.app/Contents/MacOS/
export PATH="$PWD:$PATH"
cd –

wget https://dl.google.com/chrome/mac/stable/accept_tos%3Dhttps%253A%252F%252Fwww.google.com%252Fintl%252Fen_ph%252Fchrome%252Fterms%252F%26_and_accept_tos%3Dhttps%253A%252F%252Fpolicies.google.com%252Fterms/googlechrome.pkg
pkgutil --expand-full googlechrome.pkg google-chrome
cd ./google-chrome/GoogleChrome.pkg/Payload/Google\ Chrome.app/Contents/MacOS/
export PATH="$PWD:$PATH"
cd –

echo "Running test_xeus_cpp in Firefox"
python $BUILD_PREFIX/bin/emrun.py --browser="firefox" --kill_exit --browser-args="--headless"  test_xeus_cpp.html
echo "Running test_xeus_cpp in Google Chrome"
python $BUILD_PREFIX/bin/emrun.py --browser="Google Chrome" --kill_exit --browser-args="--headless  --no-sandbox"  test_xeus_cpp.html

To run tests in Safari you can make use of safaridriver. How to enable this will depend on your MacOS operating system, and is best to consult safaridriver. You will also need to install the Selenium python package. This only needs to be enable once, and then you can execute the following to run the tests in Safari

echo "Running test_xeus_cpp in Safari"
python $BUILD_PREFIX/bin/emrun.py --no_browser --kill_exit --timeout 60 --browser-args="--headless --no-sandbox"  test_xeus_cpp.html &
python ../../scripts/browser_tests_safari.py test_xeus_cpp.html

To run the browser tests on Ubuntu x86 execute the following from the build folder

cd test
wget https://dl.google.com/linux/direct/google-chrome-stable_current_amd64.deb
dpkg-deb -x google-chrome-stable_current_amd64.deb $PWD/chrome
cd ./chrome/opt/google/chrome/
export PATH="$PWD:$PATH"
cd -

wget https://ftp.mozilla.org/pub/firefox/releases/138.0.1/linux-x86_64/en-GB/firefox-138.0.1.tar.xz
tar -xJf firefox-138.0.1.tar.xz
cd ./firefox
export PATH="$PWD:$PATH"
cd -

echo "Running test_xeus_cpp in Firefox"
python $BUILD_PREFIX/bin/emrun.py --browser="firefox" --kill_exit --timeout 60 --browser-args="--headless"  test_xeus_cpp.html
echo "Running test_xeus_cpp in Google Chrome"
python $BUILD_PREFIX/bin/emrun.py --browser="google-chrome" --kill_exit --timeout 60 --browser-args="--headless --no-sandbox"  test_xeus_cpp.html

To build and test Jupyter Lite with this kernel locally you can execute the following

micromamba create -n xeus-lite-host jupyter_server jupyterlite-xeus -c conda-forge
micromamba activate xeus-lite-host
jupyter lite serve --XeusAddon.prefix=$PREFIX \
                   --XeusAddon.mounts="$PREFIX/share/xeus-cpp/tagfiles:/share/xeus-cpp/tagfiles" \
                   --XeusAddon.mounts="$PREFIX/etc/xeus-cpp/tags.d:/etc/xeus-cpp/tags.d" \
                   --contents README.md \
                   --contents notebooks/xeus-cpp-lite-demo.ipynb \
                   --contents notebooks/tinyraytracer.ipynb \
                   --contents notebooks/images/marie.png \
                   --contents notebooks/audio/audio.wav