Skip to content

Commit 2c6c6b1

Browse files
mcbartonmcbarton
authored
Add emscripten build instructions to online documentation (#450)
1 parent 195f4e7 commit 2c6c6b1

File tree

2 files changed

+194
-0
lines changed

2 files changed

+194
-0
lines changed

‎docs/Emscripten-build-instructions.rst

Lines changed: 193 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,193 @@
1+
#########################
2+
Wasm Build Instructions
3+
#########################
4+
5+
It should be noted that the wasm build of CppInterOp is still
6+
experimental and subject to change.
7+
8+
************************************
9+
CppInterOp Wasm Build Instructions
10+
************************************
11+
12+
This document first starts with the instructions on how to build a wasm
13+
build of CppInterOp. Before we start it should be noted that unlike the
14+
non wasm version of CppInterOp we currently only support the Clang-REPL
15+
backend using llvm>19 for osx and Linux. We will first make folder to
16+
build our wasm build of CppInterOp. This can be done by executing the
17+
following command
18+
19+
.. code:: bash
20+
21+
mkdir CppInterOp-wasm
22+
23+
Now move into this directory using the following command
24+
25+
.. code:: bash
26+
27+
cd ./CppInterOp-wasm
28+
29+
To create a wasm build of CppInterOp we make use of the emsdk toolchain.
30+
This can be installed by executing (we only currently support version
31+
3.1.45)
32+
33+
.. code:: bash
34+
35+
git clone https://github.com/emscripten-core/emsdk.git
36+
./emsdk/emsdk install 3.1.45
37+
38+
and activate the emsdk environment
39+
40+
.. code:: bash
41+
42+
./emsdk/emsdk activate 3.1.45
43+
source ./emsdk/emsdk_env.sh
44+
45+
Now clone the 19.x release of the LLVM project repository and CppInterOp
46+
(the building of the emscripten version of llvm can be avoided by
47+
executing micromamba install llvm -c
48+
<https://repo.mamba.pm/emscripten-forge> and setting the LLVM_BUILD_DIR
49+
appropriately)
50+
51+
.. code:: bash
52+
53+
git clone --depth=1 --branch release/19.x https://github.com/llvm/llvm-project.git
54+
git clone --depth=1 https://github.com/compiler-research/CppInterOp.git
55+
56+
Now move into the cloned llvm-project folder and apply the required
57+
patches
58+
59+
.. code:: bash
60+
61+
cd ./llvm-project/
62+
git apply -v ../CppInterOp/patches/llvm/emscripten-clang19-*.patch
63+
64+
We are now in a position to build an emscripten build of llvm by
65+
executing the following
66+
67+
.. code:: bash
68+
69+
mkdir build
70+
cd build
71+
emcmake cmake -DCMAKE_BUILD_TYPE=Release \
72+
-DLLVM_HOST_TRIPLE=wasm32-unknown-emscripten \
73+
-DLLVM_ENABLE_ASSERTIONS=ON \
74+
-DLLVM_TARGETS_TO_BUILD="WebAssembly" \
75+
-DLLVM_ENABLE_LIBEDIT=OFF \
76+
-DLLVM_ENABLE_PROJECTS="clang;lld" \
77+
-DLLVM_ENABLE_ZSTD=OFF \
78+
-DLLVM_ENABLE_LIBXML2=OFF \
79+
-DCLANG_ENABLE_STATIC_ANALYZER=OFF \
80+
-DCLANG_ENABLE_ARCMT=OFF \
81+
-DCLANG_ENABLE_BOOTSTRAP=OFF \
82+
-DCMAKE_CXX_FLAGS="-Dwait4=__syscall_wait4" \
83+
-DLLVM_INCLUDE_BENCHMARKS=OFF \
84+
-DLLVM_INCLUDE_EXAMPLES=OFF \
85+
-DLLVM_INCLUDE_TESTS=OFF \
86+
-DLLVM_ENABLE_THREADS=OFF \
87+
../llvm
88+
emmake make clang -j $(nproc --all)
89+
emmake make clang-repl -j $(nproc --all)
90+
emmake make lld -j $(nproc --all)
91+
92+
Once this finishes building we need to take note of where we built our
93+
llvm build. This can be done by executing the following
94+
95+
.. code:: bash
96+
97+
export LLVM_BUILD_DIR=$PWD
98+
99+
We can move onto building the wasm version of CppInterOp. We will do
100+
this within a Conda environment. We can achieve this by executing
101+
(assumes you have micromamba installed and that your shell is
102+
initialised for the micromamba install)
103+
104+
.. code:: bash
105+
106+
cd ../../CppInterOp/
107+
micromamba create -f environment-wasm.yml --platform=emscripten-wasm32
108+
micromamba activate CppInterOp-wasm
109+
110+
You will also want to set a few environment variables
111+
112+
.. code:: bash
113+
114+
export PREFIX=$CONDA_PREFIX
115+
export CMAKE_PREFIX_PATH=$PREFIX
116+
export CMAKE_SYSTEM_PREFIX_PATH=$PREFIX
117+
118+
Now to build CppInterOp execute the following
119+
120+
.. code:: bash
121+
122+
mkdir build
123+
cd ./build/
124+
emcmake cmake -DCMAKE_BUILD_TYPE=Release \
125+
-DLLVM_DIR=$LLVM_BUILD_DIR/lib/cmake/llvm \
126+
-DLLD_DIR=$LLVM_BUILD_DIR/lib/cmake/lld \
127+
-DClang_DIR=$LLVM_BUILD_DIR/lib/cmake/clang \
128+
-DBUILD_SHARED_LIBS=ON \
129+
-DCMAKE_FIND_ROOT_PATH_MODE_PACKAGE=ON \
130+
-DCMAKE_INSTALL_PREFIX=$PREFIX \
131+
../
132+
emmake make -j $(nproc --all) install
133+
134+
Once this finishes building we need to take note of where we built
135+
CppInterOp. This can be done by executing the following
136+
137+
.. code:: bash
138+
139+
export CPPINTEROP_BUILD_DIR=$PWD
140+
141+
## Xeus-cpp-lite Wasm Build Instructions
142+
143+
A project which makes use of the wasm build of CppInterOp is xeus-cpp.
144+
xeus-cpp is a C++ Jupyter kernel. Assuming you are in the CppInterOp
145+
build folder, you can build the wasm version of xeus-cpp by executing
146+
147+
.. code:: bash
148+
149+
cd ../..
150+
export SYSROOT_PATH=$PWD/emsdk/upstream/emscripten/cache/sysroot
151+
git clone --depth=1 https://github.com/compiler-research/xeus-cpp.git
152+
cd ./xeus-cpp
153+
mkdir build
154+
cd build
155+
emcmake cmake \
156+
-DCMAKE_BUILD_TYPE=Release \
157+
-DCMAKE_PREFIX_PATH=$PREFIX \
158+
-DCMAKE_INSTALL_PREFIX=$PREFIX \
159+
-DXEUS_CPP_EMSCRIPTEN_WASM_BUILD=ON \
160+
-DCMAKE_FIND_ROOT_PATH_MODE_PACKAGE=ON \
161+
-DCppInterOp_DIR="$CPPINTEROP_BUILD_DIR/lib/cmake/CppInterOp" \
162+
-DSYSROOT_PATH=$SYSROOT_PATH \
163+
..
164+
emmake make -j $(nproc --all) install
165+
166+
To build Jupyter Lite website with this kernel locally that you can use
167+
for testing execute the following
168+
169+
.. code:: bash
170+
171+
cd ../..
172+
micromamba create -n xeus-lite-host jupyterlite-core -c conda-forge
173+
micromamba activate xeus-lite-host
174+
python -m pip install jupyterlite-xeus jupyter_server
175+
jupyter lite build --XeusAddon.prefix=$PREFIX --contents xeus-cpp/notebooks/xeus-cpp-lite-demo.ipynb
176+
177+
We now need to shift necessary files like `xcpp.data` which contains the
178+
binary representation of the file(s) we want to include in our
179+
application. As of now this would contain all important files like
180+
Standard Headers, Libraries etc coming out of emscripten's sysroot.
181+
Assuming we are still inside build we should do the following
182+
183+
.. code:: bash
184+
185+
cp $PREFIX/bin/xcpp.data _output/extensions/@jupyterlite/xeus/static
186+
cp $PREFIX/lib/libclangCppInterOp.so _output/extensions/@jupyterlite/xeus/static
187+
188+
Once the Jupyter Lite site has built you can test the website locally by
189+
executing
190+
191+
.. code:: bash
192+
193+
jupyter lite serve --XeusAddon.prefix=$PREFIX

‎docs/index.rst

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -20,6 +20,7 @@ C++ to simpler, more interactive languages like Python.
2020

2121

2222
InstallationAndUsage
23+
Emscripten-build-instructions
2324
UsingCppInterOp
2425
reference
2526
tutorials

0 commit comments

Comments
 (0)