Update docs about current installation issues (#6298) [ci skip]

* update docs regarding #6275 (github changes with SSL that force a newer python version) and #6288 (just mention the emsdk script itself from github, not the binary releases which we don't have a working solution for atm)

* mention zip download from github, and update docs to reflect that binary packages are now available for linux, no need to build from source

* mention Windows Subsystem for Linux

Author: kripken

site/source/docs/building_from_source/toolchain_what_is_needed.rst

@@ -23,7 +23,7 @@ Emscripten tools and dependencies
 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`):
 
 	- :term:`Node.js` (0.8 or above; 0.10.17 or above to run websocket-using servers in node):
-	- :term:`Python` 2.7 (2.7.12 or above preferred)
+	- :term:`Python` 2.7.12 or above (Python 3.* may also work, work is ongoing)
 	- :term:`Java` (1.6.0_31 or later).  Java is optional. It is required to use the :term:`Closure Compiler` (in order to minify your code).
 	- :term:`Git` client. Git is required if building tools from source.
 	- :term:`Fastcomp` (Emscripten's fork of LLVM and Clang)

site/source/docs/getting_started/downloads.rst

@@ -4,43 +4,28 @@
 Download and install
 ====================
 
-**Emscripten SDK provides the whole Emscripten toolchain in a single package, with integrated support for** :ref:`updating to newer SDKs <updating-the-emscripten-sdk>` **as they are released.**
-
 .. tip:: If you are :ref:`contributing <contributing>` to Emscripten you should :ref:`build Emscripten from source <installing-from-source>`.
 
-
-SDK Downloads
-=============
-
-Download one of the SDK installers below to get started with Emscripten development.
-
-.. emscripten-sdk-windows-installers:
-
-Windows
--------
-
-- `64-bit Emscripten SDK for Windows <https://s3.amazonaws.com/mozilla-games/emscripten/releases/emsdk-portable-64bit.zip>`_ (emsdk-portable-64bit.zip)
-		A zipped package of the SDK that does not require system installation privileges. Follow the instructions below to :ref:`install Emscripten SDK on Windows <sdk-installation-instructions>`.
-
-Linux and Mac OS X
-------------------
-
-.. _emscripten-sdk-linux-osx:
-	
-- `Emscripten SDK for Linux and OS X <https://s3.amazonaws.com/mozilla-games/emscripten/releases/emsdk-portable.tar.gz>`_ (emsdk-portable.tar.gz) 
-		A tar.gz archive package of the SDK that does not require system installation privileges. To install, follow the :ref:`platform-specific notes <platform-notes-installation_instructions-SDK>` and the :ref:`general instructions <sdk-installation-instructions>`.
-
 .. _sdk-installation-instructions:
 
 Installation instructions
 =========================
 
 First check the :ref:`Platform-specific notes <platform-notes-installation_instructions-SDK>` below and install any prerequisites.
 
-Install or update the SDK using the following steps:
+The core Emscripten SDK (emsdk) driver is a Python script. You can get it for the first time with
+
+  ::
+
+    # Get the emsdk repo
+    git clone https://github.com/juj/emsdk.git
+
+    # Enter that directory
+    cd emsdk
+
+.. note:: You can also get the emsdk without git, by selecting "Clone or download => Download ZIP" on the `emsdk GitHub page <https://github.com/juj/emsdk>`_.
 
-1. Download and unzip the SDK package to a directory of your choice. This directory will contain the Emscripten SDK.
-#. Open a command prompt inside the SDK directory and run the following :ref:`emsdk <emsdk>` commands to get the latest tools from Github and set them as :term:`active <Active Tool/SDK>`:
+Run the following :ref:`emsdk <emsdk>` commands to get the latest tools from GitHub and set them as :term:`active <Active Tool/SDK>`:
 
 	::
 
@@ -65,9 +50,18 @@ If you change the location of the SDK (e.g. take it to another computer on an US
 Platform-specific notes
 ----------------------------
 
+Windows
++++++++
+
+#. Install Python 2.7.12 or newer (older versions may not work due to `a GitHub change with SSL <https://github.com/kripken/emscripten/issues/6275>`_).
+
+	.. note:: Instead of running emscripten on Windows directly, you can use the Windows Subsystem for Linux to run it in a Linux environment.
+
 Mac OS X
 ++++++++
 
+If you use MacOS 10.13.3 or later then you should have a new enough version of Python installed (older versions may not work due to `a GitHub change with SSL <https://github.com/kripken/emscripten/issues/6275>`_). Otherwise you can manually install and use Python 2.7.12 or newer.
+
 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.
 
 #. Install the *XCode Command Line Tools*. These are a precondition for *git*.
@@ -94,20 +88,7 @@ Linux
 
 .. note:: *Emsdk* does not install any tools to the system, or otherwise interact with Linux package managers. All file changes are done inside the **emsdk/** directory.
 
-- The system must have a working :ref:`compiler-toolchain` (because *emsdk* builds software from the source): 
-
-	::	
-	
-		#Update the package lists
-		sudo apt-get update
-		
-		# Install *gcc* (and related dependencies)
-		sudo apt-get install build-essential
-		
-		# Install cmake
-		sudo apt-get install cmake
-		
-- *Python*, *node.js* or *Java* are not provided by *emsdk*. The user is expected to install these beforehand with the *system package manager*:
+- *Python*, *node.js*, *CMake*, and *Java* are not provided by *emsdk*. The user is expected to install these beforehand with the *system package manager*:
 
 	::
 	
@@ -116,10 +97,15 @@ Linux
 		
 		# Install node.js
 		sudo apt-get install nodejs
+
+		# Install CMake (optional, only needed for tests and building Binaryen)
+		sudo apt-get install cmake
 		
 		# Install Java (optional, only needed for Closure Compiler minification)
 		sudo apt-get install default-jre
 
+.. note:: You need Python 2.7.12 or newer because older versions may not work due to `a GitHub change with SSL <https://github.com/kripken/emscripten/issues/6275>`_).
+
 .. note:: Your system may provide Node.js as ``node`` instead of ``nodejs``. In that case, you may need to also update the ``NODE_JS`` attribute of your ``~/.emscripten`` file.
 
 - *Git* is not installed automatically. Git is only needed if you want to use tools from one of the development branches **emscripten-incoming** or **emscripten-master**: 
@@ -161,7 +147,7 @@ Type the following in a command prompt ::
 	# Activate PATH and other environment variables in the current terminal
 	source ./emsdk_env.sh
 
-The package manager can do many other maintenance tasks ranging from fetching specific old versions of the SDK through to using the :ref:`versions of the tools on Github <emsdk-master-or-incoming-sdk>` (or even your own fork). Check out all the possibilities in the :ref:`emsdk_howto`.
+The package manager can do many other maintenance tasks ranging from fetching specific old versions of the SDK through to using the :ref:`versions of the tools on GitHub <emsdk-master-or-incoming-sdk>` (or even your own fork). Check out all the possibilities in the :ref:`emsdk_howto`.
 
 .. _downloads-uninstall-the-sdk: