Fix emscripten build instructions (#421)

Author: mcbarton

Emscripten-build-instructions.md

@@ -1,6 +1,6 @@
 # Wasm Build Instructions
 
-It should be noted that the wasm build of CppInterOp is still experimental and subject to change to change.  
+It should be noted that the wasm build of CppInterOp is still experimental and subject to change.  
 
 ## CppInterOp Wasm Build Instructions
 
@@ -22,14 +22,7 @@ To create a wasm build of CppInterOp we make use of the emsdk toolchain. This ca
 support version 3.1.45)
 ```bash
 git clone https://github.com/emscripten-core/emsdk.git
-cd emsdk
-./emsdk install  3.1.45
-```
-
-Go back upto the top level build directory using
-
-```bash
-cd ../..
+./emsdk/emsdk install  3.1.45
 ```
 
 and activate the emsdk environment
@@ -48,11 +41,11 @@ git clone --depth=1 --branch release/19.x https://github.com/llvm/llvm-project.g
 git clone --depth=1 https://github.com/compiler-research/CppInterOp.git
 ```
 
-Now move into the cloned llvm-project folder and apply a required patch
+Now move into the cloned llvm-project folder and apply the required patches
 
 ```bash
 cd ./llvm-project/
-git apply -v ../CppInterOp/patches/llvm/emscripten-clang${{ matrix.clang-runtime }}-*.patch
+git apply -v ../CppInterOp/patches/llvm/emscripten-clang19-*.patch
 ```
 
 We are now in a position to build an emscripten build of llvm by executing the following
@@ -71,8 +64,13 @@ emcmake cmake -DCMAKE_BUILD_TYPE=Release \
                         -DCLANG_ENABLE_ARCMT=OFF \
                         -DCLANG_ENABLE_BOOTSTRAP=OFF \
                         -DCMAKE_CXX_FLAGS="-Dwait4=__syscall_wait4" \
+                        -DLLVM_INCLUDE_BENCHMARKS=OFF                   \
+                        -DLLVM_INCLUDE_EXAMPLES=OFF                     \
+                        -DLLVM_INCLUDE_TESTS=OFF                        \
+                        -DLLVM_ENABLE_THREADS=OFF                       \
                         ../llvm
 emmake make clang -j $(nproc --all)
+emmake make clang-repl -j $(nproc --all)
 emmake make lld -j $(nproc --all)
 ```
 
@@ -82,10 +80,26 @@ Once this finishes building we need to take note of where we built our llvm buil
 export LLVM_BUILD_DIR=$PWD
 ```
 
-We can move onto building the wasm version of CppInterOp. To do this execute the following  
+We can move onto building the wasm version of CppInterOp. We will do this within a Conda environment. We can achieve this  
+by executing (assumes you have micromamba installed and that your shell is initialised for the micromamba install)  
 
 ```bash
 cd ../../CppInterOp/
+micromamba create -f environment-wasm.yml --platform=emscripten-wasm32
+micromamba activate CppInterOp-wasm
+```
+
+You will also want to set a few environment variables  
+
+```bash
+export PREFIX=$CONDA_PREFIX
+export CMAKE_PREFIX_PATH=$PREFIX
+export CMAKE_SYSTEM_PREFIX_PATH=$PREFIX
+```
+
+Now to build CppInterOp execute the following  
+
+```bash
 mkdir build
 cd ./build/
 emcmake cmake -DCMAKE_BUILD_TYPE=Release    \
@@ -96,7 +110,7 @@ emcmake cmake -DCMAKE_BUILD_TYPE=Release    \
                 -DCMAKE_FIND_ROOT_PATH_MODE_PACKAGE=ON            \
                 -DCMAKE_INSTALL_PREFIX=$PREFIX         \
                 ../
-emmake make -j $(nproc --all)
+emmake make -j $(nproc --all) install
 ```
 
 Once this finishes building we need to take note of where we built CppInterOp. This can be done by executing the following
@@ -107,27 +121,16 @@ export CPPINTEROP_BUILD_DIR=$PWD
 
 ## Xeus-cpp-lite Wasm Build Instructions
 
-A project which makes use of the wasm build of CppInterOp is xeus-cpp. xeus-cpp is a C++ Jupyter kernel. To build xeus-cpp we first need to  
-install several other dependencies. To create an Conda environment with this dependencies installed execute the following from the  
-CppInterOp build folder (these instructions will assume you have already installed micromamba)  
-
-```bash
-cd ..
-micromamba create -f environment-wasm.yml --platform=emscripten-wasm32
-micromamba activate CppInterOp-wasm
-export PREFIX=$MAMBA_ROOT_PREFIX/envs/CppInterOp-wasm
-```
-Now we can build an wasm build of xeus-cpp by executing the following  
+A project which makes use of the wasm build of CppInterOp is xeus-cpp. xeus-cpp is a C++ Jupyter kernel. Assuming you are in  
+the CppInterOp build folder, you can build the wasm version of xeus-cpp by executing  
 
 ```bash
-cd ..
+cd ../..
+export SYSROOT_PATH=$PWD/emsdk/upstream/emscripten/cache/sysroot
 git clone --depth=1 https://github.com/compiler-research/xeus-cpp.git
 cd ./xeus-cpp
 mkdir build
 cd build
-export CMAKE_PREFIX_PATH=$PREFIX
-export CMAKE_SYSTEM_PREFIX_PATH=$PREFIX
-export SYSROOT_PATH=$HOME/emsdk/upstream/emscripten/cache/sysroot
 emcmake cmake \
           -DCMAKE_BUILD_TYPE=Release                                     \
           -DCMAKE_PREFIX_PATH=$PREFIX                                    \
@@ -140,11 +143,11 @@ emcmake cmake \
  emmake make -j $(nproc --all) install
 ```
 
-To build Jupyter Lite with this kernel without creating a website you can execute the following
+To build Jupyter Lite website with this kernel locally that you can use for testing execute the following
 
 ```bash
 cd ../..
-micromamba create -n xeus-lite-host jupyterlite-core
+micromamba create -n xeus-lite-host jupyterlite-core -c conda-forge
 micromamba activate xeus-lite-host
 python -m pip install jupyterlite-xeus
 jupyter lite build --XeusAddon.prefix=$PREFIX
@@ -159,7 +162,7 @@ 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
+Once the Jupyter Lite site has built you can test the website locally by executing
 
 ```bash
 jupyter lite serve --XeusAddon.prefix=$PREFIX