Skip to content

Commit 78b2fc5

Browse files
hamishwilleehamishwillee
committed
changes to building from articles as a result of feedback from ChrisM. Significant fixes to LLVM-Backend doc
1 parent 8bd02e7 commit 78b2fc5

12 files changed

Lines changed: 296 additions & 142 deletions

‎site/source/docs/building_from_source/LLVM-Backend.rst‎

Lines changed: 207 additions & 78 deletions
Large diffs are not rendered by default.

‎site/source/docs/building_from_source/building_emscripten_from_source_on_linux.rst‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,12 +1,12 @@
11
.. _building-emscripten-on-linux:
22

3-
================================================
4-
Building Emscripten on Linux (ready-for-review)
5-
================================================
3+
============================
4+
Building Emscripten on Linux
5+
============================
66

77
.. 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>`.
88

9-
These instructions are provided for developers who, for whatever reason, prefer a manual approach.
9+
The instructions below are provided for developers who, for whatever reason, prefer a manual approach.
1010

1111
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.
1212

‎site/source/docs/building_from_source/building_emscripten_from_source_on_mac_os_x.rst‎

Lines changed: 5 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -6,9 +6,9 @@ Building Emscripten on Mac OS X (ready-for-review)
66

77
.. 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>`.
88

9-
These instructions are provided for developers who, for whatever reason, prefer a manual approach.
9+
The instructions below are provided for developers who, for whatever reason, prefer a manual approach.
1010

11-
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.
11+
This page contains basic instructions on how to manually build and configure Emscripten from source on a clean Mac OS X box (OS X version 10.8.2).
1212

1313
What you'll need
1414
=================
@@ -21,20 +21,20 @@ Installing required tools
2121

2222
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.
2323

24-
#. Install the *XCode Command Line Tools*. These include the toolchain to build :term:`Fastcomp`, and also are a precondition for *git*.
24+
#. Install the *XCode Command Line Tools*. These include the toolchain to build :term:`Fastcomp`, and are a precondition for *git*.
2525

2626
- Install XCode from the `Mac OS X App Store <http://superuser.com/questions/455214/where-is-svn-on-os-x-mountain-lion>`_.
2727
- In **XCode | Preferences | Downloads**, install *Command Line Tools*.
2828

2929
#. Install *git*:
3030

31-
- 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>`_.
31+
- `Allow installation of unsigned packages <https://www.my-private-network.co.uk/knowledge-base/apple-related-questions/osx-unsigned-apps.html>`_, or installing the git package won't succeed.
3232
- 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>`_).
3333
- Download and install git directly from http://git-scm.com/.
3434

3535
#. Install *cmake* if you do not have it yet:
3636

37-
- Download and install `cmake-2.8.10.2-Darwin64-universal.dmg <http://www.cmake.org/cmake/resources/software.html>`_ (or newer)
37+
- Download and install `cmake-2.8.10.2-Darwin64-universal.dmg <http://www.cmake.org/cmake/resources/software.html>`_ (or newer).
3838

3939

4040
#. Install *node.js* from http://nodejs.org/

‎site/source/docs/building_from_source/building_emscripten_from_source_on_windows.rst‎

Lines changed: 12 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -6,7 +6,7 @@ Building Emscripten on Windows (ready-for-review)
66

77
.. 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>`.
88

9-
These instructions are provided for developers who, for whatever reason, prefer a manual approach.
9+
The instructions below are provided for developers who, for whatever reason, prefer a manual approach.
1010

1111
This page contains basic instructions on how to manually build and configure Emscripten from source on a clean Windows box.
1212

@@ -16,40 +16,42 @@ What you'll need
1616

1717
The topic :ref:`Emscripten Toolchain <toolchain-what-you-need>` lists the specific versions of tools that are needed.
1818

19-
.. 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.
19+
.. 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 :ref:`integrate with Visual Studio <emscripten-and-vs2010-manual-integration-on-windows>`, do NOT install the 64-bit versions of the tools.
2020

2121
Installing required tools
2222
==========================
2323

2424
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.
2525

2626

27-
#. Install `Python 2.x <http://www.python.org/>`_ (not 3.x)
27+
#. Install `Python 2.x <http://www.python.org/>`_ (not 3.x):
2828

