259 строки
12 KiB
Markdown
259 строки
12 KiB
Markdown
Emscripten SDK
|
|
==============
|
|
|
|
[](https://circleci.com/gh/emscripten-core/emsdk/tree/master)
|
|
|
|
The Emscripten toolchain is distributed as a standalone Emscripten SDK. The SDK
|
|
provides all the required tools, such as Clang, Python and Node.js along with an
|
|
update mechanism that enables migrating to newer Emscripten versions as they are
|
|
released.
|
|
|
|
You can also set up Emscripten from source, without the pre-built SDK, see
|
|
"Installing from Source" below.
|
|
|
|
## Downloads / How do I get the latest Emscripten build?
|
|
|
|
To get started with Emscripten development, see the [Emscripten website
|
|
documentation](https://emscripten.org/docs/getting_started/downloads.html).
|
|
|
|
That explains how to use the emsdk to get the latest binary builds (without
|
|
compiling from source). Basically, that amounts to
|
|
|
|
```
|
|
./emsdk install latest
|
|
./emsdk activate latest
|
|
```
|
|
|
|
## SDK Concepts
|
|
|
|
The Emscripten SDK is effectively a small package manager for tools that are
|
|
used in conjunction with Emscripten. The following glossary highlights the
|
|
important concepts to help understanding the internals of the SDK:
|
|
|
|
* **Tool**: The basic unit of software bundled in the SDK. A Tool has a name and
|
|
a version. For example, 'clang-3.2-32bit' is a Tool that contains the 32-bit
|
|
version of the Clang v3.2 compiler.
|
|
* **SDK**: A set of tools. For example, 'sdk-1.5.6-32bit' is an SDK consisting
|
|
of the tools `clang-3.2-32bit`, `node-0.10.17-32bit`, `python-2.7.5.1-32bit`
|
|
and `emscripten-1.5.6`.
|
|
* **Active Tool/SDK**: Emscripten stores compiler configuration in a
|
|
user-specific file **~/.emscripten**. This file points to paths for
|
|
Emscripten, Python, Clang and so on. If the file ~/.emscripten is configured
|
|
to point to a Tool in a specific directory, then that tool is denoted as being
|
|
**active**. The Emscripten Command Prompt always gives access to the currently
|
|
active Tools. This mechanism allows switching between different installed SDK
|
|
versions easily.
|
|
* **emsdk**: This is the name of the manager script that Emscripten SDK is
|
|
accessed through. Most operations are of the form `emsdk command`. To access
|
|
the emsdk script, launch the Emscripten Command Prompt.
|
|
|
|
## System Requirements
|
|
|
|
Using the emsdk pre-compiled packages requires only the minimal set of
|
|
dependenencies lists below. When building from source a wider set of tools
|
|
include git, cmake, and a host compiler are required. See:
|
|
https://emscripten.org/docs/building_from_source/toolchain_what_is_needed.html.
|
|
|
|
### Mac OS X
|
|
|
|
- For Intel-based Macs, macOS 10.13 or newer. For ARM64 M1 based Macs, macOS
|
|
11.0 or newer.
|
|
- `java`: For running closure compiler (optional). After installing emscripten
|
|
via emsdk, typing 'emcc --help' should pop up a OS X dialog "Java is not
|
|
installed. To open java, you need a Java SE 6 runtime. Would you like to
|
|
install one now?" that will automatically download a Java runtime to the
|
|
system.
|
|
|
|
### Linux
|
|
|
|
- `python`: Version 2.7.0 or above.
|
|
- `java`: For running closure compiler (optional)
|
|
|
|
The emsdk pre-compiled binaries are built aginst Ubuntu/Xenial 16.04 LTS and
|
|
therefore depend on system libraries compatiable with versions of `glibc` and
|
|
`libstdc++` present in that release. If your linux distribution is very old
|
|
you may not be able to use the pre-compiled binaries packages.
|
|
|
|
### Windows
|
|
|
|
- `java`: For running closure compiler (optional)
|
|
|
|
## Uninstalling the Emscripten SDK
|
|
|
|
To remove the Emscripten SDK, simply delete the emsdk directory.
|
|
|
|
## SDK Maintenance
|
|
|
|
The following tasks are common with the Emscripten SDK:
|
|
|
|
### How do I work the emsdk utility?
|
|
|
|
Run `emsdk help` or just `emsdk` to get information about all available commands.
|
|
|
|
### How do I check the installation status and version of the SDK and tools?
|
|
|
|
To get a list of all currently installed tools and SDK versions, and all
|
|
available tools, run `emsdk list`.
|
|
* A line will be printed for each tool/SDK that is available for installation.
|
|
* The text `INSTALLED` will be shown for each tool that has already been
|
|
installed.
|
|
* If a tool/SDK is currently active, a star * will be shown next to it.
|
|
* If a tool/SDK is currently active, but the terminal your are calling emsdk
|
|
from does not have `PATH` and environment set up to utilize that tool, a star
|
|
in parentheses (\*) will be shown next to it. Run `emsdk_env.bat` (Windows) or
|
|
`source ./emsdk_env.sh` (Linux and OS X) to set up the environment for the
|
|
calling terminal.
|
|
|
|
### How do I install a tool/SDK version?
|
|
|
|
Run the command `emsdk install <tool/sdk name>` to download and install a new
|
|
tool or an SDK version.
|
|
|
|
### How do I remove a tool or an SDK?
|
|
|
|
Run the command `emsdk uninstall <tool/sdk name>` to delete the given tool or
|
|
SDK from the local hard drive completely.
|
|
|
|
### How do I check for updates to the Emscripten SDK?
|
|
|
|
`emsdk update` will fetch package information for all the new tools and
|
|
SDK versions. After that, run `emsdk install <tool/sdk name>` to install a new
|
|
version.
|
|
|
|
### How do I install an old Emscripten compiler version?
|
|
|
|
Emsdk contains a history of old compiler versions that you can use to maintain
|
|
your migration path. Type `emsdk list --old` to get a list of archived tool and
|
|
SDK versions, and `emsdk install <name_of_tool>` to install it.
|
|
|
|
### I want to build from source!
|
|
|
|
Some Emsdk Tool and SDK targets refer to packages that are precompiled, and
|
|
no compilation is needed when installing them. Other Emsdk Tools and SDK
|
|
targets come "from source", meaning that they will fetch the source repositories
|
|
using git, and compile the package on demand.
|
|
|
|
When you run `emsdk list`, it will group the Tools and SDKs under these two
|
|
categories.
|
|
|
|
To obtain and build latest upstream wasm SDK from source, run
|
|
|
|
```
|
|
emsdk install sdk-upstream-main-64bit
|
|
emsdk activate sdk-upstream-main-64bit
|
|
```
|
|
|
|
You can use this target for example to bootstrap developing patches to LLVM,
|
|
Binaryen or Emscripten. (After initial installation, use `git remote add`
|
|
in the cloned tree to add your own fork to push changes as patches)
|
|
|
|
If you only intend to contribute to Emscripten repository, and not to LLVM
|
|
or Binaryen, you can also use precompiled versions of them, and only git
|
|
clone the Emscripten repository. For more details, see
|
|
|
|
https://emscripten.org/docs/contributing/developers_guide.html?highlight=developer#setting-up
|
|
|
|
### When working on git branches compiled from source, how do I update to a newer compiler version?
|
|
|
|
Unlike tags and precompiled versions, a few of the SDK packages are based on
|
|
"moving" git branches and compiled from source (e.g. sdk-upstream-main,
|
|
sdk-main, emscripten-main, binaryen-main). Because of that, the
|
|
compiled versions will eventually go out of date as new commits are introduced
|
|
to the development branches. To update an old compiled installation of one of
|
|
this branches, simply reissue the "emsdk install" command on that tool/SDK. This
|
|
will `git pull` the latest changes to the branch and issue an incremental
|
|
recompilation of the target in question. This way you can keep calling `emsdk
|
|
install` to keep an Emscripten installation up to date with a given git branch.
|
|
|
|
Note though that if the previously compiled branch is very old, sometimes CMake
|
|
gets confused and is unable to properly rebuild a project. This has happened in
|
|
the past e.g. when LLVM migrated to requiring a newer CMake version. In cases of
|
|
any odd compilation errors, it is advised to try deleting the intermediate build
|
|
directory to clear the build (e.g. "emsdk/clang/fastcomp/build_xxx/") before
|
|
reissuing `emsdk install`.
|
|
|
|
### How do I change the currently active SDK version?
|
|
|
|
You can toggle between different tools and SDK versions by running `emsdk
|
|
activate <tool/sdk name>`. Activating a tool will set up `~/.emscripten` to
|
|
point to that particular tool. On Windows, you can pass the option `--permanent` to
|
|
the `activate` command to register the environment permanently for the current user. Use `--system` to do this for all users.
|
|
|
|
### How do I build multiple projects with different SDK versions in parallel?
|
|
|
|
By default, Emscripten locates all configuration files in the home directory of
|
|
the user. This may be a problem if you need to simultaneously build with
|
|
multiple Emscripten compiler versions, since the user home directory can only be
|
|
configured to point to one compiler at a time. This can be overcome by
|
|
specifying the '--embedded' option as a parameter to 'emsdk activate', which
|
|
will signal emsdk to generate the compiler configuration files inside the emsdk
|
|
root directory instead of the user home directory. Use this option also when it
|
|
is desirable to run emsdk in a fully portable mode that does not touch any files
|
|
outside the emsdk directory.
|
|
|
|
### How do I track the latest Emscripten development with the SDK?
|
|
|
|
A common and supported use case of the Emscripten SDK is to enable the workflow
|
|
where you directly interact with the github repositories. This allows you to
|
|
obtain new features and latest fixes immediately as they are pushed to the
|
|
github repository, without having to wait for release to be tagged. You do not
|
|
need a github account or a fork of Emscripten to do this. To switch to using the
|
|
latest upstream git development branch `main`, run the following:
|
|
|
|
emsdk install git-1.9.4 # Install git. Skip if the system already has it.
|
|
emsdk install sdk-upstream-main-64bit # Clone+pull the latest emscripten-core/emscripten/main.
|
|
emsdk activate sdk-upstream-main-64bit # Set the main SDK as the currently active one.
|
|
|
|
### How do I use my own Emscripten github fork with the SDK?
|
|
|
|
It is also possible to use your own fork of the Emscripten repository via the
|
|
SDK. This is achieved with standard git machinery, so there if you are already
|
|
acquainted with working on multiple remotes in a git clone, these steps should
|
|
be familiar to you. This is useful in the case when you want to make your own
|
|
modifications to the Emscripten toolchain, but still keep using the SDK
|
|
environment and tools. To set up your own fork as the currently active
|
|
Emscripten toolchain, first install the `sdk-main` SDK like shown in the
|
|
previous section, and then run the following commands in the emsdk directory:
|
|
|
|
cd emscripten/main
|
|
# Add a git remote link to your own repository.
|
|
git remote add myremote https://github.com/mygituseraccount/emscripten.git
|
|
# Obtain the changes in your link.
|
|
git fetch myremote
|
|
# Switch the emscripten-main tool to use your fork.
|
|
git checkout -b mymain --track myremote/main
|
|
|
|
In this way you can utilize the Emscripten SDK tools while using your own git
|
|
fork. You can switch back and forth between remotes via the `git checkout`
|
|
command as usual.
|
|
|
|
### How do I use Emscripten SDK with a custom version of python, java, node.js or some other tool?
|
|
|
|
The provided Emscripten SDK targets are metapackages that refer to a specific
|
|
set of tools that have been tested to work together. For example,
|
|
`sdk-1.35.0-64bit` is an alias to the individual packages `clang-e1.35.0-64bit`,
|
|
`node-4.1.1-64bit`, `python-2.7.5.3-64bit` and `emscripten-1.35.0`. This means
|
|
that if you install this version of the SDK, both python and node.js will be
|
|
installed inside emsdk as well. If you want to use your own/system python or
|
|
node.js instead, you can opt to install emsdk by specifying the individual set
|
|
of packages that you want to use. For example, `emsdk install
|
|
clang-e1.35.0-64bit emscripten-1.35.0` will only install the Emscripten
|
|
LLVM/Clang compiler and the Emscripten frontend without supplying python and
|
|
node.js.
|
|
|
|
### My installation fails with "fatal error: ld terminated with signal 9 [Killed]"?
|
|
|
|
This may happen if the system runs out of memory. If you are attempting to build
|
|
one of the packages from source and are running in a virtual OS or may have
|
|
relatively little RAM and disk space available, then the build might fail. Try
|
|
feeding your computer more memory. Another thing to try is to force emsdk
|
|
install to build in a singlethreaded mode, which will require less RAM
|
|
simultaneously. To do this, pass the `-j1` flag to the `emsdk install` command.
|
|
|
|
### How do I run Emscripten on 32-bit systems or non-x86-64 systems?
|
|
|
|
Emscripten SDK releases are no longer packaged or maintained for 32-bit systems.
|
|
If you want to run Emscripten on a 32-bit system, you can try manually building
|
|
the compiler. Follow the steps in the above section "Building an Emscripten tag
|
|
or branch from source" to get started.
|