Merge branch 'main' into Update-to-emsdk-3.1.73

Author: mcbarton

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

@@ -2,15 +2,16 @@ name: Build and Deploy
 
 on:
   workflow_dispatch:
+  pull_request:
   push:
     branches:
     - main
-    
+
 permissions:
   contents: read
   pages: write
   id-token: write
-    
+
 jobs:
   build:
     runs-on: ${{ matrix.os }}
@@ -20,44 +21,36 @@ jobs:
       matrix:
         include:
           - name: Github-page
-            os: macos-15
-            emsdk_ver: "3.1.73"
+            os: ubuntu-24.04
     steps:
       - uses: actions/checkout@v4
         with:
           fetch-depth: 0
-        
+
       - name: install mamba
         uses: mamba-org/setup-micromamba@main
         with:
+          environment-file: environment-wasm-build.yml
           init-shell: bash
+          environment-name: xeus-cpp-wasm-build
 
       - name: Setup default Build Type on *nux
         if: ${{ runner.os != 'windows' }}
         run: |
           echo "ncpus=$(nproc --all)" >> $GITHUB_ENV
-          
-      - name: Setup emsdk
-        shell: bash -l {0}
-        run: |
-          cd $HOME
-          git clone --depth=1 https://github.com/emscripten-core/emsdk.git
-          cd emsdk
-          ./emsdk install  ${{ matrix.emsdk_ver }}    
 
       - name: Build xeus-cpp
         shell: bash -l {0}
         run: |
-          $HOME/emsdk/emsdk activate ${{matrix.emsdk_ver}}
-          source $HOME/emsdk/emsdk_env.sh
           micromamba create -f environment-wasm-host.yml --platform=emscripten-wasm32
-          
+
           mkdir build
           pushd build
 
+          export BUILD_PREFIX=$MAMBA_ROOT_PREFIX/envs/xeus-cpp-wasm-build
           export PREFIX=$MAMBA_ROOT_PREFIX/envs/xeus-cpp-wasm-host 
           echo "PREFIX=$PREFIX" >> $GITHUB_ENV
-          export SYSROOT_PATH=$HOME/emsdk/upstream/emscripten/cache/sysroot
+          export SYSROOT_PATH=$BUILD_PREFIX/opt/emsdk/upstream/emscripten/cache/sysroot
 
           emcmake cmake \
             -DCMAKE_BUILD_TYPE=Release                        \
@@ -66,9 +59,9 @@ jobs:
             -DCMAKE_FIND_ROOT_PATH=$PREFIX                    \
             -DSYSROOT_PATH=$SYSROOT_PATH                      \
             ..
-          emmake make -j  ${{ env.ncpus }} install
+          emmake make -j ${{ env.ncpus }} install
 
-      - name: Jupyter Lite integration 
+      - name: Jupyter Lite integration
         shell: bash -l {0}
         run: |
           micromamba create -n xeus-lite-host jupyterlite-core jupyter_server
@@ -78,6 +71,8 @@ jobs:
               --XeusAddon.prefix=${{ env.PREFIX }} \
               --contents README.md \
               --contents notebooks/xeus-cpp-lite-demo.ipynb \
+              --contents notebooks/images/marie.png \
+              --contents notebooks/audio/audio.wav \
               --output-dir dist
 
       - name: Upload artifact
@@ -87,12 +82,15 @@ jobs:
 
   deploy:
     needs: build
+    if: github.ref == 'refs/heads/main'
     permissions:
       pages: write
       id-token: write
+
     environment:
       name: github-pages
       url: ${{ steps.deployment.outputs.page_url }}
+
     runs-on: ubuntu-24.04
     steps:
       - name: Deploy to GitHub Pages

.github/workflows/main.yml

@@ -191,25 +191,10 @@ jobs:
       matrix:
         include:
           - name: ubu24
-            os: ubuntu-24.04
-            emsdk_ver: "3.1.73"
-            micromamba_shell_init: bash
-          - name: ubu22
-            os: ubuntu-22.04
-            emsdk_ver: "3.1.73"
-            micromamba_shell_init: bash
-          - name: osx13-x86
-            os: macos-13
-            emsdk_ver: "3.1.73"
-            micromamba_shell_init: bash
-          - name: osx14-arm
-            os: macos-14
-            emsdk_ver: "3.1.73"
+            os: ubuntu-24.04-arm
             micromamba_shell_init: bash
           - name: osx15-arm
             os: macos-15