2929
- 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).
3030
- Add the path to the Python directory containing **Python.exe** to your PATH.
3131

32-
- Paths are set by opening **System Settings | Advanced system properties**, clicking **Environment Variables** and select **PATH**.
32+
- Paths are set by opening **System Settings | Advanced system properties**, clicking **Environment Variables** and selecting **PATH**.
3333
- Add the path to python, separated by semicolons: e.g. ``;C:/Python27/;`` or ``;C:/Python27/bin;`` (depending on the location of the exe).
3434

3535

36-
#. Install `node.js <http://nodejs.org/>`_
36+
#. Install `node.js <http://nodejs.org/>`_:
3737

38-
- 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).
38+
- 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).
3939

4040

41-
#. Install `gcc 4.6 <http://sourceforge.net/projects/mingw-w64/files/>`_
41+
#. Install `gcc 4.6 <http://sourceforge.net/projects/mingw-w64/files/>`_.
42+
43+
#. Install `cmake <http://www.cmake.org/cmake/resources/software.html>`_.
4244

4345
#. Install `Github for Windows <http://windows.github.com/>`_ (or any other git client).
4446

45-
#. Install `Java <http://java.com/en/download/index.jsp>`_
47+
#. Install `Java <http://java.com/en/download/index.jsp>`_.
4648

4749
#. Build :term:`Fastcomp` (LLVM + Clang) from source using :ref:`these instructions <building-fastcomp-from-source>`.
4850

4951
#. 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:
5052

5153
- Using *Github for Windows*:
52-
- Launch the *GitHub for Windows* Client. Click **Skip Setup** if you don't have a github account.
54+
- Launch the *GitHub for Windows* Client. Click **Skip Setup** if you don't have a Github account.
5355
- (optional) Select **Options** from the gear menu, and customize the default storage directory. Ensure the path has no spaces.
5456
- In your web browser, open https://github.com/kripken/emscripten and press the **Clone in Windows** button.
5557

@@ -74,7 +76,7 @@ Instructions for creating and manually configuring this file are given in :ref:`
7476
Validating the environment
7577
===============================
7678

77-
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: ::
79+
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: ::
7880

7981
emcc tests/hello_world.cpp
8082

‎site/source/docs/building_from_source/configuring_emscripten_settings.rst‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -65,11 +65,11 @@ Editing the compiler configuration file
6565
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`).
6666

6767

68-
#. 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:
68+
#. 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 **<LLVM root>/build/Release/bin** or <LLVM root>/build/bin**, where ``<LLVM root>`` is wherever you cloned LLVM:
6969

7070
::
7171
72-
LLVM_ROOT = 'os.path.expanduser(os.getenv('LVVM') or '/home/ubuntu/a-path/emscripten-fastcomp/build/bin')'
72+
LLVM_ROOT = 'os.path.expanduser(os.getenv('LLVM') or '/home/ubuntu/a-path/emscripten-fastcomp/build/bin')'
7373

7474
.. note:: Use forward slashes!
7575

‎site/source/docs/building_from_source/manually_integrating_emscripten_with_vs2010.rst‎

Lines changed: 11 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -6,40 +6,41 @@ Manually Integrating Emscripten into Visual Studio 2010 (ready-for-review)
66

77
.. 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.
88

