Skip to content

Commit c9df3e3

Browse files
mcbartonmcbarton
authored
Add Emscripten Build Instructions (#390)
* Add Emscripten Build Instructions * Address comments in the PR * Update Emscripten-build-instructions.md
1 parent 5d81a80 commit c9df3e3

File tree

1 file changed

+157
-0
lines changed

1 file changed

+157
-0
lines changed

‎Emscripten-build-instructions.md

Lines changed: 157 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,157 @@
1+
# Wasm Build Instructions
2+
3+
It should be noted that the wasm build of CppInterOp is still experimental and subject to change to change.
4+
5+
## CppInterOp Wasm Build Instructions
6+
7+
This document first starts with the instructions on how to build a wasm build of CppInterOp. Before we start it should be noted that
8+
unlike the non wasm version of CppInterOp we currently only support the Clang-REPL backend using llvm>19 for osx and Linux.
9+
We will first make folder to build our wasm build of CppInterOp. This can be done by executing the following command
10+
11+
```bash
12+
mkdir CppInterOp-wasm
13+
```
14+
15+
Now move into this directory using the following command
16+
17+
```bash
18+
cd ./CppInterOp-wasm
19+
```
20+
21+
To create a wasm build of CppInterOp we make use of the emsdk toolchain. This can be installed by executing (we only currently
22+
support version 3.1.45)
23+
```bash
24+
git clone https://github.com/emscripten-core/emsdk.git
25+
cd emsdk
26+
./emsdk install 3.1.45
27+
```
28+
29+
Go back upto the top level build directory using
30+
31+
```bash
32+
cd ../..
33+
```
34+
35+
and activate the emsdk environment
36+
37+
```bash
38+
./emsdk/emsdk activate 3.1.45
39+
source ./emsdk/emsdk_env.sh
40+
```
41+
42+
Now clone the 19.x release of the LLVM project repository and CppInterOp (the building of the emscripten version of llvm can be
43+
avoided by executing micromamba install llvm -c <https://repo.mamba.pm/emscripten-forge> and setting the LLVM_BUILD_DIR appropriately)
44+
45+
46+
```bash
47+
git clone --depth=1 --branch release/19.x https://github.com/llvm/llvm-project.git
48+
git clone --depth=1 https://github.com/compiler-research/CppInterOp.git
49+
```
50+
51+
Now move into the cloned llvm-project folder and apply a required patch
52+
53+
```bash
54+
cd ./llvm-project/
55+
git apply -v ../CppInterOp/patches/llvm/emscripten-clang${{ matrix.clang-runtime }}-*.patch
56+
```
57+
58+
We are now in a position to build an emscripten build of llvm by executing the following
59+
```bash
60+
mkdir build
61+
cd build
62+
emcmake cmake -DCMAKE_BUILD_TYPE=Release \
63+
-DLLVM_HOST_TRIPLE=wasm32-unknown-emscripten \
64+
-DLLVM_ENABLE_ASSERTIONS=ON \
65+
-DLLVM_TARGETS_TO_BUILD="WebAssembly" \
66+
-DLLVM_ENABLE_LIBEDIT=OFF \
67+
-DLLVM_ENABLE_PROJECTS="clang;lld" \
68+
-DLLVM_ENABLE_ZSTD=OFF \
69+
-DLLVM_ENABLE_LIBXML2=OFF \
70+
-DCLANG_ENABLE_STATIC_ANALYZER=OFF \
71+
-DCLANG_ENABLE_ARCMT=OFF \
72+
-DCLANG_ENABLE_BOOTSTRAP=OFF \
73+
-DCMAKE_CXX_FLAGS="-Dwait4=__syscall_wait4" \
74+
../llvm
75+
emmake make clang -j $(nproc --all)
76+
emmake make lld -j $(nproc --all)
77+
```
78+
79+
Once this finishes building we need to take note of where we built our llvm build. This can be done by executing the following
80+
81+
```bash
82+
export LLVM_BUILD_DIR=$PWD
83+
```
84+
85+
We can move onto building the wasm version of CppInterOp. To do this execute the following
86+
87+
```bash
88+
cd ../../CppInterOp/
89+
mkdir build
90+
cd ./build/
91+
emcmake cmake -DCMAKE_BUILD_TYPE=Release \
92+
-DUSE_CLING=OFF \
93+
-DUSE_REPL=ON \
94+
-DLLVM_DIR=$LLVM_BUILD_DIR/lib/cmake/llvm \
95+
-DLLD_DIR=$LLVM_BUILD_DIR/lib/cmake/lld \
96+
-DClang_DIR=$LLVM_BUILD_DIR/lib/cmake/clang \
97+
-DBUILD_SHARED_LIBS=ON \
98+
-DCMAKE_FIND_ROOT_PATH_MODE_PACKAGE=ON \
99+
-DCMAKE_INSTALL_PREFIX=$PREFIX \
100+
../
101+
emmake make -j $(nproc --all)
102+
```
103+
104+
Once this finishes building we need to take note of where we built CppInterOp. This can be done by executing the following
105+
106+
```bash
107+
export CPPINTEROP_BUILD_DIR=$PWD
108+
```
109+
110+
## Xeus-cpp-lite Wasm Build Instructions
111+
112+
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
113+
install several other dependencies. To create an Conda environment with this dependencies installed execute the following from the
114+
CppInterOp build folder (these instructions will assume you have already installed micromamba)
115+
116+
```bash
117+
cd ..
118+
micromamba create -f environment-wasm.yml --platform=emscripten-wasm32
119+
micromamba activate CppInterOp-wasm
120+
export PREFIX=$MAMBA_ROOT_PREFIX/envs/CppInterOp-wasm
121+
```
122+
Now we can build an wasm build of xeus-cpp by executing the following
123+
124+
```bash
125+
cd ..
126+
git clone --depth=1 https://github.com/compiler-research/xeus-cpp.git
127+
cd ./xeus-cpp
128+
mkdir build
129+
cd build
130+
export CMAKE_PREFIX_PATH=$PREFIX
131+
export CMAKE_SYSTEM_PREFIX_PATH=$PREFIX
132+
emcmake cmake \
133+
-DCMAKE_BUILD_TYPE=Release \
134+
-DCMAKE_PREFIX_PATH=$PREFIX \
135+
-DCMAKE_INSTALL_PREFIX=$PREFIX \
136+
-DXEUS_CPP_EMSCRIPTEN_WASM_BUILD=ON \
137+
-DCMAKE_FIND_ROOT_PATH_MODE_PACKAGE=ON \
138+
-DCppInterOp_DIR="$CPPINTEROP_BUILD_DIR/lib/cmake/CppInterOp" \
139+
..
140+
emmake make -j $(nproc --all) install
141+
```
142+
143+
To build Jupyter Lite with this kernel without creating a website you can execute the following
144+
145+
```bash
146+
cd ../..
147+
micromamba create -n xeus-lite-host jupyterlite-core
148+
micromamba activate xeus-lite-host
149+
python -m pip install jupyterlite-xeus
150+
jupyter lite build --XeusAddon.prefix=$PREFIX
151+
```
152+
153+
Once the Jupyter Lite site has built you can test the website locally by executing
154+
155+
```bash
156+
jupyter lite serve --XeusAddon.prefix=$PREFIX
157+
```

0 commit comments

Comments
 (0)