Unity-Technologies
/
emscripten
зеркало из https://github.com/Unity-Technologies/emscripten.git
1
0
Форкнуть 0
Код Задачи Пакеты Проекты Релизы Вики Активность

Significant updates to the building emscripten from source topiss

This commit is contained in:
hamishwillee 2014-08-11 19:55:05 +10:00
Родитель 43a180fb87
Коммит 7494d3d67a
15 изменённых файлов: 515 добавлений и 429 удалений
Показать статистику Скачать Patch файл Скачать Diff файл Показать все файлы Свернуть все файлы

63
site/source/docs/building_from_source/LLVM-Backend.rst
Просмотреть файл

@ -21,24 +21,50 @@ Fastcomp is an **LLVM backend**. It is **not** in upstream LLVM yet, it is far t
This means that if you use another build of LLVM - like an older one you built yourself, or one from your linux distro's repos, etc. - it will **not** contain fastcomp. Emscripten will give an error about this (you can manually run those checks with ``emcc -v``), and briefly explain the issue and link to this page (where, later down, you can see how to disable fastcomp).
.. _building-fastcomp-from-source:
Getting Fastcomp
----------------
.. _building-fastcomp-from-source:
Building fastcomp from source
--------------------------------
To use fastcomp, you need both Emscripten (see the :ref:`Tutorial`) and the Emscripten LLVM code, either from the SDK or from source. Instructions from source are as follows:
- Clone the fastcomp LLVM repository: https://github.com/kripken/emscripten-fastcomp. Note that it doesn't matter where
you do this; you'll point to that directory when you edit ``~/.emscripten``, see later down): ::
- Clone the fastcomp `LLVM repository <https://github.com/kripken/emscripten-fastcomp>`_:
::
git clone https://github.com/kripken/emscripten-fastcomp
- Enter ``tools`` and clone the fastcomp Clang repository: https://github.com/kripken/emscripten-fastcomp-clang Note: **you must clone it into a dir named "clang"**, so that clang is present in ``tools/clang``! Use something like ``git clone ..repo.. clang``. (Another note: **this repo has changed**, earlier in fastcomp development we used another one, so make sure you are using this one now.)
- Build it:
- ``cd ..`` to get back to the root of the llvm checkout
- ``mkdir build`` and then ``cd build`` (it is better to build into a
separate build dir)
- Configure the build using the *configure* script or *Cmake*:
.. note:: It doesn't matter where you clone *fastcomp* because Emscripten gets the information from the :ref:`compiler configuration file (~/.emscripten) <compiler-configuration-file>`. We show how to update this file later in these instructions:
- Navigate to the **tools** directory (**emscripten-fastcomp/tools**) and clone the `kripken/emscripten-fastcomp-clang <https://github.com/kripken/emscripten-fastcomp-clang>`_ repository into a *clang* subdirectory:
::
cd tools
git clone https://github.com/kripken/emscripten-fastcomp-clang clang
.. warning:: You **must** clone it into a dir named "clang", so that clang is present in **tools/clang**!
.. note:: This repo has changed. Early in fastcomp development we used a different directory.
- Build fastcomp
- Navigate back to the root of the llvm clone (**/emscripten-fastcomp**), then create and navigate into a new directory "**build**" (we highly recommend creating a separate build directory):
::
cd ..
mkdir build
cd build
- Configure the build using *either* the *configure* script or *cmake* (configure is located in the parent directory):
- Using *configure*:
@ -52,10 +78,23 @@ To use fastcomp, you need both Emscripten (see the :ref:`Tutorial`) and the Emsc
cmake .. -DCMAKE_BUILD_TYPE=Release -DLLVM_TARGETS_TO_BUILD="X86;JSBackend" -DLLVM_INCLUDE_EXAMPLES=OFF -DLLVM_INCLUDE_TESTS=OFF -DCLANG_INCLUDE_EXAMPLES=OFF -DCLANG_INCLUDE_TESTS=OFF
replace X86 if you are on something else..
.. note:: replace X86 if you are on something else..
- ``make -j 4`` (or whatever number of cores you want to use)
- Set it up in ~/.emscripten (set the path to the llvm checkout + something like ``/build/Release/bin`` as LLVM\_ROOT, look for where the ``clang`` binary shows up under ``build/``)
- Call *make* to build the sources, specifying the number of available cores:
::
make -j 4
.. _llvm-update-compiler-configuration-file:
- Update the :ref:`~/.emscripten <compiler-configuration-file>`, specifying the location of *fastcomp* in using the ``LLVM_ROOT`` variable. The path should be set to the location of the *clang* binary under the **build** directory. This will be something like **<LVVM root>/build/Release/bin** or **<LVVM root>/build/bin**:
::
LLVM_ROOT='' **HamishW**
.. note:: If **~/.emscripten** does not yet exist, you can create it by running ``./emcc --help`` in your **emscripten** directory (assuming Emscripten has already been downloaded).
Branches
~~~~~~~~

123
site/source/docs/building_from_source/building_emscripten_from_source_on_linux.rst
Просмотреть файл

