Simplify instructions, add CI badge
authorAndrey Mokhov <andrey.mokhov@gmail.com>
Thu, 1 Sep 2016 22:20:05 +0000 (23:20 +0100)
committerGitHub <noreply@github.com>
Thu, 1 Sep 2016 22:20:05 +0000 (23:20 +0100)
[skip ci]

doc/windows.md

index a70f85a..efbaeb2 100644 (file)
@@ -1,23 +1,60 @@
-# Building on Windows\r
+# Building GHC on Windows\r
 \r
-Here are a list of instructions to build GHC, from source, on Windows. I tested these instructions on a clean machine using the [free Windows 10 VirtualBox image](https://dev.windows.com/en-us/microsoft-edge/tools/vms/windows/) (I bumped the VM CPUs to 4, and RAM to 4096Mb). These instructions are not currently the official GHC building instructions, but might be simpler and more robust than those.\r
+[![Windows status](https://img.shields.io/appveyor/ci/snowleopard/hadrian/master.svg?label=Windows)](https://ci.appveyor.com/project/snowleopard/hadrian)\r
 \r
-The first step is to [install Stack](https://www.stackage.org/stack/windows-x86_64-installer) (I just accepted all the defaults), then open a command prompt and run:\r
+Here is how you can build GHC, from source, on Windows. We assume that you\r
+already have `git` and `stack` installed.\r
 \r
-       stack setup\r
-       stack install happy alex\r
-       stack exec -- pacman -S gcc binutils git automake-wrapper tar make patch autoconf --noconfirm\r
-       stack exec -- git clone --recursive git://git.haskell.org/ghc.git\r
-       cd ghc\r
-       stack exec -- git clone git://github.com/snowleopard/hadrian\r
-       stack build --stack-yaml=hadrian/stack.yaml --only-dependencies\r
-       stack exec --stack-yaml=hadrian/stack.yaml -- hadrian/build.bat -j --flavour=quickest\r
+```sh\r
+# Get GHC and Hadrian sources\r
+git clone --recursive git://git.haskell.org/ghc.git\r
+cd ghc\r
+git clone git://github.com/snowleopard/hadrian\r
+cd hadrian\r
 \r
-The entire process should take about 20 minutes. Note, this will build GHC without optimisations. If you need an optimised GHC, drop the `--flavour=quickest` flag from the last command line (this will slow down the build to about an hour).\r
+# Download and install the bootstrapping GHC and MSYS2\r
+stack setup\r
 \r
-#### Future ideas\r
+# Install utilities required during the GHC build process\r
+stack exec -- pacman -S autoconf automake-wrapper make patch tar --noconfirm\r
 \r
-Here are some alternatives that have been considered, but not yet tested. Use the instructions above.\r
+# Build Hadrian and dependencies (including GHC dependencies Alex and Happy)\r
+stack build\r
+\r
+# Build GHC\r
+stack exec hadrian -- --directory ".." -j --flavour=quickest\r
+\r
+# Test GHC\r
+cd ..\r
+inplace\bin\ghc-stage2 -e 1+2\r
+```    \r
+\r
+The entire process should take about 20 minutes. Note, this will build GHC without\r
+optimisations. If you need an optimised GHC, drop the `--flavour=quickest` flag from\r
+the build command line (this will slow down the build to about an hour).\r
+\r
+These are currently not the\r
+[official GHC building instructions](https://ghc.haskell.org/trac/ghc/wiki/Building/Preparation/Windows),\r
+but are much simpler and may also be more robust.\r
+\r
+The `stack build` and `stack exec hadrian` commands can be replaced by an invocation\r
+of Hadrian's Stack-based build script: `build.stack.bat -j --flavour=quickest`. Use this\r
+script if you plan to work on Hadrian and/or rebuild GHC often.\r
+\r
+## Prerequisites\r
+\r
+The above works on a clean machine with `git` and `stack` installed (tested with default\r
+installation settings), which you can get from https://git-scm.com/download/win and\r
+https://www.stackage.org/stack/windows-x86_64-installer. \r
+\r
+## Testing\r
+\r
+These instructions have been tested on a clean Windows 10 machine using the\r
+[free VirtualBox image](https://dev.windows.com/en-us/microsoft-edge/tools/vms/windows/),\r
+and are also routinely tested on\r
+[Hadrian's AppVeyor CI instance](https://ci.appveyor.com/project/snowleopard/hadrian/history). \r
+\r
+## Notes\r
+\r
+Beware of the [current limitations of Hadrian](https://github.com/snowleopard/hadrian#current-limitations).\r
 \r
-* The `pacman` install of `gcc` is probably not necessary, but it does pull in a lot of tools, some of which probably are necessary. Ideally thin the list down.\r
-* Happy/Alex should be able to be installed by adding them as `build-tools` in the Cabal file.\r