Mercurial

comparison third_party/emsdk/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 Emscripten SDK
2 ==============
3
4 [![CircleCI](https://circleci.com/gh/emscripten-core/emsdk/tree/main.svg?style=svg)](https://circleci.com/gh/emscripten-core/emsdk/tree/main)
5
6 The Emscripten toolchain is distributed as a standalone Emscripten SDK. The SDK
7 provides all the required tools, such as Clang, Python and Node.js along with an
8 update mechanism that enables migrating to newer Emscripten versions as they are
9 released.
10
11 You can also set up Emscripten from source, without the pre-built SDK, see
12 "Installing from Source" below.
13
14 ## Downloads / How do I get the latest Emscripten build?
15
16 To get started with Emscripten development, see the [Emscripten website
17 documentation](https://emscripten.org/docs/getting_started/downloads.html).
18
19 That explains how to use the emsdk to get the latest binary builds (without
20 compiling from source). Basically, that amounts to
21
22 ```
23 git pull
24 ./emsdk install latest
25 ./emsdk activate latest
26 ```
27
28 ## SDK Concepts
29
30 The Emscripten SDK is effectively a small package manager for tools that are
31 used in conjunction with Emscripten. The following glossary highlights the
32 important concepts to help understanding the internals of the SDK:
33
34 * **Tool**: The basic unit of software bundled in the SDK. A Tool has a name and
35 a version. For example, 'clang-3.2-32bit' is a Tool that contains the 32-bit
36 version of the Clang v3.2 compiler.
37 * **SDK**: A set of tools. For example, 'sdk-1.5.6-32bit' is an SDK consisting
38 of the tools `clang-3.2-32bit`, `node-0.10.17-32bit`, `python-2.7.5.1-32bit`
39 and `emscripten-1.5.6`.
40 * **Active Tool/SDK**: Emscripten SDK stores compiler configuration in a file
41 called `.emscripten` within the emsdk directory. This file points to paths
42 for Emscripten, Python, Clang and so on. If the configuration file points to a
43 Tool in a specific directory, then that tool is denoted as being
44 **active**. This mechanism allows switching between different installed
45 tools and SDKs.
46 * **emsdk**: This is the name of the manager script that Emscripten SDK is
47 accessed through. Most operations are of the form `emsdk <command>`.
48
49 ## System Requirements
50
51 Using the emsdk pre-compiled packages requires only the minimal set of
52 dependencies lists below. When building from source a wider set of tools
53 include git, cmake, and a host compiler are required. See:
54 https://emscripten.org/docs/building_from_source/toolchain_what_is_needed.html.
55
56 ### Mac OS X
57
58 - macOS 11.0 or newer.
59 - `java`: For running closure compiler (optional). After installing emscripten
60 via emsdk, typing 'emcc --help' should pop up a OS X dialog "Java is not
61 installed. To open java, you need a Java SE 6 runtime. Would you like to
62 install one now?" that will automatically download a Java runtime to the
63 system.
64
65 ### Linux
66
67 - `python`: Version 3.8 or above.
68 - `java`: For running closure compiler (optional)
69
70 The emsdk pre-compiled binaries are built against debian/stretch (for x86_64)
71 and debian/bullseye (for arm64) sysroots and therefore depend on system
72 libraries compatible with the version of `glibc` (and other libraries) present
73 in those releases. If your linux distribution is very old you may not be able to
74 use the pre-compiled binaries packages. Note that `libc++` is statically linked
75 so there should be no issues with older versions of `libstdc++` or `libc++`.
76
77 ### Windows
78
79 - `java`: For running closure compiler (optional)
80
81 ## Uninstalling the Emscripten SDK
82
83 To remove the Emscripten SDK, simply delete the emsdk directory.
84
85 ## SDK Maintenance
86
87 The following tasks are common with the Emscripten SDK:
88
89 ### How do I work the emsdk utility?
90
91 Run `emsdk help` or just `emsdk` to get information about all available commands.
92
93 ### How do I check the installation status and version of the SDK and tools?
94
95 To get a list of all currently installed tools and SDK versions, and all
96 available tools, run `emsdk list`.
97 * A line will be printed for each tool/SDK that is available for installation.
98 * The text `INSTALLED` will be shown for each tool that has already been
99 installed.
100 * If a tool/SDK is currently active, a star * will be shown next to it.
101 * If a tool/SDK is currently active, but the terminal your are calling emsdk
102 from does not have `PATH` and environment set up to utilize that tool, a star
103 in parentheses (\*) will be shown next to it. Run `emsdk_env.bat` (Windows) or
104 `source ./emsdk_env.sh` (Linux and OS X) to set up the environment for the
105 calling terminal.
106
107 ### How do I install a tool/SDK version?
108
109 Run the command `emsdk install <tool/sdk name>` to download and install a new
110 tool or an SDK version.
111
112 ### How do I remove a tool or an SDK?
113
114 Run the command `emsdk uninstall <tool/sdk name>` to delete the given tool or
115 SDK from the local hard drive completely.
116
117 ### How do I check for updates to the Emscripten SDK?
118
119 `emsdk update` will fetch package information for all the new tools and
120 SDK versions. After that, run `emsdk install <tool/sdk name>` to install a new
121 version.
122
123 ### How do I install an old Emscripten compiler version?
124
125 Emsdk contains a history of old compiler versions that you can use to maintain
126 your migration path. Type `emsdk list --old` to get a list of archived tool and
127 SDK versions, and `emsdk install <name_of_tool>` to install it.
128
129 ### I want to build from source!
130
131 Some Emsdk Tool and SDK targets refer to packages that are precompiled, and
132 no compilation is needed when installing them. Other Emsdk Tools and SDK
133 targets come "from source", meaning that they will fetch the source repositories
134 using git, and compile the package on demand.
135
136 When you run `emsdk list`, it will group the Tools and SDKs under these two
137 categories.
138
139 To obtain and build latest wasm SDK from source, run
140
141 ```
142 emsdk install sdk-main-64bit
143 emsdk activate sdk-main-64bit
144 ```
145
146 You can use this target for example to bootstrap developing patches to LLVM,
147 Binaryen or Emscripten. (After initial installation, use `git remote add`
148 in the cloned tree to add your own fork to push changes as patches)
149
150 If you only intend to contribute to Emscripten repository, and not to LLVM
151 or Binaryen, you can also use precompiled versions of them, and only git
152 clone the Emscripten repository. For more details, see
153
154 https://emscripten.org/docs/contributing/developers_guide.html?highlight=developer#setting-up
155
156 ### When working on git branches compiled from source, how do I update to a newer compiler version?
157
158 Unlike tags and precompiled versions, a few of the SDK packages are based on
159 "moving" git branches and compiled from source (e.g. sdk-main,
160 sdk-main, emscripten-main, binaryen-main). Because of that, the
161 compiled versions will eventually go out of date as new commits are introduced
162 to the development branches. To update an old compiled installation of one of
163 this branches, simply reissue the "emsdk install" command on that tool/SDK. This
164 will `git pull` the latest changes to the branch and issue an incremental
165 recompilation of the target in question. This way you can keep calling `emsdk
166 install` to keep an Emscripten installation up to date with a given git branch.
167
168 Note though that if the previously compiled branch is very old, sometimes CMake
169 gets confused and is unable to properly rebuild a project. This has happened in
170 the past e.g. when LLVM migrated to requiring a newer CMake version. In cases of
171 any odd compilation errors, it is advised to try deleting the intermediate build
172 directory to clear the build (e.g. "emsdk/clang/fastcomp/build_xxx/") before
173 reissuing `emsdk install`.
174
175 ### How do I change the currently active SDK version?
176
177 You can toggle between different tools and SDK versions by running `emsdk
178 activate <tool/sdk name>`. Activating a tool will set up `~/.emscripten` to
179 point to that particular tool. On Windows, you can pass the option `--permanent` to
180 the `activate` command to register the environment permanently for the current user. Use `--system` to do this for all users.
181
182 ### How do I track the latest Emscripten development with the SDK?
183
184 A common and supported use case of the Emscripten SDK is to enable the workflow
185 where you directly interact with the github repositories. This allows you to
186 obtain new features and latest fixes immediately as they are pushed to the
187 github repository, without having to wait for release to be tagged. You do not
188 need a github account or a fork of Emscripten to do this. To switch to using the
189 latest git development branch `main`, run the following:
190
191 emsdk install git-1.9.4 # Install git. Skip if the system already has it.
192 emsdk install sdk-main-64bit # Clone+pull the latest emscripten-core/emscripten/main.
193 emsdk activate sdk-main-64bit # Set the main SDK as the currently active one.
194
195 ### How do I use my own Emscripten github fork with the SDK?
196
197 It is also possible to use your own fork of the Emscripten repository via the
198 SDK. This is achieved with standard git machinery, so if you are already
199 acquainted with working on multiple remotes in a git clone, these steps should
200 be familiar to you. This is useful in the case when you want to make your own
201 modifications to the Emscripten toolchain, but still keep using the SDK
202 environment and tools. To set up your own fork as the currently active
203 Emscripten toolchain, first install the `sdk-main` SDK like shown in the
204 previous section, and then run the following commands in the emsdk directory:
205
206 cd emscripten/main
207 # Add a git remote link to your own repository.
208 git remote add myremote https://github.com/mygituseraccount/emscripten.git
209 # Obtain the changes in your link.
210 git fetch myremote
211 # Switch the emscripten-main tool to use your fork.
212 git checkout -b mymain --track myremote/main
213
214 In this way you can utilize the Emscripten SDK tools while using your own git
215 fork. You can switch back and forth between remotes via the `git checkout`
216 command as usual.
217
218 ### How do I use Emscripten SDK with a custom version of python, java, node.js or some other tool?
219
220 The provided Emscripten SDK targets are metapackages that refer to a specific
221 set of tools that have been tested to work together. For example,
222 `sdk-1.35.0-64bit` is an alias to the individual packages `clang-e1.35.0-64bit`,
223 `node-4.1.1-64bit`, `python-2.7.5.3-64bit` and `emscripten-1.35.0`. This means
224 that if you install this version of the SDK, both python and node.js will be
225 installed inside emsdk as well. If you want to use your own/system python or
226 node.js instead, you can opt to install emsdk by specifying the individual set
227 of packages that you want to use. For example, `emsdk install
228 clang-e1.35.0-64bit emscripten-1.35.0` will only install the Emscripten
229 LLVM/Clang compiler and the Emscripten frontend without supplying python and
230 node.js.
231
232 ### My installation fails with "fatal error: ld terminated with signal 9 [Killed]"?
233
234 This may happen if the system runs out of memory. If you are attempting to build
235 one of the packages from source and are running in a virtual OS or may have
236 relatively little RAM and disk space available, then the build might fail. Try
237 feeding your computer more memory. Another thing to try is to force emsdk
238 install to build in a singlethreaded mode, which will require less RAM
239 simultaneously. To do this, pass the `-j1` flag to the `emsdk install` command.
240
241 ### How do I run Emscripten on 32-bit systems or non-x86-64 systems?
242
243 Emscripten SDK releases are no longer packaged or maintained for 32-bit systems.
244 If you want to run Emscripten on a 32-bit system, you can try manually building
245 the compiler. Follow the steps in the above section "Building an Emscripten tag
246 or branch from source" to get started.