Use check-xeus-cpp target to run C++ tests for both native and Emscripten platform (+ make build instructions consistent across files) (#386)

Author: mcbarton

.github/workflows/deploy-github-page.yml

@@ -42,7 +42,7 @@ jobs:
         run: |
           echo "ncpus=$(nproc --all)" >> $GITHUB_ENV
 
-      - name: Build xeus-cpp
+      - name: Build and test xeus-cpp in node, then install
         shell: bash -l {0}
         run: |
           micromamba create -f environment-wasm-host.yml --platform=emscripten-wasm32
@@ -64,9 +64,10 @@ jobs:
             -DSYSROOT_PATH=$SYSROOT_PATH                      \
             -DCMAKE_COMPILE_WARNING_AS_ERROR=ON            \
             ..
+          emmake make -j ${{ env.ncpus }} check-xeus-cpp
           emmake make -j ${{ env.ncpus }} install
 
-      - name: Test xeus-cpp C++ Emscripten
+      - name: Test Emscripten xeus-cpp in browser
         shell: bash -l {0}
         run: |
           set -e
@@ -134,7 +135,6 @@ jobs:
             echo "Running test_xeus_cpp in Google Chrome"
             python ${{ env.BUILD_PREFIX }}/bin/emrun.py --browser="google-chrome" --kill_exit --timeout 60 --browser-args="--headless  --no-sandbox"  test_xeus_cpp.html
           fi
-          node test_xeus_cpp.js
         timeout-minutes: 4
 
       - name: Jupyter Lite integration

.github/workflows/main.yml

@@ -113,37 +113,23 @@ jobs:
           -DCMAKE_COMPILE_WARNING_AS_ERROR=ON            \
            ${{ matrix.extra_cmake_flags }} 
 
-      - name: build & install
+      - name: build, run C++ tests & install
         if: ${{ runner.os == 'windows' }}
         shell: cmd /C call {0}
         run: |
           call C:\Users\runneradmin\micromamba-root\condabin\micromamba.bat activate xeus-cpp
           cd build
           set CL=/MP
+          nmake check-xeus-cpp
           nmake install
 
-      - name: build & install
+      - name: build, run C++ tests & install
         if: ${{ runner.os != 'windows' }}
         shell: bash -l {0}
         run: |
           cd build
           make install -j ${{ env.ncpus }}
-
-      - name: Test xeus-cpp C++ Unix Systems
-        if: ${{ runner.os != 'windows' }}
-        shell: bash -l {0}
-        run: |
-          cd build/test
-          ./test_xeus_cpp
-        timeout-minutes: 4
-
-      - name: Test xeus-cpp C++ Windows Systems
-        if: ${{ runner.os == 'windows' }}
-        shell: cmd /C call {0}
-        run: |
-          call C:\Users\runneradmin\micromamba-root\condabin\micromamba.bat activate xeus-cpp
-          cd build\test
-          .\test_xeus_cpp.exe
+          make -j ${{ env.ncpus }} check-xeus-cpp
 
       - name: Python tests Unix Systems
         if: ${{ runner.os != 'windows' }}
@@ -225,7 +211,7 @@ jobs:
             echo "ncpus=$(nproc --all)" >> $GITHUB_ENV
           fi
 
-      - name: Build xeus-cpp
+      - name: Build and test xeus-cpp in node, then install
         shell: bash -l {0}
         run: |
           micromamba create -f environment-wasm-host.yml --platform=emscripten-wasm32
@@ -247,9 +233,10 @@ jobs:
             -DSYSROOT_PATH=$SYSROOT_PATH                      \
             -DCMAKE_COMPILE_WARNING_AS_ERROR=ON            \
             ..
+          emmake make -j ${{ env.ncpus }} check-xeus-cpp
           emmake make -j ${{ env.ncpus }} install
 
-      - name: Test xeus-cpp C++ Emscripten
+      - name: Test Emscripten xeus-cpp in browser
         shell: bash -l {0}
         run: |
           export BUILD_PREFIX=$MAMBA_ROOT_PREFIX/envs/xeus-cpp-wasm-build
@@ -323,7 +310,6 @@ jobs:
             echo "Running test_xeus_cpp in Google Chrome"
             python ${{ env.BUILD_PREFIX }}/bin/emrun.py --browser="google-chrome" --kill_exit --timeout 60 --browser-args="--headless --no-sandbox"  test_xeus_cpp.html
           fi
-          node test_xeus_cpp.js
         timeout-minutes: 4
 
       - name: Jupyter Lite integration

CONTRIBUTING.md

@@ -35,27 +35,26 @@ micromamba create -f environment-dev.yml -y
 micromamba activate xeus-cpp
 ```
 
-You are now in a position to install xeus-cpp into this environment. You can do this by executing
+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)
 
 ```bash
 mkdir build
 cd build
-cmake -D CMAKE_BUILD_TYPE=Release -D CMAKE_PREFIX_PATH=$CONDA_PREFIX -D CMAKE_INSTALL_PREFIX=$CONDA_PREFIX -D CMAKE_INSTALL_LIBDIR=lib ..
-make install
+cmake .. -D CMAKE_PREFIX_PATH=$CONDA_PREFIX -D CMAKE_INSTALL_PREFIX=$CONDA_PREFIX -D CMAKE_INSTALL_LIBDIR=lib
+make check-xeus-cpp
 ```
 
-To check that everything is installed correctly you can run the c++ tests by executing the following
+and
 
 ```bash
-cd ./test
-./test_xeus_cpp
+cd ../../test
+pytest -sv test_xcpp_kernel.py
 ```
 
-and the python tests by executing
+to perform the python tests. After you have checked that the kernel passes all the tests, you can install it by executing
 
 ```bash
-cd ../../test
-pytest -sv test_xcpp_kernel.py
+make install
 ```
 
 ## Setting up a development environment (wasm instructions)
@@ -75,14 +74,15 @@ 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
+You are now in a position to build the xeus-cpp kernel. You build and test it in node by executing the following
+
 ```bash
 micromamba create -f environment-wasm-host.yml --platform=emscripten-wasm32
 mkdir build
 cd build
-export BUILD_TOOLS_PREFIX=$MAMBA_ROOT_PREFIX/envs/xeus-cpp-wasm-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_TOOLS_PREFIX/opt/emsdk/upstream/emscripten/cache/sysroot
+export SYSROOT_PATH=$BUILD_PREFIX/opt/emsdk/upstream/emscripten/cache/sysroot
 
 emcmake cmake \
         -DCMAKE_BUILD_TYPE=Release                        \
@@ -91,14 +91,7 @@ emcmake cmake \
         -DCMAKE_FIND_ROOT_PATH=$PREFIX                    \
         -DSYSROOT_PATH=$SYSROOT_PATH                      \
         ..
-emmake make install
-```
-
-To test the lite build you can execute the following to run the C++ tests built against emscripten in node
-
-```bash
-cd test
-node test_xeus_cpp.js
+emmake make check-xeus-cpp
 ```
 
 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
@@ -155,6 +148,12 @@ 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
 ```
 
+After you have checked that the kernel passes all the tests, you can install it by executing
+
+```bash
+emmake make install
+```
+
 To build and test Jupyter Lite with this kernel locally you can execute the following
 ```bash
 micromamba create -n xeus-lite-host jupyterlite-core=0.6 jupyter_server jupyterlite-xeus -c conda-forge

README.md

@@ -57,24 +57,23 @@ micromamba create -f environment-dev.yml
 micromamba activate xeus-cpp
 micromamba install jupyterlab -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)
+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)
 ```bash
 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
-```bash
-cd test
-./test_xeus_cpp
+make check-xeus-cpp
 ```
 and
 ```bash
 cd ../../test
 pytest -sv test_xcpp_kernel.py
 ```
-to perform the python tests.
+to perform the python tests. After you have checked that the kernel passes all the tests, you can install it by executing
+
+```bash
+make install
+```
 
 ## Installation within a mamba environment (wasm build instructions)
 
@@ -91,7 +90,7 @@ 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
+You are now in a position to build the xeus-cpp kernel. You build and test it in node by executing the following
 ```bash
 micromamba create -f environment-wasm-host.yml --platform=emscripten-wasm32
 mkdir build
@@ -107,14 +106,7 @@ emcmake cmake \
         -DCMAKE_FIND_ROOT_PATH=$PREFIX                    \
         -DSYSROOT_PATH=$SYSROOT_PATH                      \
         ..
-emmake make install
-```
-
-To test the lite build you can execute the following to run the C++ tests built against emscripten in node
-
-```bash
-cd test
-node test_xeus_cpp.js
+emmake make check-xeus-cpp
 ```
 
 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
@@ -171,6 +163,12 @@ 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
 ```
 
+After you have checked that the kernel passes all the tests, you can install it by executing
+
+```bash
+emmake make install
+```
+
 To build and test Jupyter Lite with this kernel locally you can execute the following
 ```bash
 micromamba create -n xeus-lite-host jupyterlite-core=0.6 jupyter_server jupyterlite-xeus -c conda-forge

docs/source/InstallationAndUsage.rst

@@ -25,15 +25,28 @@ this environment with mamba by executing the following
     micromamba activate xeus-cpp
     micromamba install jupyterlab -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)