9-
*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.
9+
*vs-tool* is an *MSBuild* plugin that tells *Visual Studio* how to use the *Fastcomp* (LLVM + 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.
1010

1111
The following instructions explain how to manually set up *vs-tool*.
1212

13-
.. note:: `At time of writing <https://github.com/juj/vs-tool/issues/5>`_ *vs-tool* only supports Visual Studio 2010.
13+
.. note:: Currently (August 2014) *vs-tool* `only supports <https://github.com/juj/vs-tool/issues/5>`_ Visual Studio 2010.
1414

1515
Install the vs-tool plugin
1616
============================
1717

18-
1. Install Visual Studio 2010
18+
1. Install `Visual Studio 2010 <http://www.visualstudio.com/downloads/download-visual-studio-vs>`_:
1919

20-
.. note:: The Express version has not been tested, but should be work. :ref:`contact` if you have any problems integrating with VS2010 Express!
20+
.. note:: The `Express <http://go.microsoft.com/?linkid=9709949>`_ version has not been tested, but should work. :ref:`contact` if you have any problems integrating with VS2010 Express!
2121

2222
#. Clone the juj/vs-tool repository from github:
2323

2424
::
2525
2626
git clone https://github.com/juj/vs-tool
2727

28-
#. Install vs-tool itself:
28+
#. Install the *vs-tool* plugin:
2929

30-
#. Navigate to folder **vs-tool** in the repository clone.
30+
#. Navigate to the **vs-tool** folder in the repository clone.
3131
#. Copy the folders **Clang** and **Emscripten** to **C:/Program Files (x86)/MSBuild/Microsoft.Cpp/v4.0/Platforms/**.
3232

3333
#. Set up the required environment variables for *vs-tool*.
3434

3535
#. Windows 7: Open **Control Panel | System | Advanced System Settings | Environment Variables**.
36+
#. Windows 8: Right click on the **Windows menu icon | System | Advanced System Settings | Environment Variables**.
3637
#. 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.:
3738

3839
::
3940

4041
SETX CLANG_BIN C:/Projects/llvm-build/bin/Release
4142

42-
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.
43+
This variable is how *vs-tool* locates the folder containing your *Fastcomp* compiler. Alternatively, this path can be set on a per-project basis in the *Visual Studio project property* pages.
4344

4445
#. 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.:
4546

@@ -49,20 +50,20 @@ Install the vs-tool plugin
4950
5051
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.
5152

52-
#. 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:
53+
#. Create a new environment variable ``EMCC_WEBBROWSER_EXE`` and set it to point to an executable you want to use to browse web pages generated using Emscripten via Visual Studio. This process is spawned when you tap **Start** (**Ctrl-F5**) in Visual Studio for an Emscripten-targeted project:
5354

5455
::
5556

5657
SETX EMCC_WEBBROWSER_EXE C:/Program Files (x86)/Mozilla Firefox/firefox.exe
5758

58-
#. Now you are all set to start developing Emscripten-based projects from *Visual Studio*.
59+
#. Now you are all set to start developing Emscripten-based projects using *Visual Studio*.
5960

6061
Test the installation
6162
======================
6263

6364
To test the installation, open and build the Visual Studio solution file **/emscripten/tests/msvc10/tests_msvc10.sln**.
6465

65-
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.
66+
That project builds a few select samples from inside the Emscripten **tests/** folder ("hello world", "hello gles", etc.), and is a good verification of the integration.
6667

6768

6869
Learn more

‎site/source/docs/building_from_source/toolchain_what_is_needed.rst‎

Lines changed: 37 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -1,21 +1,24 @@
11
.. _emscripten-toolchain-top:
22

3-
=======================================
4-
Emscripten Toolchain (ready-for-review)
5-
=======================================
3+
=================================
4+
Emscripten Toolchain Requirements
5+
=================================
66

77
The instructions below list the main tools and dependencies in an Emscripten environment, along with instructions on how to test which dependencies are installed.
88

9-
.. 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.
9+
.. 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 — they are provided for information only.
1010

11-
The instructions are useful if you're :ref:`manually <installing-from-source>` building from source.
11+
The instructions below are useful if you're :ref:`manually <installing-from-source>` building from source.
1212

1313
.. _toolchain-what-you-need:
1414

1515
What you'll need
1616
================
1717

18-
A complete Emscripten environment includes the following tools:
18+
Emscripten tools and dependencies
19+
---------------------------------
20+
21+
A complete Emscripten environment requires the following tools. First test to see if they are already installed using the :ref:`instructions below <toolchain-test-which-dependencies-are-installed>`. Then install any missing tools using the instructions in the appropriate platform-specific build topic (:ref:`building-emscripten-on-linux`, :ref:`building-emscripten-on-windows-from-source`, :ref:`building-emscripten-on-mac-osx-from-source`):
1922

2023
- :term:`Node.js` (0.8 or above; 0.10.17 or above to run websocket-using servers in node):
2124
- :term:`Python` 2.x (2.7.3 or above preferred)
@@ -26,11 +29,27 @@ A complete Emscripten environment includes the following tools:
2629

2730
.. note: 64-bit versions of all needed dependencies are preferred, and may be required if you are building large projects.
2831
29-
When building manually from sources you will also need a compiler environment (to build :ref:`Fastcomp <LLVM-Backend>`):
32+
.. note:: The `Spidermonkey shell <https://developer.mozilla.org/en-US/docs/Mozilla/Projects/SpiderMonkey/Introduction_to_the_JavaScript_shell>`_ is also required if you want to run **100%** of the tests in the test suite. Most developers will not need this, and should instead use *node.js*.
33+
34+
.. _compiler-toolchain:
35+
36+
Compiler toolchain
37+
------------------
3038

31-
- *gcc* (4.6 or later)
39+
When building Emscripten from source code, whether "manually" or using the SDK, you will also need a compiler toolchain:
40+
41+
- On Windows install `gcc 4.6 <http://sourceforge.net/projects/mingw-w64/files/>`_
42+
- On Linux install *gcc* from the **build-essential** package:
43+
44+
::
45+
46+
sudo apt-get install build-essential
3247
33-
.. note:: The *Spidermonkey* shell is also required if you want to run **100%** of the tests in the test suite. Most developers will not need this, and need only *node.js*.
48+
- On Mac OS X install the *XCode Command Line Tools*:
49+
50+
- Install XCode from the `Mac OS X App Store <http://superuser.com/questions/455214/where-is-svn-on-os-x-mountain-lion>`_.
51+
- In **XCode | Preferences | Downloads**, install *Command Line Tools*.
52+
3453

3554
.. _toolchain-test-which-dependencies-are-installed:
3655

@@ -39,7 +58,7 @@ Test which tools are installed
3958

4059
Some of the tools are pre-installed on the various platforms (for example, Python is always available on Linux builds).
4160

42-
You can check which tools are already present and only install those files that are needed:
61+
You can check which tools are already present using the following commands:
4362

4463
::
4564

@@ -50,7 +69,10 @@ You can check which tools are already present and only install those files that
5069
nodejs --version
5170
5271
# Check for node.js on Windows
53-
node --version #
72+
node --version #
73+
74+
# Check for node.js on Mac OS X
75+
node -v
5476
5577
# Check for git
5678
git --version
@@ -61,3 +83,7 @@ You can check which tools are already present and only install those files that
6183
# Check for gcc / g++
6284
gcc --version
6385
g++
86+
87+
# Check for cmake
88+
cmake
89+

‎site/source/docs/building_from_source/verify_emscripten_environment.rst‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -21,7 +21,7 @@ Open a terminal in the directory in which you installed Emscripten (on Windows o
2121

2222
./emcc -v
2323

24-
.. note:: On Windows, invoke the tool with **emsdk** instead of **./emsdk**:
24+
.. note:: On Windows, invoke the tool with **emsdk** instead of **./emsdk**.
2525

2626
For example, the following output reports an installation where Java is missing:
2727

0 commit comments

Comments
 (0)