@ -1,12 +1,14 @@
.. _building-emscripten-on-linux:
============================================================
Building Emscripten on Linux (under-construction)
============================================================
================================================
Building Emscripten on Linux (ready-for-review)
================================================
This page contains basic instructions on how to build and configure Emscripten from source on a clean (Ubuntu 14.04.1 LTS 64bit) Linux box.
.. tip:: The :ref:`Portable SDK for Linux <portable-emscripten-sdk-linux-osx>` (and Mac OS X) provides the **easiest** and **most reliable** method for **building from source**. Just :ref:`download and install the SDK <sdk-download-and-install>` and follow the brief instructions :ref:`here <emsdk-master-or-incoming-sdk>`.
.. tip:: The :ref:`Portable SDK for Linux <portable-emscripten-sdk-linux-osx>` (and Mac OS X) also builds the tools from source, and may provide a simpler alternative to the process outlined here. The benefit of the SDK is that it helps automate getting the source and configuring the environment.
These instructions are provided for developers who, for whatever reason, prefer a manual approach.
This page contains basic instructions on how to manually build and configure Emscripten from source on a clean (Ubuntu 14.04.1 LTS 64bit) Linux box.
What you'll need
=================
@ -15,7 +17,7 @@ The previous topic (:ref:`Emscripten Toolchain <toolchain-what-you-need>`) lists
Installing required tools
============================================================
==========================
These instructions explain how to install **all** the :ref:`required tools <toolchain-what-you-need>`. You can :ref:`test whether some of these are already installed <toolchain-test-which-dependencies-are-installed>` on the platform and skip those steps.
@ -33,7 +35,7 @@ These instructions explain how to install **all** the :ref:`required tools <tool
sudo apt-get install python2.7
#. Install *node.js* using the *system package manager*:
#. Install `node.js <http://nodejs.org/>`_ using the *system package manager*:
::
@ -69,115 +71,24 @@ These instructions explain how to install **all** the :ref:`required tools <tool
git clone https://github.com/kripken/emscripten.git
Configuring Emscripten
=======================
**HamishW** What do to with this section depends on how specific it is to particular platforms. May be best to have very thin links here and link to the parent document
1. Navigate to the directory where you cloned the Emscripten repository.
2. Enter the command:
::
./emcc --help
You should get a ``Welcome to Emscripten!`` message. Behind the scenes, Emscripten generated a file called ``.emscripten`` in your home folder.
3. Edit **.emscripten**:
1. Edit the variable ``EMSCRIPTEN_ROOT`` to point to the Emscripten root folder, e.g.:
::
EMSCRIPTEN_ROOT = 'C:/Users/username/Documents/GitHub/emscripten'``
.. note:: Use forward slashes!
2. Edit the variable ``LLVM_ROOT`` to point directly to the path where you built *Fastcomp*, e.g.:
::
LLVM_ROOT = '**HamishW**'
3. Edit the variable TEMP\_DIR to point to a valid Windows path on your local system, e.g. ``TEMP_DIR = 'C:/tmp'``, and create that folder on the local filesystem if it doesn't exist.
.. COMMENT - HAMISHW Check if can sensibly or useful integrate any of this.
Also COMMENT ON ACTUALLY USING THE Emscripten on Linux. This MIGHT actually live in the tutorial since it will change where you navigate.
On Linux+OSX, you need to use the 'source' command to alter the current terminal. I.e. Linux+OSX call 'source ./emsdk_env.sh' when Windows calls 'emsdk_env.bat'. When you change the active tools with the 'activate' command, there should be a help message that describes that syntax.
On Linux+OSX there is no support for permanent path activation, but one needs to e.g. add the line 'source ~/emsdk/emsdk_env.sh' to home bash profile files or similar to bootstrap it to the console. On Windows one can use the --global flag for emsdk_env.bat.
Configuring the basic Emscripten settings file
============================================
The first time you run emcc (or any of the other Emscripten tools, for that matter), it will create a settings file at ``~/.emscripten`` (~ is your user's home directory) and exit. This file contains a number of settings that provide Emscripten with the Paths to all its requirements (LLVM, clang, etc.) amongst other things, and looks something like so: ::
import os
LLVM_ROOT='C:/Program Files/Emscripten/clang/3.2_64bit/bin'
NODE_JS='C:/Program Files/Emscripten/node/0.10.17_64bit/node.exe'
PYTHON='C:/Program Files/Emscripten/python/2.7.5.3_64bit/python.exe'
JAVA='C:/Program Files/Emscripten/java/7.45_64bit/bin/java.exe'
EMSCRIPTEN_ROOT='C:/Program Files/Emscripten/emscripten/1.7.8'
CRUNCH='C:/Program Files/Emscripten/crunch/1.03/crunch.exe'
MINGW_ROOT='C:/Program Files/Emscripten/mingw/4.6.2_32bit'
SPIDERMONKEY_ENGINE = ''
V8_ENGINE = ''
TEMP_DIR = 'c:/users/cmills/appdata/local/temp'
COMPILER_ENGINE = NODE_JS
JS_ENGINES = [NODE_JS]
If you used an emsdk installer to install Emscripten everything would be set up automatically, but since you probably built everything manually (since you are reading this section) you'll need to set the Emscripten settings yourself.
1. If you haven't run Emscripten before, run it now with (assumes you are in ``emsdk`` and haven't set it's location in your PATH):
::
./Emscripten/1.7.8/emcc
.. note:: This is for Mac/Linux; on Windows you would use emcc instead.
.. note:: If you are having trouble with python versions, you can also explicitly invoke
::
python emcc
especially if python2 is not defined in your system. python2 allows python 2 and 3 to be installed together on one system, which is increasingly common; as an alternative to python emcc, you can also add a symlink to python from python2). In that case you should also update the PYTHON line in the ~/.emscripten settings file.
#. Edit the ``~/.emscripten`` file now using your favourite text editor.
#. Change the directory locations of ``LLVM_ROOT`` and ``NODE_JS`` to the right places in your setup (specifically, edit ``LLVM_ROOT`` and ``NODE_JS``). If those paths are not right, Emscripten will not find LLVM, Clang or Node.js and return a failure message. Look at the comments in the file that explain what the settings are and which ones you need to change.
#. After setting those paths, run ``./Emscripten/1.7.8/emcc`` again. It should again perform the sanity checks to test the specified paths. If they don't all pass, you might have a typo somewhere. When everything is set up properly, running ``./Emscripten/1.7.8/emcc`` should return ``emcc: no input files``, and you should be ready to use it.
Configuring Emscripten settings
===============================
Almost all the compiler settings used by Emscripten are defined in the :ref:`compiler configuration file (~/.emscripten) <compiler-configuration-file>`, a user-specific file located in the user's home directory.
Instructions for creating and manually configuring up this file are given in :ref:`configuring-emscripten-settings`.
Validating the environment
===============================
The best way to validate the environment is to build some code.
There are some basic validation and troubleshooting instructions in the topic: :ref:`verifying-the-emscripten-environment`.
.. comment: This is a comment that might go in the "verifying" section.
**HamishW** Also see what can come out of the Downloads validating section. May be some scope for reuse.
**HamishW** confirm that you can't use paths set up by emscripten - you have to actually specify which emcc you want to run? on Linux.
You can also validate the individual parts of the toolchain have been installed, as described above: ::
# Test emcc. This should print out the *emcc* version number as well as run some basic tests
The best way to validate the environment is to build some code. Open the terminal in your *Emscripten* directory (where *emcc* is located) and enter: ::
./emcc tests/hello_world.cpp
If this builds **a.out.js** in the current directory, and you don't see any build errors in the terminal, Emscripten is good to go!
There are additional validation and troubleshooting instructions in the topic: :ref:`verifying-the-emscripten-environment`.

156
site/source/docs/building_from_source/building_emscripten_from_source_on_mac_os_x.rst
Просмотреть файл

@ -1,135 +1,89 @@
.. _Getting-started-on-Mac-OS-X:
.. _building-emscripten-on-mac-osx-from-source:
================================================
Building Emscripten on Mac OS X (wiki-import)
================================================
.. note:: This article was migrated from the wiki (Fri, 25 Jul 2014 04:21) and is now the "master copy" (the version in the wiki will be deleted). It may not be a perfect rendering of the original but we hope to fix that soon!
==================================================
Building Emscripten on Mac OS X (ready-for-review)
==================================================
This guide instructs step-by-step on how to setup emscripten on a clean Mac OS X box. The steps have been tested against OS X version 10.8.2.
.. tip:: The :ref:`Portable SDK for Linux <portable-emscripten-sdk-linux-osx>` (and Mac OS X) provides the **easiest** and **most reliable** method for **building from source**. Just :ref:`download and install the SDK <sdk-download-and-install>` and follow the brief instructions :ref:`here <emsdk-master-or-incoming-sdk>`.
Note for `homebrew <https://github.com/Homebrew/homebrew>`__ users:
``brew install emscripten`` does all the steps below for you (including installation of the llvm fastcomp compiler and patching the python interpreter).
These instructions are provided for developers who, for whatever reason, prefer a manual approach.
1. Install svn if you do not have it yet. It is distributed with XCode Command Line Tools in OSX App Store. See http://superuser.com/questions/455214/where-is-svn-on-os-x-mountain-lion
This page contains basic instructions on how to manually build and configure Emscripten from source on a clean (OS X version 10.8.2) clean Mac OS X box.
- Install XCode from OSX App Store.
- In XCode->Preferences->Downloads, install Command Line Tools.
- Test that svn works from command line: type 'svn --version' in terminal.
What you'll need
=================
2. Install git if you do not have it yet:
The topic :ref:`Emscripten Toolchain <toolchain-what-you-need>` lists the specific versions of tools that are needed.
- Allow installation of unsigned packages, or installing git package won't succeed: https://www.my-private-network.co.uk/knowledge-base/apple-related-questions/osx-unsigned-apps.html
- Download and install git from http://git-scm.com/
- Test that git works from command line: type 'git --version' in terminal.
3. Install cmake if you do not have it yet:
Installing required tools
==========================
- Download and install cmake-2.8.10.2-Darwin64-universal.dmg or newer from http://www.cmake.org/cmake/resources/software.html
- Test that cmake works from command line: type 'cmake --version' in terminal.
These instructions explain how to install **all** the :ref:`required tools <toolchain-what-you-need>`. You can :ref:`test whether some of these are already installed <toolchain-test-which-dependencies-are-installed>` on the platform and skip those steps.
4. Build LLVM+Clang 3.2 from SVN repository:
#. Install the *XCode Command Line Tools*. These include the toolchain to build :term:`Fastcomp`, and also are a precondition for *git*.
::
- Install XCode from the `Mac OS X App Store <http://superuser.com/questions/455214/where-is-svn-on-os-x-mountain-lion>`_.
- In **XCode | Preferences | Downloads**, install *Command Line Tools*.
cd ~
svn co http://llvm.org/svn/llvm-project/llvm/tags/RELEASE\_32/final llvm32
cd llvm32/tools
svn co http://llvm.org/svn/llvm-project/cfe/tags/RELEASE\_32/final clang
cd ../..
mkdir llvm32build
cd llvm32build
cmake -DCMAKE\_BUILD\_TYPE=Release -G "Unix Makefiles" ../llvm32
make
#. Install *git*:
After these steps, Clang 3.2 will be built into ~/llvm32build/bin. The source tree ~/llvm32 is not needed anymore, if you want to conserve disk space.
- Allow installation of unsigned packages, or installing git package `won't succeed <https://www.my-private-network.co.uk/knowledge-base/apple-related-questions/osx-unsigned-apps.html>`_.
- Install XCode and the XCode Command Line Tools (should already have been done). This will provide *git* to the system PATH (see `this stackoverflow post <http://stackoverflow.com/questions/9329243/xcode-4-4-command-line-tools>`_).
- Download and install git directly from http://git-scm.com/.
Note that XCode ships with a custom version of Clang (3.1svn or 3.2svn depending on XCode version). It may be possible to omit this step and just use the version provided by XCode, but the LLVM 3.2 RELEASE version is preferred, since that is the "officially supported version" the Emscripten OSX unit tests are run against.
#. Install *cmake* if you do not have it yet:
5. Set up Clang 3.2 in PATH:
- Download and install `cmake-2.8.10.2-Darwin64-universal.dmg <http://www.cmake.org/cmake/resources/software.html>`_ (or newer)
::
cd ~
echo "export PATH=~/llvm32build/bin:$PATH" >> .profile
#. Install *node.js* from http://nodejs.org/
The above change is permanent and it persists between system restarts. It only affects the current user.
6. Close all terminal windows, and open a new one. Check that clang works ok in path:
.. _getting-started-on-osx-install-python2:
::
#. Setup *python2* (this step is needed to workaround a bug reported in `#763 <https://github.com/kripken/emscripten/issues/763>`_):
cd ~
clang --version
The command should output: clang version 3.2 (tags/RELEASE\_32/final 176107) Target: x86\_64-apple-darwin12.2.1 Thread model: posix
7. Delete old .emscripten file if it happened to exist:
::
rm ~/.emscripten
rm -rf ~/.emscripten\_cache
8. Set up node:
- Download and install node from http://nodejs.org/
- Test that node works from command line: type 'node --version' in terminal.
9. Obtain Emscripten:
::
cd ~
git clone https://github.com/kripken/emscripten.git
By default, git will clone the emscripten 'incoming' branch, which is the branch where the newest developments of Emscripten occur. If you want to use a more stable branch, switch to the 'master' branch: - cd ~/emscripten - git checkout master
.. _getting-started-on-osx-install-python2:
10. Setup 'python2': (this step is needed to workaround a bug reported in `#763 <https://github.com/kripken/emscripten/issues/763>`__)
- In terminal, type 'python2 --version'. If you get a "command not found", type the following: ::
- In terminal, type ``python2 --version``. If you get a "command not found", type the following: ::
cd /usr/bin
sudo ln python python2
sudo ln ../../System/Library/Frameworks/Python.framework/Versions/2.7/bin/python2.7 python22.7
- Issue 'python2 --version' again. It should now print Python 2.7.2
- Enter ``python2 --version`` again. It should now print Python 2.7.2
11. Perform emscripten "first run":
#. Build :term:`Fastcomp` (LLVM + Clang) from source using :ref:`these instructions <building-fastcomp-from-source>`.
::
#. Clone the `kripken/emscripten <https://github.com/kripken/emscripten>`_ repository from Github. This repository contains the main compiler tool for compiling C/C++ programs to JavaScript:
cd ~/emscripten
/emcc --help
- Create a directory (with no spaces in the name) to contain the clone.
- Enter the following command into the terminal: ::
git clone https://github.com/kripken/emscripten.git
Configuring Emscripten settings
===============================
Almost all the compiler settings used by Emscripten are defined in the :ref:`compiler configuration file (~/.emscripten) <compiler-configuration-file>`, a user-specific file located in the user's home directory.
Instructions for creating and manually configuring up this file are given in :ref:`configuring-emscripten-settings`.
Validating the environment
===============================
The best way to validate the environment is to build some code. Open the terminal in your *Emscripten* directory (where *emcc* is located) and enter: ::
./emcc tests/hello_world.cpp
If this builds **a.out.js** in the current directory, and you don't see any build errors in the terminal, Emscripten is good to go!
There are additional validation and troubleshooting instructions in the topic: :ref:`verifying-the-emscripten-environment`.
- edit the file ~/.emscripten in a text editor to set up any required paths.
12. (Optional) Compile a simple test program to check that everything works:
::
cd ~/emscripten
./em++ tests/hello\_world.cpp
node a.out.js
The first run will most likely pop up an automatic prompt that asks to install java. Proceed, and after installation finishes, rerun the above commands. Running node should output: hello, world!
13. (Optional) Compile a simple WebGL program to check that .html output and GLES2/WebGL works:
::
cd ~/emscripten
./emcc tests/hello\_world\_gles.c -o hello\_world\_gles.html
open hello\_world\_gles.html
.. note:: If the Safari 6 browser pops up with a message "Could not create canvas :(", follow `these instructions <http://support.apple.com/kb/PH11926>`_ to enable WebGL support in Safari
14. (Optional) Run the full battery of tests to check that Emscripten is perfectly operational on the current platform: ::
cd ~/emscripten
python tests/runner.py
python tests/runner.py benchmark
Note that some tests will likely fail. Cross-reference the results with https://github.com/kripken/emscripten/issues?labels=tests to see if you are receiving currently unknown issues.