+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)
 
 .. code-block:: bash
 
-    mkdir build && cd build
-    cmake .. -D CMAKE_PREFIX_PATH=$CONDA_PREFIX -D CMAKE_INSTALL_PREFIX=$CONDA_PREFIX 
-    -D CMAKE_INSTALL_LIBDIR=lib
-    make && make install
+   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
+
+and
+
+.. code-block:: bash
+
+   cd ../../test
+   pytest -sv test_xcpp_kernel.py
+
+to perform the python tests. After you have checked that the kernel passes all the tests, you can install it by executing
+
+.. code-block:: bash
+
+   make install
 
 Installation within a mamba environment (wasm build instructions)
 ========================
@@ -55,32 +68,25 @@ 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
+You are now in a position to build the xeus-cpp kernel. You build and test it in node by executing the following
 
 .. code-block:: bash
 
     micromamba create -f environment-wasm-host.yml --platform=emscripten-wasm32
     mkdir build
     cd build
-    export BUILD_TOOLS_PREFIX=$MAMBA_ROOT_PREFIX/envs/xeus-cpp-wasm-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_TOOLS_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
+    export SYSROOT_PATH=$BUILD_PREFIX/opt/emsdk/upstream/emscripten/cache/sysroot
 
-
-To test the lite build you can execute the following to run the C++ tests built against emscripten in node
-
-.. code-block:: bash
-
-    cd test
-    node test_xeus_cpp.js
+    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 check-xeus-cpp
 
 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
 
