Mercurial

annotate third_party/emsdk/bazel/README.md @ 208:5d3e116dd745

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
[MrJuneJune] made it more mobile friendly.
author MrJuneJune <me@mrjunejune.com>
date Sun, 15 Feb 2026 12:33:54 -0800
parents 8d17f6e6e290
children
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
179
8d17f6e6e290 [ThirdParty] Added emsdk bazel rules that can be supported by bazel 9.0.0
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
1 # Bazel Emscripten toolchain
8d17f6e6e290 [ThirdParty] Added emsdk bazel rules that can be supported by bazel 9.0.0
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
2
8d17f6e6e290 [ThirdParty] Added emsdk bazel rules that can be supported by bazel 9.0.0
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
3 ## Setup Instructions
8d17f6e6e290 [ThirdParty] Added emsdk bazel rules that can be supported by bazel 9.0.0
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
4
8d17f6e6e290 [ThirdParty] Added emsdk bazel rules that can be supported by bazel 9.0.0
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
5 Support for depending on emsdk with a WORKSPACE file was removed and last available in [emsdk version 4.0.6](https://github.com/emscripten-core/emsdk/tree/24fc909c0da13ef641d5ae75e89b5a97f25e37aa). Now we only support inclusion as a bzlmod module.
8d17f6e6e290 [ThirdParty] Added emsdk bazel rules that can be supported by bazel 9.0.0
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
6
8d17f6e6e290 [ThirdParty] Added emsdk bazel rules that can be supported by bazel 9.0.0
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
7 In your `MODULE.bazel` file, put:
8d17f6e6e290 [ThirdParty] Added emsdk bazel rules that can be supported by bazel 9.0.0
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
8 ```starlark
8d17f6e6e290 [ThirdParty] Added emsdk bazel rules that can be supported by bazel 9.0.0
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
9 emsdk_version = "4.0.6"
8d17f6e6e290 [ThirdParty] Added emsdk bazel rules that can be supported by bazel 9.0.0
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
10 bazel_dep(name = "emsdk", version = emsdk_version)
8d17f6e6e290 [ThirdParty] Added emsdk bazel rules that can be supported by bazel 9.0.0
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
11 git_override(
8d17f6e6e290 [ThirdParty] Added emsdk bazel rules that can be supported by bazel 9.0.0
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
12 module_name = "emsdk",
8d17f6e6e290 [ThirdParty] Added emsdk bazel rules that can be supported by bazel 9.0.0
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
13 remote = "https://github.com/emscripten-core/emsdk.git",
8d17f6e6e290 [ThirdParty] Added emsdk bazel rules that can be supported by bazel 9.0.0
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
14 strip_prefix = "bazel",
8d17f6e6e290 [ThirdParty] Added emsdk bazel rules that can be supported by bazel 9.0.0
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
15 tag = emsdk_version,
8d17f6e6e290 [ThirdParty] Added emsdk bazel rules that can be supported by bazel 9.0.0
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
16 )
8d17f6e6e290 [ThirdParty] Added emsdk bazel rules that can be supported by bazel 9.0.0
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
17 ```
8d17f6e6e290 [ThirdParty] Added emsdk bazel rules that can be supported by bazel 9.0.0
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
18
8d17f6e6e290 [ThirdParty] Added emsdk bazel rules that can be supported by bazel 9.0.0
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
19 You can use a different version of this SDK by changing it in your `MODULE.bazel` file. The Emscripten version is by default the same as the SDK version, but you can use a different one as well by adding to your `MODULE.bazel`:
8d17f6e6e290 [ThirdParty] Added emsdk bazel rules that can be supported by bazel 9.0.0
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
20
8d17f6e6e290 [ThirdParty] Added emsdk bazel rules that can be supported by bazel 9.0.0
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
21 ```
8d17f6e6e290 [ThirdParty] Added emsdk bazel rules that can be supported by bazel 9.0.0
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
22 emscripten_deps = use_extension(
8d17f6e6e290 [ThirdParty] Added emsdk bazel rules that can be supported by bazel 9.0.0
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
23 "@emsdk//:emscripten_deps.bzl",
8d17f6e6e290 [ThirdParty] Added emsdk bazel rules that can be supported by bazel 9.0.0
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
24 "emscripten_deps",
8d17f6e6e290 [ThirdParty] Added emsdk bazel rules that can be supported by bazel 9.0.0
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
25 )
8d17f6e6e290 [ThirdParty] Added emsdk bazel rules that can be supported by bazel 9.0.0
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
26 emscripten_deps.config(version = "4.0.1")
8d17f6e6e290 [ThirdParty] Added emsdk bazel rules that can be supported by bazel 9.0.0
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
27 ```
8d17f6e6e290 [ThirdParty] Added emsdk bazel rules that can be supported by bazel 9.0.0
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
28
8d17f6e6e290 [ThirdParty] Added emsdk bazel rules that can be supported by bazel 9.0.0
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
29 ## Building
8d17f6e6e290 [ThirdParty] Added emsdk bazel rules that can be supported by bazel 9.0.0
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
30
8d17f6e6e290 [ThirdParty] Added emsdk bazel rules that can be supported by bazel 9.0.0
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
31 Put the following line into your `.bazelrc`:
8d17f6e6e290 [ThirdParty] Added emsdk bazel rules that can be supported by bazel 9.0.0
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
32
8d17f6e6e290 [ThirdParty] Added emsdk bazel rules that can be supported by bazel 9.0.0
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
33 ```
8d17f6e6e290 [ThirdParty] Added emsdk bazel rules that can be supported by bazel 9.0.0
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
34 build --incompatible_enable_cc_toolchain_resolution
8d17f6e6e290 [ThirdParty] Added emsdk bazel rules that can be supported by bazel 9.0.0
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
35 ```
8d17f6e6e290 [ThirdParty] Added emsdk bazel rules that can be supported by bazel 9.0.0
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
36
8d17f6e6e290 [ThirdParty] Added emsdk bazel rules that can be supported by bazel 9.0.0
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
37 Then write a new rule wrapping your `cc_binary`.
8d17f6e6e290 [ThirdParty] Added emsdk bazel rules that can be supported by bazel 9.0.0
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
38
8d17f6e6e290 [ThirdParty] Added emsdk bazel rules that can be supported by bazel 9.0.0
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
39 ```starlark
8d17f6e6e290 [ThirdParty] Added emsdk bazel rules that can be supported by bazel 9.0.0
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
40 load("@rules_cc//cc:defs.bzl", "cc_binary")
8d17f6e6e290 [ThirdParty] Added emsdk bazel rules that can be supported by bazel 9.0.0
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
41 load("@emsdk//emscripten_toolchain:wasm_rules.bzl", "wasm_cc_binary")
8d17f6e6e290 [ThirdParty] Added emsdk bazel rules that can be supported by bazel 9.0.0
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
42
8d17f6e6e290 [ThirdParty] Added emsdk bazel rules that can be supported by bazel 9.0.0
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
43 cc_binary(
8d17f6e6e290 [ThirdParty] Added emsdk bazel rules that can be supported by bazel 9.0.0
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
44 name = "hello-world",
8d17f6e6e290 [ThirdParty] Added emsdk bazel rules that can be supported by bazel 9.0.0
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
45 srcs = ["hello-world.cc"],
8d17f6e6e290 [ThirdParty] Added emsdk bazel rules that can be supported by bazel 9.0.0
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
46 )
8d17f6e6e290 [ThirdParty] Added emsdk bazel rules that can be supported by bazel 9.0.0
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
47
8d17f6e6e290 [ThirdParty] Added emsdk bazel rules that can be supported by bazel 9.0.0
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
48 wasm_cc_binary(
8d17f6e6e290 [ThirdParty] Added emsdk bazel rules that can be supported by bazel 9.0.0
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
49 name = "hello-world-wasm",
8d17f6e6e290 [ThirdParty] Added emsdk bazel rules that can be supported by bazel 9.0.0
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
50 cc_target = ":hello-world",
8d17f6e6e290 [ThirdParty] Added emsdk bazel rules that can be supported by bazel 9.0.0
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
51 )
8d17f6e6e290 [ThirdParty] Added emsdk bazel rules that can be supported by bazel 9.0.0
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
52 ```
8d17f6e6e290 [ThirdParty] Added emsdk bazel rules that can be supported by bazel 9.0.0
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
53
8d17f6e6e290 [ThirdParty] Added emsdk bazel rules that can be supported by bazel 9.0.0
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
54 Now you can run `bazel build :hello-world-wasm`. The result of this build will
8d17f6e6e290 [ThirdParty] Added emsdk bazel rules that can be supported by bazel 9.0.0
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
55 be the individual files produced by emscripten. Note that some of these files
8d17f6e6e290 [ThirdParty] Added emsdk bazel rules that can be supported by bazel 9.0.0
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
56 may be empty. This is because bazel has no concept of optional outputs for
8d17f6e6e290 [ThirdParty] Added emsdk bazel rules that can be supported by bazel 9.0.0
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
57 rules.
8d17f6e6e290 [ThirdParty] Added emsdk bazel rules that can be supported by bazel 9.0.0
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
58
8d17f6e6e290 [ThirdParty] Added emsdk bazel rules that can be supported by bazel 9.0.0
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
59 `wasm_cc_binary` uses transition to use emscripten toolchain on `cc_target`
8d17f6e6e290 [ThirdParty] Added emsdk bazel rules that can be supported by bazel 9.0.0
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
60 and all of its dependencies, and does not require amending `.bazelrc`. This
8d17f6e6e290 [ThirdParty] Added emsdk bazel rules that can be supported by bazel 9.0.0
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
61 is the preferred way, since it also unpacks the resulting tarball.
8d17f6e6e290 [ThirdParty] Added emsdk bazel rules that can be supported by bazel 9.0.0
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
62
8d17f6e6e290 [ThirdParty] Added emsdk bazel rules that can be supported by bazel 9.0.0
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
63 The Emscripten cache shipped by default does not include LTO, 64-bit or PIC
8d17f6e6e290 [ThirdParty] Added emsdk bazel rules that can be supported by bazel 9.0.0
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
64 builds of the system libraries and ports. If you wish to use these features you
8d17f6e6e290 [ThirdParty] Added emsdk bazel rules that can be supported by bazel 9.0.0
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
65 will need to declare the cache in your `MODULE.bazel` as follows. Note
8d17f6e6e290 [ThirdParty] Added emsdk bazel rules that can be supported by bazel 9.0.0
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
66 that the configuration consists of the same flags that can be passed to
8d17f6e6e290 [ThirdParty] Added emsdk bazel rules that can be supported by bazel 9.0.0
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
67 embuilder. If `targets` is not set, all system libraries and ports will be
8d17f6e6e290 [ThirdParty] Added emsdk bazel rules that can be supported by bazel 9.0.0
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
68 built, i.e., the `ALL` option to embuilder.
8d17f6e6e290 [ThirdParty] Added emsdk bazel rules that can be supported by bazel 9.0.0
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
69
8d17f6e6e290 [ThirdParty] Added emsdk bazel rules that can be supported by bazel 9.0.0
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
70 ```starlark
8d17f6e6e290 [ThirdParty] Added emsdk bazel rules that can be supported by bazel 9.0.0
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
71 emscripten_cache = use_extension(
8d17f6e6e290 [ThirdParty] Added emsdk bazel rules that can be supported by bazel 9.0.0
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
72 "@emsdk//:emscripten_cache.bzl",
8d17f6e6e290 [ThirdParty] Added emsdk bazel rules that can be supported by bazel 9.0.0
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
73 "emscripten_cache",
8d17f6e6e290 [ThirdParty] Added emsdk bazel rules that can be supported by bazel 9.0.0
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
74 )
8d17f6e6e290 [ThirdParty] Added emsdk bazel rules that can be supported by bazel 9.0.0
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
75 emscripten_cache.configuration(flags = ["--lto"])
8d17f6e6e290 [ThirdParty] Added emsdk bazel rules that can be supported by bazel 9.0.0
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
76 emscripten_cache.targets(targets = [
8d17f6e6e290 [ThirdParty] Added emsdk bazel rules that can be supported by bazel 9.0.0
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
77 "crtbegin",
8d17f6e6e290 [ThirdParty] Added emsdk bazel rules that can be supported by bazel 9.0.0
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
78 "libprintf_long_double-debug",
8d17f6e6e290 [ThirdParty] Added emsdk bazel rules that can be supported by bazel 9.0.0
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
79 "libstubs-debug",
8d17f6e6e290 [ThirdParty] Added emsdk bazel rules that can be supported by bazel 9.0.0
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
80 "libnoexit",
8d17f6e6e290 [ThirdParty] Added emsdk bazel rules that can be supported by bazel 9.0.0
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
81 "libc-debug",
8d17f6e6e290 [ThirdParty] Added emsdk bazel rules that can be supported by bazel 9.0.0
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
82 "libdlmalloc",
8d17f6e6e290 [ThirdParty] Added emsdk bazel rules that can be supported by bazel 9.0.0
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
83 "libcompiler_rt",
8d17f6e6e290 [ThirdParty] Added emsdk bazel rules that can be supported by bazel 9.0.0
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
84 "libc++-noexcept",
8d17f6e6e290 [ThirdParty] Added emsdk bazel rules that can be supported by bazel 9.0.0
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
85 "libc++abi-debug-noexcept",
8d17f6e6e290 [ThirdParty] Added emsdk bazel rules that can be supported by bazel 9.0.0
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
86 "libsockets"
8d17f6e6e290 [ThirdParty] Added emsdk bazel rules that can be supported by bazel 9.0.0
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
87 ])
8d17f6e6e290 [ThirdParty] Added emsdk bazel rules that can be supported by bazel 9.0.0
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
88 ```
8d17f6e6e290 [ThirdParty] Added emsdk bazel rules that can be supported by bazel 9.0.0
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
89
8d17f6e6e290 [ThirdParty] Added emsdk bazel rules that can be supported by bazel 9.0.0
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
90 See `test_external/` for an example using [embind](https://emscripten.org/docs/porting/connecting_cpp_and_javascript/embind.html).