Mercurial

comparison third_party/emsdk/docker/README.md @ 179:8d17f6e6e290

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
[ThirdParty] Added emsdk bazel rules that can be supported by bazel 9.0.0
author MrJuneJune <me@mrjunejune.com>
date Thu, 22 Jan 2026 21:23:17 -0800
parents
children
comparison
equal deleted inserted replaced
178:94705b5986b3 179:8d17f6e6e290
1 # Dockerfile for EMSDK
2
3 This Dockerfile builds a self-contained version of Emscripten SDK that enables Emscripten to be used without any
4 other installation on the host system.
5
6 It is published at https://hub.docker.com/r/emscripten/emsdk.
7
8 ### Usage
9
10 Simple usage of this container to compile a hello-world
11 ```bash
12 # create helloworld.cpp
13 cat << EOF > helloworld.cpp
14 #include <iostream>
15 int main() {
16 std::cout << "Hello World!" << std::endl;
17 return 0;
18 }
19 EOF
20 ```
21
22 ```bash
23 # compile with docker image
24 docker run \
25 --rm \
26 -v "$(pwd):$(pwd)" \
27 -u $(id -u):$(id -g) \
28 emscripten/emsdk \
29 emcc helloworld.cpp -o helloworld.js
30
31 # execute on host machine
32 node helloworld.js
33 ```
34
35 Teardown of compilation command:
36
37 |part|description|
38 |---|---|
39 |`docker run`| A standard command to run a command in a container|
40 |`--rm`|remove a container after execution (optimization)|
41 |`-v "$(pwd):$(pwd)"`|Mounting current folder from the host system into mirrored path on the container<br>TIP: This helps to investigate possible problem as we preserve exactly the same paths like in host. In such case modern editors (like Sublime, Atom, VS Code) let us to CTRL+Click on a problematic file |
42 |`-u $(id -u):$(id -g)`| Run the container as a non-root user with the same UID and GID as local user. Hence all files produced by this are accessible to non-root users|
43 |`emscripten/emsdk`|Get the latest tag of this container|
44 |`emcc helloworld.cpp -o helloworld.js`|Execute `emcc` command with following arguments inside container, effectively compile our source code|
45
46
47
48 ### Building Dockerfile
49
50 This image has following optional arguments
51
52 | arg | default value | description |
53 | --- | --- | --- |
54 | `EMSCRIPTEN_VERSION` | `tot`<br/>(special case, tip-of-tree) | One of released version of Emscripten. For example `2.0.0`<br/> Minimal supported version is **1.39.0** |
55
56 **Building**
57
58 This step will build Dockerfile as given tag on local machine
59 ```bash
60 # using docker
61 docker build \
62 --network host \
63 --build-arg=EMSCRIPTEN_VERSION=1.39.17 \
64 -t emscripten/emsdk:1.39.17 \
65 -f docker/Dockerfile \
66 .
67 ```
68 ```bash
69 # using predefined make target
70 make version=1.39.17 build test
71 ```
72
73 **Tagging**
74
75 In case of using `docker build` command directly, given `--tag` should match version of released Emscripten (you can see list of non-legacy versions by executing `emsdk list`).
76
77 **Pushing**
78
79 This step will take local image and push to default docker registry. You need to make sure that you logged in docker cli (`docker login`) and you have rights to push to that registry.
80
81 ```bash
82 # using docker
83 docker push emscripten/emsdk:1.39.17
84 ```
85 ```bash
86 # using predefined make target
87 make version=1.39.17 push
88 ```
89
90 In case of pushing the most recent version, this version should be also tagged as `latest` and pushed.
91 ```bash
92 # using docker cli
93 docker tag emscripten/emsdk:1.39.17 emscripten/emsdk:latest
94 docker push emscripten/emsdk:latest
95
96 ```bash
97 # using make
98 make version=1.39.17 alias=latest push
99 ```
100
101 ### Extending
102
103 If your project uses packages that this image doesn't provide you might want to:
104 * Contribute to this repo: Maybe your dependency is either non-intrusive or could be useful for other people
105 * Create custom image that bases on this image
106
107 1. create own Dockerfile that holds:
108 ```dockerfile
109 # Point at any base image that you find suitable to extend.
110 FROM emscripten/emsdk:1.39.17
111
112 # Install required tools that are useful for your project i.e. ninja-build
113 RUN apt update && apt install -y ninja-build
114 ```
115
116 2. build it
117 ```bash
118 docker build -t extended_emscripten .
119 ```
120
121 3. test
122 ```bash
123 docker run --rm extended_emscripten ninja --version
124 # 1.10.0
125 ```