-            emsdk_ver: "3.1.73"
-            micromamba_shell_init: bash
 
     steps:
       - uses: actions/checkout@v4

CMakeLists.txt

@@ -389,7 +389,16 @@ set(XCPP_HEADERS
 add_library(xeus-cpp-headers INTERFACE)
 set_target_properties(xeus-cpp-headers PROPERTIES PUBLIC_HEADER "${XCPP_HEADERS}")
 
-install(TARGETS xeus-cpp-headers PUBLIC_HEADER DESTINATION ${CMAKE_INSTALL_INCLUDEDIR}/xcpp)
+if (EMSCRIPTEN)
+    execute_process(COMMAND ${CMAKE_COMMAND} -E make_directory ${SYSROOT_PATH}/include/xcpp)
+
+    message(STATUS "Moving headers to ${SYSROOT_PATH}/include/xcpp")
+    foreach(header ${XCPP_HEADERS})
+        file(COPY ${header} DESTINATION ${SYSROOT_PATH}/include/xcpp)
+    endforeach()
+else ()
+    install(TARGETS xeus-cpp-headers PUBLIC_HEADER DESTINATION ${CMAKE_INSTALL_INCLUDEDIR}/xcpp)
+endif()
 
 # xeus-cpp
 # ========

CONTRIBUTING.md

@@ -57,3 +57,54 @@ and the python tests by executing
 cd ../../test
 pytest -sv test_xcpp_kernel.py
 ```
+
+## 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 folowing
+
+```bash
+git clone https://github.com/<your-github-username>/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
+```bash
+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
+```bash
+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 SYSROOT_PATH=$HOME/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
+```bash
+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
+```bash
+jupyter lite serve --XeusAddon.prefix=$PREFIX
+```

docs/source/InstallationAndUsage.rst

@@ -46,14 +46,17 @@ 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
+
 .. code-block:: bash
+
     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.73" and activate it. You can get this by executing the following
 
 .. code-block:: bash
+
     cd $HOME
     git clone https://github.com/emscripten-core/emsdk.git
     cd emsdk
@@ -65,6 +68,7 @@ You'll now want to make sure you're using emsdk version "3.1.73" and activate it
 You are now in a position to build the xeus-cpp kernel. You build it by executing the following
 
 .. code-block:: bash
+
     micromamba create -f environment-wasm-host.yml --platform=emscripten-wasm32
     mkdir build
     pushd build
@@ -83,22 +87,16 @@ You are now in a position to build the xeus-cpp kernel. You build it by executin
 To build Jupyter Lite with this kernel without creating a website you can execute the following
 
 .. code-block:: bash
+
     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
 
-We now need to shift necessary files like `xcpp.data` which contains the binary representation of the file(s)
-we want to include in our application. As of now this would contain all important files like Standard Headers,
-Libraries etc coming out of emscripten's sysroot. Assuming we are still inside build we should do the following
-
-.. code-block:: bash
-    cp $PREFIX/bin/xcpp.data _output/extensions/@jupyterlite/xeus/static
-    cp $PREFIX/lib/libclangCppInterOp.so _output/extensions/@jupyterlite/xeus/static
-
 Once the Jupyter Lite site has built you can test the website locally by executing
 
 .. code-block:: bash
+
     jupyter lite serve --XeusAddon.prefix=$PREFIX
 
 Installing from conda-forge

environment-wasm-build.yml

@@ -0,0 +1,7 @@
+name: xeus-cpp-wasm-build
+channels:
+  - https://repo.mamba.pm/emscripten-forge
+  - conda-forge
+dependencies:
+  - cmake
+  - emscripten_emscripten-wasm32==3.1.45

environment-wasm-host.yml

@@ -3,6 +3,7 @@ channels:
   - https://repo.mamba.pm/emscripten-forge
   - https://repo.mamba.pm/conda-forge
 dependencies:
+  - emscripten-abi==3.1.45
   - nlohmann_json
   - xeus-lite
   - xeus