Update installation instructions (ponylang#3436)

BUILD.md

@@ -0,0 +1,127 @@
+# Building ponyc from source
+
+First of all, you need a compiler with decent C11 support. The following compilers are supported, though we recommend to use the most recent versions.
+
+- GCC >= 4.7
+- Clang >= 3.4
+- MSVC >= 2015
+- XCode Clang >= 6.0
+
+## FreeBSD
+
+```bash
+pkg install -y cmake gmake libunwind git
+make -f Makefile-lib-llvm
+sudo make -f Makefile-lib-llvm install
+```
+
+## Linux
+
+```bash
+make -f Makefile-lib-llvm
+sudo make -f Makefile-lib-llvm install
+```
+
+Additional Requirements:
+
+Distribution | Requires
+--- | ---
+alpine | cmake, g++, make, libexecinfo
+ubuntu | cmake, g++, make
+
+## macOS
+
+```bash
+make -f Makefile-lib-llvm
+sudo make -f Makefile-lib-llvm install
+```
+
+## Windows
+
+Building on Windows requires the following:
+
+- Visual Studio 2019, 2017 or 2015 (available [here](https://www.visualstudio.com/vs/community/)) or the Visual C++ Build Tools 2019, 2017 or 2015 (available [here](https://visualstudio.microsoft.com/visual-cpp-build-tools/)), and
+  - If using Visual Studio 2015, install the Windows 10 SDK (available [here](https://developer.microsoft.com/en-us/windows/downloads/windows-10-sdk)).
+  - If using Visual Studio 2017 or 2019, install the "Desktop Development with C++" workload.
+  - If using Visual C++ Build Tools 2017 or 2019, install the "Visual C++ build tools" workload, and the "Visual Studio C++ core features" individual component.
+  - If using Visual Studio 2017 or 2019, or Visual C++ Build Tools 2017 or 2019, make sure the latest `Windows 10 SDK (10.x.x.x) for Desktop` will be installed.
+- [Python](https://www.python.org/downloads) (3.6 or 2.7) needs to be in your PATH.
+
+In a command prompt in the `ponyc` source directory, run the following:
+
+```
+make.bat configure
+```
+
+(You only need to run `make.bat configure` the first time you build the project.)
+
+```
+make.bat build test
+```
+
+This will automatically perform the following steps:
+
+- Download the pre-built LLVM library for building the Pony compiler.
+  - [LLVM](http://llvm.org)
+- Build the pony compiler in the `build/<config>-<llvm-version>` directory.
+- Build the unit tests for the compiler and the standard library.
+- Run the unit tests.
+
+You can provide the following options to `make.bat` when running the `build` or `test` commands:
+
+- `--config debug|release`: whether or not to build a debug or release build (`release` is the default).
+- `--llvm <version>`: the LLVM version to build against (`3.9.1` is the default).
+
+Note that you need to provide these options each time you run make.bat; the system will not remember your last choice.
+
+Other commands include `clean`, which will clean a specified configuration; and `distclean`, which will wipe out the entire build directory.  You will need to run `make configure` after a distclean.
+
+----
+
+# Additional Build options
+
+## arch
+
+You can specify the CPU architecture to build Pony for via the `arch` make option:
+
+```bash
+make arch=arm7
+```
+
+## lto
+
+Link-time optimizations provide a performance improvement. You should strongly consider turning on LTO if you build ponyc from source. It's off by default as it comes with some caveats:
+
+- If you aren't using clang as your linker, we've seen LTO generate incorrect binaries. It's rare but it can happen. Before turning on LTO you need to be aware that it's possible.
+
+- If you are on MacOS, turning on LTO means that if you upgrade your version of XCode, you will have to rebuild your Pony compiler. You won't be able to link Pony programs if there is a mismatch between the version of XCode used to build the Pony runtime and the version of XCode you currently have installed.
+
+You can enable LTO when building the compiler in release mode. There are slight differences between platforms so you'll need to do a manual setup. LTO is enabled by setting `lto` to `yes` in the build command line like:
+
+```bash
+make lto=yes
+```
+
+If the build fails, you have to specify the LTO plugin for your compiler in the `LTO_PLUGIN` variable. For example:
+
+```bash
+make LTO_PLUGIN=/usr/lib/LLVMgold.so
+```
+
+Refer to your compiler documentation for the plugin to use in your case.
+
+## runtime-bitcode
+
+If you're compiling with Clang, you can build the Pony runtime as an LLVM bitcode file by setting `runtime-bitcode` to `yes` in the build command line:
+
+```bash
+make runtime-bitcode=yes
+```
+
+Then, you can pass the `--runtimebc` option to ponyc in order to use the bitcode file instead of the static library to link in the runtime:
+
+```bash
+ponyc --runtimebc
+```
+
+This functionality boils down to "super LTO" for the runtime. The Pony compiler will have full knowledge of the runtime and will perform advanced interprocedural optimisations between your Pony code and the runtime. If you're looking for maximum performance, you should consider this option. Note that this can result in very long optimisation times.

INSTALL.md

@@ -0,0 +1,43 @@
+# Installing Pony
+
+Prebuilt Pony binaries are available on a number of platforms. They are built using a very generic CPU instruction set and as such, will not provide maximum performance. If you need to get the best performance possible from your Pony program, we strongly recommend [building from source](BUILD.md).
+
+## Linux
+
+Prebuilt Linux packages are available via [ponyup](https://github.com/ponylang/ponyup) for Glibc and musl libc based Linux distribution. You can install nightly builds as well as official releases using ponyup.
+
+To install the most recent ponyc on a Glibc distribution (for example, Debian, Ubuntu, and most distros):
+
+```bash
+ponyup update ponyc release
+```
+
+Additional requirements:
+
+All ponyc Linux installations need a C compiler such as gcc or clang installed. The following distributions have additional requirements:
+
+Distribution | Requires
+--- | ---
+alpine | libexecinfo
+fedora | libatomic
+
+## macOS
+
+Pony can be installed as a Homebrew package.
+
+```bash
+brew update
+brew install ponyc
+```
+
+## Windows
+
+Windows users will need to install:
+
+- Visual Studio 2019, 2017 or 2015 (available [here](https://www.visualstudio.com/vs/community/)) or the Visual C++ Build Tools 2019, 2017 or 2015 (available [here](https://visualstudio.microsoft.com/visual-cpp-build-tools/)), and
+  - If using Visual Studio 2015, install the Windows 10 SDK (available [here](https://developer.microsoft.com/en-us/windows/downloads/windows-10-sdk)).
+  - If using Visual Studio 2017 or 2019, install the "Desktop Development with C++" workload.
+  - If using Visual C++ Build Tools 2017 or 2019, install the "Visual C++ build tools" workload, and the "Visual Studio C++ core features" individual component.
+  - If using Visual Studio 2017 or 2019, or Visual C++ Build Tools 2017 or 2019, make sure the latest `Windows 10 SDK (10.x.x.x) for Desktop` will be installed.
+
+Once you have installed the prerequisites, you can download the latest ponyc release from [bintray](https://dl.bintray.com/pony-language/ponyc-win/).

INSTALL_DOCKER.md

@@ -0,0 +1,73 @@
+# Docker
+
+Docker based Pony environments are available. The following tags are available:
+
+- latest (most recent build of the `master` branch)
+- release (most recent release)
+- x.y.z (tagged release e.g. 0.33.1)
+
+If you prefer to use the Alpine images, you can use the following tags:
+
+- alpine (most recent build of the `master` branch)
+- release-alpine (most recent release)
+- x.y.z-alpine (tagged release e.g. 0.33.1)
+
+The docker images also include common Pony tools like [ponyup](https://github.com/ponylang/ponyup), [corral](https://github.com/ponylang/corral), and [changelog-tool](https://github.com/ponylang/changelog-tool).
+
+## Using Pony from Docker
+
+You'll need to install Docker using [the instructions here](https://docs.docker.com/engine/installation/). Then you can pull a pony docker image using the following command (where TAG is the tag you want to use)
+
+```bash
+docker pull ponylang/ponyc:TAG
+```
+
+Then you'll be able to run `ponyc` to compile a Pony program in a given directory, running a command like this:
+
+```bash
+docker run -v /path/to/my-code:/src/main ponylang/ponyc:TAG
+```
+
+If you're unfamiliar with Docker, remember to ensure that whatever path you provide for `/path/to/my-code` is a full path name and not a relative path, and also note the lack of a closing slash, `/`, at the *end* of the path name.
+
+Note that if your host doesn't match the docker container, you'll probably have to run the resulting program inside the docker container as well, using a command like this:
+
+```bash
+docker run -v /path/to/my-code:/src/main ponylang/ponyc:TAG ./main
+```
+
+To compile and run in one step run a command like this:
+
+```
+docker run -v /path/to/my-code:/src/main ponylang/ponyc:TAG sh -c "ponyc && ./main"
+```
+
+### Docker for Windows
+
+Pull an image as above:
+
+```bash
+docker pull ponylang/ponyc:TAG
+```
+
+Share a local drive (volume), such as `c:`, with Docker for Windows, so that they are available to your containers. (Refer to [shared drives](https://docs.docker.com/docker-for-windows/#shared-drives) in the Docker for Windows documentation for details.)
+
+Then you'll be able to run `ponyc` to compile a Pony program in a given directory, running a command like this:
+
+```bash
+docker run -v c:/path/to/my-code:/src/main ponylang/ponyc:TAG
+```
+
+Note the inserted drive letter. Replace with your drive letter as appropriate.
+
+To run a program, run a command like this:
+
+```bash
+docker run -v c:/path/to/my-code:/src/main ponylang/ponyc:TAG ./main
+```
+
+To compile and run in one step run a command like this:
+
+```bash
+docker run -v c:/path/to/my-code:/src/main ponylang/ponyc:TAG sh -c "ponyc && ./main"
+```