196
site/source/docs/building_from_source/building_emscripten_from_source_on_windows.rst
Просмотреть файл

@ -1,190 +1,86 @@
.. _Using-Emscripten-on-Windows:
.. _building-emscripten-on-windows-from-source:
==============================================
Building Emscripten on Windows (wiki-import)
==============================================
===================================================
Building Emscripten on Windows (ready-for-review)
===================================================
.. note:: This article was migrated from the wiki (Fri, 25 Jul 2014 04:21) and is now the "master copy" (the version in the wiki will be deleted). It may not be a perfect rendering of the original but we hope to fix that soon!
.. tip:: The :ref:`Emscripten Windows SDKs <emscripten-sdk-windows-installers>` provide the **easiest** and **most reliable** method for **building from source**. Just :ref:`download and install the SDK <sdk-download-and-install>` and follow the brief instructions :ref:`here <emsdk-master-or-incoming-sdk>`.
This page describes how to use Emscripten on Windows.
These instructions are provided for developers who, for whatever reason, prefer a manual approach.
Setting up the Emscripten Toolchain on Windows
----------------------------------------------
This page contains basic instructions on how to manually build and configure Emscripten from source on a clean Windows box.
This section contains basic instructions on how to start using Emscripten on a clean Windows box. After these steps, you can invoke emcc from the command line by calling 'python emcc'. 64-bit versions of all needed dependencies are preferred, and may be required if you are building large projects.
What you'll need
=================
The topic :ref:`Emscripten Toolchain <toolchain-what-you-need>` lists the specific versions of tools that are needed.
.. note:: 64-bit versions of all needed dependencies are preferred, and may be required if you are building large projects. However, if you plan to use the Visual Studio integration, do NOT install the 64-bit versions of the tools.
Installing required tools
~~~~~~~~~~~~~~~~~~~~~~~~~
==========================
1. Install Python 2.x (not 3.x) from http://www.python.org/.
These instructions explain how to install **all** the :ref:`required tools <toolchain-what-you-need>`. You can :ref:`test whether some of these are already installed <toolchain-test-which-dependencies-are-installed>` on the platform and skip those steps.
- e.g. `python-2.7.5.amd64.msi <http://python.org/ftp/python/2.7.5/python-2.7.5.amd64.msi>`_ for a 64-bit install.
- If you plan to use the Visual Studio integration, do NOT install the 64-bit version. Get the 32-bit version of python from `python-2.7.5.msi <http://python.org/ftp/python/2.7.5/python-2.7.5.msi>`_.
- Add the Python bin directory to your PATH. (Open up System Settings, Advanced system properties, click Environment Variables. Add "C:27" to the PATH, separated by a semicolon.) If on the other hand ``python.exe`` appears in "C:27" and not under bin, just add "C:27".
2. Install node.js from http://nodejs.org/
#. Install `Python 2.x <http://www.python.org/>`_ (not 3.x)
- e.g. `node-v0.10.17-x64.msi <http://nodejs.org/dist/v0.10.17/x64/node-v0.10.17-x64.msi>`_
- If you plan to use the Visual Studio integration, do NOT install the 64-bit version. Get the 32-bit version of node.js from `node-v0.10.17-x86.msi <http://nodejs.org/dist/v0.10.17/node-v0.10.17-x86.msi>`_.
- For example `python-2.7.5.amd64.msi <http://python.org/ftp/python/2.7.5/python-2.7.5.amd64.msi>`_ (64-bit version) or `python-2.7.5.msi <http://python.org/ftp/python/2.7.5/python-2.7.5.msi>`_ (32-bit version).
- Add the path to the Python directory containing **Python.exe** to your PATH.
3. Setup gcc 4.6 and llvm-clang 3.2.
- Paths are set by opening **System Settings | Advanced system properties**, clicking **Environment Variables** and select **PATH**.
- Add the path to python, separated by semicolons: e.g. ``;C:/Python27/;`` or ``;C:/Python27/bin;`` (depending on the location of the exe).
- If you like building the tools yourself or plan to use the Visual Studio integration (for which you need 32-bit versions of the tools) see below for how to build LLVM/Clang from source.
- Otherwise download the following 64-bit builds:
- `x86\_64-w64-mingw32-gcc-4.6.3-2-release-win64\_rubenvb.7z <http://sourceforge.net/projects/mingw-w64/files/Toolchains%20targetting%20Win64/Personal%20Builds/rubenvb/gcc-4.6-release/x86_64-w64-mingw32-gcc-4.6.3-2-release-win64_rubenvb.7z/download>`_
- `x86\_64-w64-mingw32-clang-3.2-release-win64\_rubenvb.7z <http://sourceforge.net/projects/mingw-w64/files/Toolchains%20targetting%20Win64/Personal%20Builds/rubenvb/clang-3.2-release/x86_64-w64-mingw32-clang-3.2-release-win64_rubenvb.7z/download>`_
#. Install `node.js <http://nodejs.org/>`_
- Extract both of them using `7zip <http://7-zip.org>`__ to the same location, e.g. C:64
- For example `node-v0.10.17-x64.msi <http://nodejs.org/dist/v0.10.17/x64/node-v0.10.17-x64.msi>`_ (64-bit version) or `node-v0.10.17-x86.msi <http://nodejs.org/dist/v0.10.17/node-v0.10.17-x86.msi>`_. (32-bit version).
4. If you do not already have a git client, Install `Github for Windows <http://windows.github.com/>`_.
5. Clone the ``kripken/emscripten`` repository from github. The emscripten repository contains the main compiler tool for compiling C/C++ programs to JavaScript.
- Launch the GitHub for Windows Client. You may click "Skip Setup" if you don't have a github account.
- (optional) Select "Options" from the gear menu, and customize the default storage directory. A path without spaces can save you lots of pain down the line.
- In your web browser, open https://github.com/kripken/emscripten and press the "Clone in Windows" button.
#. Install `gcc 4.6 <http://sourceforge.net/projects/mingw-w64/files/>`_
.. note:: If you already had a different git client, the repository URL is ``https://github.com/kripken/emscripten.git`` (e.g. ``git clone https://github.com/kripken/emscripten.git``)
#. Install `Github for Windows <http://windows.github.com/>`_ (or any other git client).
#. Install `Java <http://java.com/en/download/index.jsp>`_
Configuring Emscripten
~~~~~~~~~~~~~~~~~~~~~~
#. Build :term:`Fastcomp` (LLVM + Clang) from source using :ref:`these instructions <building-fastcomp-from-source>`.
1. Open up a command prompt, and change to the directory where you cloned the Emscripten repository. By default with the GitHub client, this will be ``C:\Users\username\Documents\GitHub\emscripten``.
2. Run ``python emcc --help``
#. Clone the `kripken/emscripten <https://github.com/kripken/emscripten>`_ repository from Github. This repository contains the main compiler tool for compiling C/C++ programs to JavaScript:
- You should get a ``Welcome to Emscripten!`` message. Behind the scenes, Emscripten generated a file called ``.emscripten`` in your Windows home folder.
- If you do not see this message, make sure that python is properly in your global PATH, and that you are in the Emscripten directory.
- Using *Github for Windows*:
- Launch the *GitHub for Windows* Client. Click **Skip Setup** if you don't have a github account.
- (optional) Select **Options** from the gear menu, and customize the default storage directory. Ensure the path has no spaces.
- In your web browser, open https://github.com/kripken/emscripten and press the **Clone in Windows** button.
3. Edit ``C:\Users\username\.emscripten``:
- Using the command line:
- Create a directory (with no spaces in the name) to contain the clone.
- Enter the following command into the terminal: ::
1. Edit the variable ``EMSCRIPTEN_ROOT`` to point to the Emscripten root folder, e.g. ``EMSCRIPTEN_ROOT = 'C:/Users/username/Documents/GitHub/emscripten'`` (Note: use forward slashes)
2. Edit the variable ``LLVM_ROOT`` to point directly to the path where you installed clang.exe, e.g. ::
git clone https://github.com/kripken/emscripten.git
``LLVM_ROOT = 'C:/mingw64/bin'``
3. Edit the variable TEMP\_DIR to point to a valid Windows path on your local system, e.g. ``TEMP_DIR = 'C:/tmp'``, and create that folder on the local filesystem if it doesn't exist.
4. If you are planning on using Cygwin and cygwin make in the future, copy the .emscripten file to your cygwin home folder as well, e.g.
copy C:.emscripten C: (There is a bug in Emscripten that it currently looks for the file .emscripten in two places (Win7 user home folder or cygwin user home folder), depending on the environment it is executed in, so as a current workaround these files must be present and identical on Windows. (see `issue #411 <https://github.com/kripken/emscripten/issues/411>`_))
.. comment: **Hamish** Can we/should we integrate some of the following:
Configuring Emscripten settings
===============================
Configuring the basic Emscripten settings file
============================================
Almost all the compiler settings used by Emscripten are defined in the :ref:`compiler configuration file (.emscripten) <compiler-configuration-file>`, a user-specific file located in the user's home directory.
.. COMMENT - HAMISHW from the MDN - and I suspect no longer needed now we have LLVM Backend. Check and delete if needed.
Instructions for creating and manually configuring this file are given in :ref:`configuring-emscripten-settings`.
The first time you run emcc (or any of the other Emscripten tools, for that matter), it will create a settings file at ``~/.emscripten`` (~ is your user's home directory) and exit. This file contains a number of settings that provide Emscripten with the Paths to all its requirements (LLVM, clang, etc.) amongst other things, and looks something like so: ::
import os
LLVM_ROOT='C:/Program Files/Emscripten/clang/3.2_64bit/bin'
NODE_JS='C:/Program Files/Emscripten/node/0.10.17_64bit/node.exe'
PYTHON='C:/Program Files/Emscripten/python/2.7.5.3_64bit/python.exe'
JAVA='C:/Program Files/Emscripten/java/7.45_64bit/bin/java.exe'
EMSCRIPTEN_ROOT='C:/Program Files/Emscripten/emscripten/1.7.8'
CRUNCH='C:/Program Files/Emscripten/crunch/1.03/crunch.exe'
MINGW_ROOT='C:/Program Files/Emscripten/mingw/4.6.2_32bit'
SPIDERMONKEY_ENGINE = ''
V8_ENGINE = ''
TEMP_DIR = 'c:/users/cmills/appdata/local/temp'
COMPILER_ENGINE = NODE_JS
JS_ENGINES = [NODE_JS]
If you used an emsdk installer to install Emscripten everything would be set up automatically, but since you probably built everything manually (since you are reading this section) you'll need to set the Emscripten settings yourself.
Validating the environment
===============================
1. If you haven't run Emscripten before, run it now with (assumes you are in ``emsdk`` and haven't set it's location in your PATH):
The best way to validate the environment is to build some code. Open the terminal in your *Emscripten* directory - the directory which contains *emcc* (if you installed using *Github for Windows* this will be **C:/Users/username/Documents/GitHub/emscripten**) and enter: ::
::
emcc tests/hello_world.cpp
./Emscripten/1.7.8/emcc
If this builds **a.out.js** in the current directory, and you don't see any build errors in the terminal, Emscripten is good to go!
.. note:: This is for Mac/Linux; on Windows you would use emcc instead.
.. note:: If you are having trouble with python versions, you can also explicitly invoke
::
There are additional validation and troubleshooting instructions in the topic: :ref:`verifying-the-emscripten-environment`.
python emcc
especially if python2 is not defined in your system. python2 allows python 2 and 3 to be installed together on one system, which is increasingly common; as an alternative to python emcc, you can also add a symlink to python from python2). In that case you should also update the PYTHON line in the ~/.emscripten settings file.
#. Edit the ``~/.emscripten`` file now using your favourite text editor.
#. Change the directory locations of ``LLVM_ROOT`` and ``NODE_JS`` to the right places in your setup (specifically, edit ``LLVM_ROOT`` and ``NODE_JS``). If those paths are not right, Emscripten will not find LLVM, Clang or Node.js and return a failure message. Look at the comments in the file that explain what the settings are and which ones you need to change.
#. After setting those paths, run ``./Emscripten/1.7.8/emcc`` again. It should again perform the sanity checks to test the specified paths. If they don't all pass, you might have a typo somewhere. When everything is set up properly, running ``./Emscripten/1.7.8/emcc`` should return ``emcc: no input files``, and you should be ready to use it.
Integrating Emscripten to Visual Studio 2010
--------------------------------------------
It is possible to integrate the Emscripten compiler directly to Visual Studio. This allows existing VS .sln files to be directly built using *emcc*. The Microsoft compiler property pages are replaced by *Clang* and emcc -specific options.
1. Install Visual Studio 2010
.. note:: Express version has not been tested, but should be ok. Please drop a line on Emscripten IRC channel or mailing list to report your experience with VS2010 Express!
2. Clone the juj/vs-tool repository from github:
- git clone https://github.com/juj/vs-tool
- The vs-tool repository contains a plugin to Visual Studio 2010 (or rather, to MSBuild) that instructs Visual Studio how to use the llvm-clang and emscripten toolchain.
3. Install vs-tool itself.
4. Navigate to folder vs-tool
5. Copy the folders Clang and Emscripten to C:Files (x86).Cpp.0\\.
6. Set up the required environment variables for vs-tool.
7. Windows 7: Open Control Panel -- System -- Advanced System Settings -- Environment Variables.
8. Create a new environment variable 'CLANG\_BIN' and set it to point to the folder where you built clang to (path to clang.exe) E.g.
- SETX CLANG\_BIN C:-build
- This is how vs-tool locates the folder to your llvm-clang compiler. Alternatively, this path can be set per-project in Visual Studio project property pages.
9. Create a new environment variable 'EMSCRIPTEN' and set it to point to the Emscripten git repository root folder (the path where you copied emcc.exe and other exes to). E.g.
- SETX EMSCRIPTEN C:
- This is how vs-tool locates the Emscripten compiler. This path
can also be overridden per-project in VS property pages.
10. Create a new environment variable 'EMCC\_WEBBROWSER\_EXE' and set it to point to an executable you want to use to browse Emscripten-generated web pages from Visual Studio. This process is spawned when you tap Start (Ctrl-F5) in Visual Studio for an Emscripten-targeted project.
- SETX EMCC\_WEBBROWSER\_EXE C:Files (x86)Firefox.exe
11. Now you are all set to start developing Emscripten-based projects from Visual Studio. To test the installation, open the Visual Studio solution file 10\_msvc10.sln.
Tips for using Emscripten from the Visual Studio 2010 IDE
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
To build a Visual Studio solution using the Emscripten toolchain, select the "Emscripten" configuration from the Configuration Manager dropdown as the active configuration, and choose Build Solution (F7).
To launch a project directly to a web browser from Visual Studio, right-click on the project to run, choose "Set as Startup Project", and select Start without Debugging (Ctrl+F5). This should launch the generated .html file to the browser you specified in EMCC\_WEBBROWSER\_EXE. A bug(?) in Visual Studio causes a "Executable for Debug Session" dialog to occasionally open up when you hit Ctrl+F5. This can be ignored by clicking Yes, then No, or simply by hitting Esc and then tapping Ctrl+F5 again.
llvm-clang and Emscripten compiler settings can be edited for the project in the "usual" Visual Studio fashion: First make sure that the Emscripten platform configuration is active, then right-click on a project, and choose Properties. In the Project properties dialog, two
tree nodes Clang C/C++ and Emcc Linker should exist, which allow you to specify the desired compilation options.
If you have an existing solution file you want to build using Emscripten, open the Configuration Manager.. dialog for the solution, and in the Active Solution Platform dropdown, choose New.... In the new dialog, choose Emscripten as the platform name, and Copy settings from
Empty. After this, you can switch between building the solution for Win32 and Emscripten from the Configuration Manager dropdown list.
When you want to create a new Visual Studio project for Emscripten, we recommend you start with a Visual C++ Empty Project. This will create a new project for the Win32 platform. Then convert that project for Emscripten as outlined in the previous paragraph.
Building LLVM/Clang from Source
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
In case the above-referenced prebuilt binaries do not work for you, you can build LLVM and Clang from source.
To install and set up ``llvm-clang 3.2``, open a Visual Studio 2010 command prompt and type:
1. ``svn co http://llvm.org/svn/llvm-project/llvm/tags/RELEASE_32/final llvm``
2. ``cd llvm\tools``
3. ``svn co http://llvm.org/svn/llvm-project/cfe/tags/RELEASE_32/final clang``
4. ``cd ..\\..``
5. ``mkdir build``
6. ``cd build``
7. ``cmake -G "Visual Studio 10" ..\llvm``
8. ``msbuild LLVM.sln /p:Configuration=Release``
If you have problems with the above, see more help here: http://clang.llvm.org/get\_started.html
.. note:: Instead of checking out the trunk as the guide suggests, check out the latest tagged release of Clang (3.2 at the time of writing). An older version will not most likely work with Emscripten.

