11# Proxy-Wasm C++ SDK Build Instructions
22
33The C++ SDK has dependencies on specific versions of the C++ WebAssembly
4- toolchain [ Emscripten] ( https://emscripten.org ) and the protobuf library,
5- therefore use of a Docker image is recommended .
4+ toolchain [ Emscripten] ( https://emscripten.org ) . Use of a Docker image is
5+ recommended to achieve repeatable builds and save work .
66
77## Docker
88
@@ -11,7 +11,7 @@ A Dockerfile for the C++ SDK is provided in [Dockerfile-sdk](../Dockerfile-sdk).
1111It can built in this repository's root directory by:
1212
1313``` bash
14- docker build -t wasmsdk:v2 -f Dockerfile-sdk .
14+ docker build -t wasmsdk:v3 -f Dockerfile-sdk .
1515```
1616
1717The docker image can be used for compiling C++ plugin code into Wasm modules.
@@ -23,12 +23,10 @@ Create a directory with your source files and a Makefile:
2323``` makefile
2424PROXY_WASM_CPP_SDK =/sdk
2525
26- all : myproject.wasm
27-
28- include ${PROXY_WASM_CPP_SDK}/Makefile.base_lite
26+ include ${PROXY_WASM_CPP_SDK}/Makefile
2927```
3028
31- Source file (myproject.cc) :
29+ Create a C++ source file (myproject.cc) :
3230
3331```c++
3432# include <string>
@@ -57,62 +55,40 @@ void ExampleContext::onDone() { logInfo("onDone " + std::to_string(id())); }
5755
5856# ## Compiling with the Docker build image
5957
60- Run docker :
61-
62- ```bash
63- docker run -v $PWD :/work -w /work wasmsdk:v2 /build_wasm.sh
64- ```
65-
66- # ## Caching the standard libraries
67-
68- The first time that emscripten runs it will generate the standard libraries. To
69- cache these in the docker image, after the first successful compilation (e.g
70- myproject.cc above), commit the image with the standard libraries :
58+ Run docker to build wasm, using a target with a .wasm suffix :
7159
7260```bash
73- docker commit `docker ps -l | grep wasmsdk :v2 | awk '{print $1}'` wasmsdk:v2
61+ docker run -v $PWD :/work -w /work wasmsdk:v3 /build_wasm.sh myproject.wasm
7462```
7563
76- This will save time on subsequent compiles.
64+ You can specify wasm dependencies via these Makefile variables :
7765
78- # ## Using Abseil from the Docker image
66+ - PROTOBUF = {full, lite, none}
67+ - WASM_DEPS = list of libraries
7968
80- Abseil (optionally) is built in /root/abseil and can be used. Note that the
81- Abseil containers (e.g. `absl ::flat_hash_set`) exercise many syscalls which are
82- not supported. Consequentially individual files should be pulled in which are
83- relatively self contained (e.g. `strings`). Example customized Makefile :
69+ For example :
8470
8571```makefile
8672PROXY_WASM_CPP_SDK =/sdk
87- CPP_API: =${PROXY_WASM_CPP_SDK}
88- CPP_CONTEXT_LIB = ${CPP_API}/proxy_wasm_intrinsics.cc
89- ABSL = /root/abseil-cpp
90- ABSL_CPP = ${ABSL}/absl/strings/str_cat.cc ${ABSL}/absl/strings/str_split.cc ${ABSL}/absl/strings/numbers.cc ${ABSL}/absl/strings/ascii.cc
9173
92- all : plugin.wasm
74+ PROTOBUF =lite
75+ WASM_DEPS =re2 absl_strings
9376
94- % .wasm% .wat% .cc ${CPP_API}/proxy_wasm_intrinsics.h ${CPP_API}/proxy_wasm_enums.h ${CPP_API}/proxy_wasm_externs.h ${CPP_API}/proxy_wasm_api.h ${CPP_API}/proxy_wasm_intrinsics.js ${CPP_CONTEXT_LIB}
95- ls /root
96- em++ --no-entry -s EXPORTED_FUNCTIONS=['_malloc'] --std=c++17 -O3 -flto -I${CPP_API} -I${CPP_API}/google/protobuf -I/usr/local/include -I${ABSL} --js-library ${CPP_API}/proxy_wasm_intrinsics.js ${ABSL_CPP} $*.cc ${CPP_API}/proxy_wasm_intrinsics.pb.cc ${CPP_CONTEXT_LIB} ${CPP_API}/libprotobuf.a -o $*.wasm
77+ include ${PROXY_WASM_CPP_SDK}/Makefile
9778```
9879
99- Precompiled Abseil libraries are also available, so the above can also be done
100- as:
101-
102- ``` makefile
103- PROXY_WASM_CPP_SDK =/sdk
104- CPP_API: =${PROXY_WASM_CPP_SDK}
105- CPP_CONTEXT_LIB = ${CPP_API}/proxy_wasm_intrinsics.cc
106- ABSL = /root/abseil-cpp
107- ABSL_LIBS = ${ABSL}/absl/strings/libabsl_strings.a ${ABSL}/absl/strings/libabsl_strings_internal.a ${ABSL}/absl/strings/libabsl_str_format_internal.a
80+ # ## Caching the standard libraries
10881
109- all : plugin.wasm
82+ The first time that emscripten runs it will generate the standard libraries. To
83+ cache these in the docker image, after the first successful compilation (e.g
84+ myproject.cc above), commit the image with the standard libraries :
11085
111- % .wasm% .wat% .cc ${CPP_API}/proxy_wasm_intrinsics.h ${CPP_API}/proxy_wasm_enums.h ${CPP_API}/proxy_wasm_externs.h ${CPP_API}/proxy_wasm_api.h ${CPP_API}/proxy_wasm_intrinsics.js ${CPP_CONTEXT_LIB}
112- ls /root
113- em++ --no-entry -s EXPORTED_FUNCTIONS=['_malloc'] --std=c++17 -O3 -flto -I${CPP_API} -I${CPP_API}/google/protobuf -I/usr/local/include -I${ABSL} --js-library ${CPP_API}/proxy_wasm_intrinsics.js $*.cc ${CPP_API}/proxy_wasm_intrinsics.pb.cc ${CPP_CONTEXT_LIB} ${CPP_API}/libprotobuf.a ${ABSL_LIBS} -o $*.wasm
86+ ```bash
87+ docker commit `docker ps -l | grep wasmsdk :v3 | awk '{print $1}'` wasmsdk:v3
11488```
11589
90+ This will save time on subsequent compiles.
91+
11692# ## Ownership of the resulting .wasm files
11793
11894The compiled files may be owned by root. To chown them, add the follow lines to
@@ -124,48 +100,32 @@ PROXY_WASM_CPP_SDK=/sdk
124100all : myproject.wasm
125101 chown ${uid}.${gid} $^
126102
127- include ${PROXY_WASM_CPP_SDK}/Makefile.base_lite
103+ include ${PROXY_WASM_CPP_SDK}/Makefile
128104```
129105
130106Invocation file (e.g. build.sh) :
131107
132108```bash
133109# !/bin/bash
134- docker run -e uid="$(id -u ) " -e gid="$(id -g ) " -v $PWD :/work -w /work wasmsdk:v2 /build_wasm.sh
110+ docker run -e uid="$(id -u ) " -e gid="$(id -g ) " -v $PWD :/work -w /work wasmsdk:v3 /build_wasm.sh
135111```
136112
137113# # Dependencies for building Wasm modules:
138114
139115If you do not wish to use the Docker image, the dependencies can be installed by
140- script (sdk\_container.sh), or by hand.
141-
142- # ## protobuf v3.9.1
143-
144- You must install the version of protobuf on your build system that matches the
145- libprotobuf.a files (without any patches) so that the generated code matches the
146- .a library. Currently this is based on tag v3.9.1 of
147- https ://github.com/protocolbuffers/protobuf.
148-
149- ```bash
150- git clone https ://github.com/protocolbuffers/protobuf
151- cd protobuf
152- git checkout v3.9.1
153- git submodule update --init --recursive
154- ./autogen.sh
155- ./configure
156- make
157- make check
158- sudo make install
159- ```
116+ script (sdk\_container.sh), or by hand. First you need Emscripten to build
117+ everything else. Then you can build other wasm-compatible libraries, such as
118+ protobuf, abseil, and RE2.
160119
161120# ## Emscripten
162121
122+ Version 3.1.67 is known to work :
123+
163124```bash
164125git clone https ://github.com/emscripten-core/emsdk.git
165126cd emsdk
166127git checkout 3.1.67
167-
168- ./emsdk install 3.1.67
128+ ./emsdk install --shallow 3.1.67
169129./emsdk activate 3.1.67
170130
171131source ./emsdk_env.sh
@@ -178,26 +138,3 @@ It is possible later versions will work, e.g.
178138./emsdk install latest
179139./emsdk activate latest
180140```
181-
182- However 3.1.67 is known to work.
183-
184- ### Rebuilding the libprotobuf.a files
185-
186- To build the protobuf static libraries for use in your proxy-wasm wasm module,
187- if you need them, you may use Emscripten in the same way sdk\_ container.sh does
188- it:
189-
190- ``` bash
191- git clone https://github.com/protocolbuffers/protobuf protobuf-wasm
192- cd protobuf-wasm
193- git checkout v3.9.1
194- git submodule update --init --recursive
195- ./autogen.sh
196- emconfigure ./configure --disable-shared CXXFLAGS=" -O3 -flto"
197- emmake make
198- cd ..
199- cp protobuf-wasm/src/.libs/libprotobuf-lite.a ${CPP_API} /libprotobuf-lite.a
200- cp protobuf-wasm/src/.libs/libprotobuf.a ${CPP_API} /libprotobuf.a
201- ```
202-
203- Note: ensure /usr/local/bin is in your path.
0 commit comments