@@ -136,6 +142,12 @@ To do this on Ubuntu x86 execute the following
     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
 
+After you have checked that the kernel passes all the tests, you can install it by executing
+
+.. code-block:: bash
+
+    emmake make install
+
 To build and test Jupyter Lite with this kernel locally you can execute the following
 
 .. code-block:: bash

test/CMakeLists.txt

@@ -96,6 +96,10 @@ if(EMSCRIPTEN)
         ${CMAKE_CURRENT_BINARY_DIR}/libxeus.so
         COMMENT "Copying libxeus.so to the test directory"
     )
+    add_custom_target(check-xeus-cpp
+        COMMAND ${CMAKE_COMMAND} -E chdir ${CMAKE_CURRENT_BINARY_DIR} node test_xeus_cpp.js
+        DEPENDS test_xeus_cpp
+    )
 else()
     find_package(Threads)
 
@@ -117,5 +121,5 @@ else()
     target_link_libraries(test_xeus_cpp xeus-cpp doctest::doctest ${CMAKE_THREAD_LIBS_INIT})
     target_include_directories(test_xeus_cpp PRIVATE ${XEUS_CPP_INCLUDE_DIR})
 
-    add_custom_target(xtest COMMAND test_xeus_cpp DEPENDS test_xeus_cpp)
+    add_custom_target(check-xeus-cpp COMMAND test_xeus_cpp DEPENDS test_xeus_cpp)
 endif()