104
site/source/docs/building_from_source/configuring_emscripten_settings.rst Normal file
Просмотреть файл

@ -0,0 +1,104 @@
.. _configuring-emscripten-settings:
=====================================================================================
Configuring Emscripten Settings when Manually Building from Source (ready-for-review)
=====================================================================================
.. note:: These instructions are are only useful if you are building Emscripten manually from source! If you're using the :ref:`SDK <sdk-download-and-install>` you should never manually update the settings, because the :ref:`emsdk` automatically overwrites the file with the appropriate compiler settings when you :term:`activate <Active Tool/SDK>` a tool or SDK.
The compiler settings used by Emscripten are defined in the :ref:`compiler configuration file (~/.emscripten) <compiler-configuration-file>`. These settings include paths to the tools (LLVM, Clang, Java etc.) and the compiler's temporary directory for intermediate build files.
This article explains how to create and update the file when you are building Emscripten :ref:`manually <installing-from-source>` from source.
Creating the compiler configuration file
========================================
The settings file is created the first time a user runs :ref:`emcc <emccdoc>` (or any of the other Emscripten tools):
1. Navigate to the directory where you cloned the Emscripten repository.
2. Enter the command:
::
./emcc --help
You should get a ``Welcome to Emscripten!`` message. Behind the scenes, Emscripten generated a file called ``.emscripten`` in your home folder.
Emscripten makes a "best guess" at the correct locations for tools and updates the file appropriately. Where possible it will look for "system" apps (like Python and Java) and infer the location of the ``EMSCRIPTEN_ROOT`` (where :ref:`emcc <emccdoc>` is located) from the location of the command prompt.
The file will probably not include the link to :term:`Fastcomp` (``LLVM_ROOT``) as a manual source build can create this anywhere.
Locating the compiler configuration file (.emscripten)
=======================================================
The settings file is created in the user's home directory:
- On Linux and Mac OS X this file is named **~/.emscripten**, where ~ is the user's home directory.
.. note:: On Linux, files with the "." prefix are hidden by default. You may need to change your view settings to find the file.
- On Windows the file can be found at a path like: **C:/Users/yourusername_000/.emscripten**.
Compiler configuration file-format
==================================
.. note:: While the syntax is identical, the appearance of the default **.emscripten** file created by *emcc* is quite different than that created by *emsdk* (see :ref:`here <compiler-configuration-file>`). This is because *emsdk* manages multiple target environments, and where possible hard codes the locations of those tools when a new environment is activated. The default file, by contrast, only needs to manage a single environment, but needs to make it as easy for the user as possible to configure manually.
The file simply assigns paths to a number of *variables* representing the the main tools used by Emscripten. For example, if the user cloned Emscripten to the **C:/Users/username/Documents/GitHub/emscripten** directory, then the file would have the line: ::
EMSCRIPTEN_ROOT = 'C:/Users/username/Documents/GitHub/emscripten'
The default *emcc* configuration file often gets the paths from environment variables if defined. If no variable is defined the system will also attempt to find "system executables". For example: ::
PYTHON = os.path.expanduser(os.getenv('PYTHON') or 'C:\\Python27\\python2.exe')
You can find out the other variable names from the default *.emscripten* file or the :ref:`example here <compiler-configuration-file>`.
Editing the compiler configuration file
=======================================
The compiler configuration file can be edited with the text-editor of your choice. As stated above, most default settings are likely to be correct. If you're building manually from source, you are most likely to have to update the variable ``LLVM_ROOT`` (for :term:`Fastcomp`).
#. Edit the variable ``LLVM_ROOT`` to point directly to the path where you :ref:`built Fastcomp <llvm-update-compiler-configuration-file>`. This path is likely to be something like **<LVVM root>/build/Release/bin** or <LVVM root>/build/bin**, where ``<LVVM root>`` is wherever you cloned LVVM:
::
LLVM_ROOT = 'os.path.expanduser(os.getenv('LVVM') or '/home/ubuntu/a-path/emscripten-fastcomp/build/bin')'
.. note:: Use forward slashes!
#. Edit the variable ``TEMP_DIR`` to point to a valid path on your local system, e.g. ``TEMP_DIR = '/tmp'`` (``TEMP_DIR = 'c:/tmp'`` on Windows), and create that folder on the local filesystem if it doesn't exist.
#. You *may* need to edit the variable ``EMSCRIPTEN_ROOT`` to point to the Emscripten root folder, e.g.:
::
EMSCRIPTEN_ROOT = os.path.expanduser(os.getenv('EMSCRIPTEN') or '/home/ubuntu/yourpath/emscripten') # directory
.. comment .. The settings are now correct in the configuration file, but the paths and environment variables are not set in the command prompt/terminal. **HamishW** Follow up with Jukka on htis.
After setting those paths, run ``emcc`` again. It should again perform the sanity checks to test the specified paths. There are further validation tests in: :ref:`verifying-the-emscripten-environment`.

19
site/source/docs/building_from_source/index.rst
Просмотреть файл

@ -1,12 +1,18 @@
.. _installing-from-source:
======================================================================================
Building Emscripten from Source (under-construction)
======================================================================================
==================================================
Building Emscripten from Source (ready-for-review)
==================================================
Instead of using the SDK, you can grab the code and dependencies yourself. This is a little more technical but lets you use the very latest development code.
.. tip:: The *SDK* provides the **easiest** and **most reliable** method for **building from source**. Just :ref:`download the SDK <sdk-download-and-install>` and follow the brief instructions :ref:`here <emsdk-master-or-incoming-sdk>`.
The instructions for setting up Emscripten on each platform are given below, followed by guidance on how to validate your environment once it is complete:
This section is provided for developers who, for whatever reason, prefer a manual approach.
.. note:: A user can't "manually " build from sources and use the SDK at the same time, because the SDK overwrites manual changes made to the user's :ref:`compiler configuration file <configuring-emscripten-settings>`.
This section shows how to get the source and dependencies and build Emscripten from sources.
The instructions for building Emscripten on the different platforms are given below, followed by guidance on how to update the configuration file and validate your environment once it is complete:
.. toctree::
:maxdepth: 1
@ -14,8 +20,9 @@ The instructions for setting up Emscripten on each platform are given below, fol
toolchain_what_is_needed
building_emscripten_from_source_on_linux
building_emscripten_from_source_on_windows
manually_integrating_emscripten_with_vs2010
building_emscripten_from_source_on_mac_os_x
LLVM-Backend
configuring_emscripten_settings
verify_emscripten_environment

72
site/source/docs/building_from_source/manually_integrating_emscripten_with_vs2010.rst Normal file
Просмотреть файл

@ -0,0 +1,72 @@
.. _emscripten-and-vs2010-manual-integration-on-windows:
==========================================================================
Manually Integrating Emscripten into Visual Studio 2010 (ready-for-review)
==========================================================================
.. tip:: The :term:`vs-tool` plugin is installed automatically by the :term:`Windows NSIS Installer Emscripten SDK` if *Visual Studio 2010* is present on the target system at install time. These instructions are only needed if you're :ref:`manually building from source <installing-from-source>`, or for some other reason cannot use the SDK.
*vs-tool* is a *MSBuild* plugin that tells *Visual Studio* how to use the *Fastcomp* (LVVM + Clang) and Emscripten toolchain. The plugin allows existing Visual Studio **.sln** files to be directly built through the IDE using :ref:`emcc <emccdoc>`. The Microsoft compiler property pages are replaced by *Fastcomp*- and *emcc*- specific options.
The following instructions explain how to manually set up *vs-tool*.
.. note:: `At time of writing <https://github.com/juj/vs-tool/issues/5>`_ *vs-tool* only supports Visual Studio 2010.
Install the vs-tool plugin
============================
1. Install Visual Studio 2010
.. note:: The Express version has not been tested, but should be work. :ref:`contact` if you have any problems integrating with VS2010 Express!
#. Clone the juj/vs-tool repository from github:
::
git clone https://github.com/juj/vs-tool
#. Install vs-tool itself:
#. Navigate to folder **vs-tool** in the repository clone.
#. Copy the folders **Clang** and **Emscripten** to **C:/Program Files (x86)/MSBuild/Microsoft.Cpp/v4.0/Platforms/**.
#. Set up the required environment variables for *vs-tool*.
#. Windows 7: Open **Control Panel | System | Advanced System Settings | Environment Variables**.
#. Create a new environment variable ``CLANG_BIN`` and set it to point to the folder where you built *Fastcomp* (path to **clang.exe**) E.g.:
::
SETX CLANG_BIN C:/Projects/llvm-build/bin/Release
This variable is how *vs-tool* locates the folder to your *Fastcomp* compiler. Alternatively, this path can be set on a per-project basis in the *Visual Studio project property* pages.
#. Create a new environment variable ``EMSCRIPTEN`` and set it to point to the Emscripten git repository root folder (the path where you copied **emcc.exe** and the other exes). E.g.:
::
SETX EMSCRIPTEN C:/Projects/emscripten
This variable is how *vs-tool* locates the Emscripten compiler. This path can also be overridden on a per-project basis in the Visual Studio property pages.
#. Create a new environment variable ``EMCC_WEBBROWSER_EXE`` and set it to point to an executable you want to use to browse in Emscripten-generated web pages from Visual Studio. This process is spawned when you tap **Start** (**Ctrl-F5**) in Visual Studio for an Emscripten-targeted project:
::
SETX EMCC_WEBBROWSER_EXE C:/Program Files (x86)/Mozilla Firefox/firefox.exe
#. Now you are all set to start developing Emscripten-based projects from *Visual Studio*.
Test the installation
======================
To test the installation, open and build the Visual Studio solution file **/emscripten/tests/msvc10/tests_msvc10.sln**.
That project builds a few select samples from inside the Emscripten **tests/** folder (for example "hello world", "hello gles", etc.), and is a good verification of the integration.
Learn more
==========
There is a basic guide to using Emscripten from within Visual Studio in the :ref:`Getting Started <getting-started-emscripten-from-vs2010>` section.

16
site/source/docs/building_from_source/toolchain_what_is_needed.rst
Просмотреть файл

@ -1,10 +1,14 @@
.. _emscripten-toolchain-top:
============================================================
Emscripten Toolchain (under-construction)
============================================================
=======================================
Emscripten Toolchain (ready-for-review)
=======================================
The :ref:`SDKs <sdk-download-and-install>` deliver (or explain how to obtain) everything you need for developing with Emscripten. However if you're building from source you'll need to gather the tools below yourself.
The instructions below list the main tools and dependencies in an Emscripten environment, along with instructions on how to test which dependencies are installed.
.. tip:: The :ref:`SDK <sdk-download-and-install>` provides the **easiest** and **most reliable** method for getting, using, updating and managing Emscripten environments, including **building from source**. If you're using the SDK you won't *need* these instructions, and they are provided for information only.
The instructions are useful if you're :ref:`manually <installing-from-source>` building from source.
.. _toolchain-what-you-need:
@ -22,7 +26,7 @@ A complete Emscripten environment includes the following tools:
.. note: 64-bit versions of all needed dependencies are preferred, and may be required if you are building large projects.
When building from sources you will also need a compiler environment (to build :ref:`Fastcomp <LLVM-Backend>`):
When building manually from sources you will also need a compiler environment (to build :ref:`Fastcomp <LLVM-Backend>`):
- *gcc* (4.6 or later)
@ -31,7 +35,7 @@ When building from sources you will also need a compiler environment (to build :
.. _toolchain-test-which-dependencies-are-installed:
Test which tools are installed
====================================
==============================
Some of the tools are pre-installed on the various platforms (for example, Python is always available on Linux builds).

31
site/source/docs/building_from_source/verify_emscripten_environment.rst
Просмотреть файл

@ -10,9 +10,12 @@ Verifying the Emscripten Development Environment (ready-for-review)
Testing the environment
=======================
The first step in verifying the environment is to run Emscripten with the version command (``-v``).
Sanity tests
------------
Open a terminal in the directory in which you installed Emscripten (on Windows open the :ref:`Emscripten Command Prompt <emcmdprompt>`). Then call the :ref:`Emscripten Compiler Frontend (emcc) <emcc>` as shown:
The first step in verifying the environment is to run Emscripten with the version command (``-v``). The command prints out information about the toolchain and runs some basic sanity tests to check that required tools are available.
Open a terminal in the directory in which you installed Emscripten (on Windows open the :ref:`Emscripten Command Prompt <emcmdprompt>`). Then call the :ref:`Emscripten Compiler Frontend (emcc) <emccdoc>` as shown:
::
@ -20,7 +23,7 @@ Open a terminal in the directory in which you installed Emscripten (on Windows o
.. note:: On Windows, invoke the tool with **emsdk** instead of **./emsdk**:
The command prints out information about the toolchain and runs some basic sanity checks. For example, the following output reports an installation where Java is missing:
For example, the following output reports an installation where Java is missing:
.. code-block:: javascript
:emphasize-lines: 6
@ -36,15 +39,25 @@ At this point you need to :ref:`Install and activate <fixing-missing-components-
WARNING root: no input files
The next test is to actually build some code! On the command prompt try to build the **hello_world.cpp** test code (in this case, from the 1.21.0 SDK): ::
./emcc ./emscripten/1.21.0/tests/hello_world.cpp
Build a basic example
---------------------
The next test is to actually build some code! On the command prompt navigate to the Emscripten directory for the current SDK and try to build the **hello_world.cpp** test code: ::
./emcc tests/hello_world.cpp
This command should complete without warnings and you should find the newly-compiled JavaScript file (**a.out.js**) in the current directory.
If compiling succeeds, you're ready for the :ref:`Tutorial`. If not, check out the troubleshooting instructions below.
Run the full test suite
------------------------
Emscripten has a comprehensive test suite which may be used to further validate all or parts of the toolchain. For more information, see :ref:`running-emscripten-tests`.
.. _troubleshooting-emscripten-environment:
Troubleshooting
@ -55,7 +68,7 @@ First run ``./emcc -v`` and examine the output to find missing components. You c
.. _fixing-missing-components-emcc:
Installing missing components
++++++++++++++++++++++++++++++++++++++++++++++++++++
-----------------------------
Missing tools can often be added using the :ref:`emsdk`. For example, to fix a warning that Java is missing, locate it in the repository, install it, and then set it as active: ::
@ -68,11 +81,11 @@ Missing tools can often be added using the :ref:`emsdk`. For example, to fix a w
#Set the component as active
./emsdk activate java-7.45-64bit
If the missing component is not listed in *emsdk*, then review the component's installation section in :ref:`installing-from-source`.
If you're :ref:`building Emscripten manually from source <installing-from-source>`, see that link for information on how to obtain all dependencies.
Other common problems
+++++++++++++++++++++++++
---------------------
Other common problems to check for are:
@ -81,7 +94,7 @@ Other common problems to check for are:
- Using older versions of LLVM. The correct versions come with the SDK, but if you're building the environment from source see :ref:`LLVM-Backend` for the proper repos for LLVM and Clang.
- Not having *python2* defined in your system. For compatibility with systems that install python 2.x alongside 3.x, we look for *python2*. If you only have python 2.x installed, symlink *python2* to *python* and update :ref:`.emscripten <compiler-configuration-file>`. You can also invoke the python scripts directly: ::
``python emcc``
python emcc
.. COMMENT:: **HamishW** Need to clarify if this last point on Python2 is Linux/Mac only, and if not, what needs to be done on Windows.

2
site/source/docs/getting_started/Tutorial.rst
Просмотреть файл

@ -15,7 +15,7 @@ First things first
Make sure you have :ref:`downloaded and installed <sdk-download-and-install>` Emscripten (the exact approach for doing this will depend your operating system: Windows, Mac or Linux).
Emscripten is accessed using the :ref:`emcc <emcc>`. This script invokes all the other tools needed to build your code, and can act as a drop-in replacement for a standard compiler like *gcc*. It is called on the command line using ``emcc`` or ``em++``
Emscripten is accessed using the :ref:`emcc <emccdoc>`. This script invokes all the other tools needed to build your code, and can act as a drop-in replacement for a standard compiler like *gcc*. It is called on the command line using ``emcc`` or ``em++``
.. note:: On Mac OS X the tool is called using the slightly different syntax: ``./emcc`` or ``./em++`` (or even directly via Python: ``python emcc``). The remainder of this tutorial uses the Windows syntax (``emcc``).

59
site/source/docs/getting_started/downloads.rst
Просмотреть файл

@ -6,7 +6,7 @@ Download and install (ready-for-review)
.. note:: The *Emscripten SDK* provides the whole Emscripten toolchain (*Clang*, *Python*, *Node.js* and *Visual Studio* integration) in a single easy-to-install package, with integrated support for :ref:`updating to newer SDKs <updating-the-emscripten-sdk>` as they are released.
.. tip:: If you are :doc:`contributing <../contributing/contributing>` to Emscripten you should :ref:`set up Emscripten from source <installing-from-source>`.
.. tip:: If you are :ref:`contributing <contributing>` to Emscripten you should first install the SDK, and then use it to :ref:`build Emscripten from source <sdk-building-emscripten-from-source>`.
SDK Downloads
@ -14,6 +14,8 @@ SDK Downloads
Download one of the SDK installers below to get started with Emscripten development. The Windows NSIS installers are the easiest to set up, while the portable SDKs can be moved between computers and do not require administration privileges.
.. emscripten-sdk-windows-installers:
Windows
-------
@ -101,8 +103,9 @@ Mac OS X
Java is not installed. To open Java, you need a Java SE 6 runtime.
Would you like to install one now?
- The *python2* command line tool is not present on OSX by default. To manually work around this issue, follow step 10 in :ref:`Getting started on Mac OS X <getting-started-on-osx-install-python2>`.
- The *python2* command line tool is not present on OSX by default. To manually work around this issue, follow the linked step in :ref:`Getting started on Mac OS X <getting-started-on-osx-install-python2>`.
.. **HamishW**: I think that Mac OS X has the same issues as Linux - ie you don't get ANYTHING much in the SDK. YOu will need the command line tools, but mostly for GCC - need to confirm this with Jukka
Linux
++++++++
@ -124,6 +127,58 @@ The easiest way to verify the installation is to compile some code using Emscrip
You can jump ahead to the :ref:`Tutorial`, but if you have any problems building you should run through the basic tests and troubleshooting instructions in :ref:`verifying-the-emscripten-environment`.
.. _sdk-building-emscripten-from-source:
Building Emscripten from source
======================================================
The SDK can be used to fetch and build the latest version of Emscripten from source. This allows you to obtain new features and the latest fixes as soon as they are pushed to Github (without having to wait for release to be tagged). **No Github account or fork of Emscripten is required!**
.. note:: The SDK is the recommended method of building Emscripten from source because it makes the process very easy, and allows you to treat the build as "just another SDK". Using the SDK allows you to easily toggle between the current SDK, older SDKs, and source-built environments, and to update to new SDKs and source updates as they become available.
It is also possible to :ref:`manually build from sources <installing-from-source>`, but this approach is more difficult, incompatible with the :ref:`SDK manager <emsdk>`, and not really needed!
You will also need a compiler toolchain to build from source:
- On Windows install `gcc 4.6 <http://sourceforge.net/projects/mingw-w64/files/>`_
- On Linux install *gcc* from the **build-essential** package:
::
sudo apt-get install build-essential
- On Mac OS X install the *XCode Command Line Tools*:
- Install XCode from the `Mac OS X App Store <http://superuser.com/questions/455214/where-is-svn-on-os-x-mountain-lion>`_.
- In **XCode | Preferences | Downloads**, install *Command Line Tools*.
To switch to using the latest upstream git development branch (``incoming``), run the following commands:
::
# Install latest git client. Skip if the system already has it.
./emsdk install git-1.8.3
# Clone+pull the latest kripken/emscripten/incoming.
./emsdk install sdk-incoming-64bit
# Set the "incoming SDK" as the active version.
./emsdk activate sdk-incoming-64bit
If you want to use the upstream stable branch ``master``, then replace ``-incoming-`` with ``-master-`` in the commands above.
.. note:: On Windows, *git* may fail with the error message:
::
Unable to find remote helper for 'https' when cloning a repository with https:// url.
The workaround is to uninstall git from *emsdk* (``emsdk uninstall git-1.8.3``) and install `Git for Windows <http://msysgit.github.io>`_. This issue is reported `here <https://github.com/juj/emsdk/issues/13>`_.
.. todo:: **HamishW** Check whether the bug (https://github.com/juj/emsdk/issues/13) is fixed and remove the above note if it is.
It is also possible to build your :ref:`own fork of the Emscripten using the SDK <emsdk-howto-use-own-fork>`.
.. _updating-the-emscripten-sdk:
Updating the SDK

19
site/source/docs/getting_started/getting_started_with_emscripten_and_vs2010.rst Normal file
Просмотреть файл

@ -0,0 +1,19 @@
.. getting-started-emscripten-from-vs2010:
===========================================================================================
Getting started using Emscripten from the Visual Studio 2010 IDE (under-construction)
===========================================================================================
To build a Visual Studio solution using the Emscripten toolchain, select the "Emscripten" configuration from the Configuration Manager dropdown as the active configuration, and choose Build Solution (F7).
To launch a project directly to a web browser from Visual Studio, right-click on the project to run, choose "Set as Startup Project", and select Start without Debugging (Ctrl+F5). This should launch the generated .html file to the browser you specified in EMCC\_WEBBROWSER\_EXE. A bug(?) in Visual Studio causes a "Executable for Debug Session" dialog to occasionally open up when you hit Ctrl+F5. This can be ignored by clicking Yes, then No, or simply by hitting Esc and then tapping Ctrl+F5 again.
llvm-clang and Emscripten compiler settings can be edited for the project in the "usual" Visual Studio fashion: First make sure that the Emscripten platform configuration is active, then right-click on a project, and choose Properties. In the Project properties dialog, two
tree nodes Clang C/C++ and Emcc Linker should exist, which allow you to specify the desired compilation options.
If you have an existing solution file you want to build using Emscripten, open the Configuration Manager.. dialog for the solution, and in the Active Solution Platform dropdown, choose New.... In the new dialog, choose Emscripten as the platform name, and Copy settings from
Empty. After this, you can switch between building the solution for Win32 and Emscripten from the Configuration Manager dropdown list.
When you want to create a new Visual Studio project for Emscripten, we recommend you start with a Visual C++ Empty Project. This will create a new project for the Win32 platform. Then convert that project for Emscripten as outlined in the previous paragraph.

1
site/source/docs/getting_started/index.rst
Просмотреть файл

@ -8,3 +8,4 @@ Getting Started (under-construction)
downloads
Tutorial
getting_started_with_emscripten_and_vs2010

3
site/source/docs/tools_reference/emcc.rst
Просмотреть файл

@ -1,5 +1,4 @@
.. _emcc:
.. _emccdoc:
=========================================================
Emscripten Compiler Frontend (emcc) (under-construction)

56
site/source/docs/tools_reference/emsdk.rst
Просмотреть файл

@ -11,14 +11,14 @@ This document provides the command syntax, and a :ref:`set of guides <emsdk_howt
Purpose
============================================
With *emsdk* you can download, install or remove *any* :term:`SDK` or :term:`Tool`, and even use the :ref:`bleeding edge versions <emsdk-master-or-incoming-sdk>` in development on Github. To access the *emsdk*, first launch the :ref:`Emscripten Command Prompt <emcmdprompt>`. Most operations are of the form ``emsdk command``.
With *emsdk* you can download, install or remove *any* :term:`SDK` or :term:`Tool`, and even use the :ref:`bleeding edge versions <emsdk-master-or-incoming-sdk>` in development on Github. To access the *emsdk*, first launch the :ref:`Emscripten Command Prompt <emcmdprompt>`. Most operations are of the form ``./emsdk command``.
Command line syntax
============================================
**emsdk** [**help** [**--old**] | **list** | **update** | **install** *<tool/sdk>* | **uninstall** *<tool/sdk>* | **activate** *<tool/sdk>*]
**./emsdk** [**help** [**--old**] | **list** | **update** | **install** *<tool/sdk>* | **uninstall** *<tool/sdk>* | **activate** *<tool/sdk>*]
Arguments
@ -41,13 +41,13 @@ Arguments
* - ``uninstall <tool/sdk>``
- Removes the :ref:`specified tool or SDK <emsdk-specified-tool-sdk>` from the disk.
* - ``activate <tool/sdk>``
- Sets the :ref:`specified tool or SDK <emsdk-specified-tool-sdk>` as the default tool in the system environment.
- Sets the :ref:`specified tool or SDK <emsdk-specified-tool-sdk>` as the default tool in the system environment. On Linux you additionally have to enable the environment settings using ``source ./emsdk_env.sh``, as described in ":ref:`emsdk-set-active-tools`".
* - ``help``
- Lists all supported commands. The same list is output if no command is specified.
.. note::
- For Mac OSX the commands are called with **./emsdk**.
- For Mac OSX the commands are called with **./emsdk**. On Windows use **emsdk**.
- **emcmdprompt.bat** is also displayed as an option in the ``emsdk help``. This is :ref:`not intended <emcmdprompt-command-line-syntax>` to be called through the command line.
@ -82,11 +82,11 @@ The *Compiler Configuration File* stores the :term:`active <Active Tool/SDK>` co
The configuration file is named **.emscripten**. It is user-specific, and is located in the user's home directory (**~/.emscripten** on Linux).
The file should not be updated directly. Instead use the *emsdk* to activate specific SDKs and tools as needed (``emsdk activate <tool/SDK>``).
The file should generally not be updated directly unless you're :ref:`building Emscripten from source <installing-from-source>`. Instead use the *emsdk* to activate specific SDKs and tools as needed (``emsdk activate <tool/SDK>``).
Below is a typical **.emscripten** file, taken from a user's root directory on Windows:
Below is a typical **.emscripten** file (created by *emsdk*), taken from a user's root directory on Windows. Note the variable names used to point to the different tools:
.. todo:: **HamishW** When I've fully tested on ubuntu perhaps include the file from there (since Linux is the most used platform.
.. todo:: **HamishW** When I've fully tested on ubuntu perhaps include the file from there (since Linux is the most used platform).
::
@ -122,20 +122,20 @@ How do I just get the latest SDK?
Use the ``update`` argument to fetch the current registry of available tools, and then specify the ``latest`` install target to get the most recent SDK: ::
# Fetch the latest registry of available tools.
emsdk update
./emsdk update
# Download and install the latest SDK tools.
emsdk install latest
./emsdk install latest
# Set up the compiler configuration to point to the "latest" SDK.
emsdk activate latest
./emsdk activate latest
How do I use emsdk?
--------------------------------
Use ``emsdk help`` or just ``emsdk`` to get information about all available commands.
Use ``./emsdk help`` or just ``./emsdk`` to get information about all available commands.
How do I check which versions of the SDK and tools are installed?
@ -143,7 +143,7 @@ How do I check which versions of the SDK and tools are installed?
To get a list of all currently installed tools and SDK versions (and all available tools) run: ::
emsdk list
./emsdk list
A line will be printed for each tool and 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.
@ -153,7 +153,9 @@ How do I install a tool/SDK version?
Use the ``install`` argument to download and install a new tool or SDK version: ::
emsdk install <tool/sdk name>
./emsdk install <tool/sdk name>
.. note:: An installed tool is present on the local machine, but not necessarily the active environment. To make an installed SDK active, use the ``activate`` command.
.. _emsdk-remove-tool-sdk:
@ -163,7 +165,7 @@ How do I remove a tool or an SDK?
Use the ``uninstall`` argument to delete a given tool or SDK from the local computer: ::
emsdk uninstall <tool/sdk name>
./emsdk uninstall <tool/sdk name>
If you want to completely remove Emscripten from your system, follow the guide at :ref:`downloads-uninstall-the-sdk`.
@ -175,18 +177,27 @@ How do I check for updates to the Emscripten SDK?
First use the ``update`` command to fetch package information for all new tools and SDK versions. Then use ``install <tool/sdk name>`` to install a new version: ::
# Fetch the latest registry of available tools.
emsdk update
./emsdk update
# Download and install the specified new version.
emsdk install <tool/sdk name>
./emsdk install <tool/sdk name>
.. _emsdk-set-active-tools:
How do I change the currently active SDK version?
----------------------------------------------------------------
Toggle between different tools and SDK versions using the :term:`activate <Active Tool/SDK>` command. This will set up ``~/.emscripten`` to point to that particular tool: ::
emsdk activate <tool/sdk name>
./emsdk activate <tool/sdk name>
# On Linux and OSX, also set the environment variables.
source ./emsdk_env.sh
.. note:: On Linux and Mac OS X, ``activate`` writes the required information to the configuration file, but cannot automatically set up the environment variables in the current terminal. To do this you need to call **/emsdk_env.sh** with the source prefix after calling ``activate``. The use of ``source`` is a security feature of Unix shells.
On Windows, calling ``activate`` automatically sets up the required paths and environment variables.
How do I install an old Emscripten compiler version?
@ -194,8 +205,8 @@ 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. Use the ``list --old`` argument to get a list of archived tool and SDK versions, and ``install <name_of_tool>`` to install it: ::
emsdk list --old
emsdk install <name_of_tool>
./emsdk list --old
./emsdk install <name_of_tool>
On Windows, you can directly install an old SDK version by using one of :ref:`these archived NSIS installers <archived-nsis-windows-sdk-releases>`.
@ -213,13 +224,13 @@ To switch to using the latest upstream git development branch (``incoming``), ru
::
# Install git. Skip if the system already has it.
emsdk install git-1.8.3
./emsdk install git-1.8.3
# Clone+pull the latest kripken/emscripten/incoming.
emsdk install sdk-incoming-64bit
./emsdk install sdk-incoming-64bit
# Set the "incoming SDK" as the active version.
emsdk activate sdk-incoming-64bit
./emsdk activate sdk-incoming-64bit
If you want to use the upstream stable branch ``master``, then replace ``-incoming-`` with ``-master-`` in the commands above.
@ -233,6 +244,7 @@ If you want to use the upstream stable branch ``master``, then replace ``-incomi
.. todo:: **HamishW** Check whether the bug (https://github.com/juj/emsdk/issues/13) is fixed and remove the above note if it is.
.. _emsdk-howto-use-own-fork:
How do I use my own Emscripten Github fork with the SDK?
----------------------------------------------------------------