Convert INSTALLING to markdown

README.md

@@ -39,9 +39,9 @@ To contribute to Pyston, you need to to sign the [Dropbox Contributor License Ag
 
 ### Getting started
 
-To get a full development environment for Pyston, you need pretty recent versions of various tools, since self-modifying code tends to be less well supported.  The docs/INSTALLING file contains information about what the tools are, how to get them, and how to install them; currently it can take up to an hour to get them all built on a quad-core machine.
+To get a full development environment for Pyston, you need pretty recent versions of various tools, since self-modifying code tends to be less well supported.  The docs/INSTALLING.md file contains information about what the tools are, how to get them, and how to install them; currently it can take up to an hour to get them all built on a quad-core machine.
 
-To simply build and run Pyston, a smaller set of dependencies is required; see docs/INSTALLING, but skip the "OPTIONAL DEPENDENCIES" section. Once all the dependencies are installed, you should be able to do
+To simply build and run Pyston, a smaller set of dependencies is required; see docs/INSTALLING.md, but skip the "OPTIONAL DEPENDENCIES" section. Once all the dependencies are installed, you should be able to do
 ```
 $ make check -j4
 ```

docs/INSTALLING → docs/INSTALLING.mb

-DEPENDENCIES:
+Pyston currently only supports installing from source; the following instructions have only been tested on Ubuntu, but should ideally work on a Mac as well.
 
-# Pyston expects to find all of its dependencies in ~/pyston_deps:
+Pyston expects to find all of its dependencies in ~/pyston_deps:
+```
 mkdir ~/pyston_deps
+```
 
-GCC (assuming 4.8.2):
+### Compiler for clang
+
+clang requires a fairly modern [host compiler](http://llvm.org/docs/GettingStarted.html#host-c-toolchain-both-compiler-and-standard-library), so typically you will have to install a new one.  The easiest thing to do is to just create a fresh build of GCC:
+
+```
 sudo apt-get install libgmp-dev libmpfr-dev libmpc-dev make build-essential libtool zip gcc-multilib autogen
 cd ~/pyston_deps
 wget 'http://www.netgull.com/gcc/releases/gcc-4.8.2/gcc-4.8.2.tar.bz2'
 tar xvf gcc-4.8.2.tar.bz2
 mkdir gcc-4.8.2-{build,install}
 cd gcc-4.8.2-build
-# Space-saving configuration:
+# Space- and time-saving configuration:
 ../gcc-4.8.2/configure --disable-bootstrap --enable-languages=c,c++ --prefix=$HOME/pyston_deps/gcc-4.8.2-install
 # full configuration:
 # ../gcc-4.8.2/configure --prefix=$HOME/pyston_deps/gcc-4.8.2-install
 make -j4
 make check
 make install
+```
+
+### ccache
 
-ccache:
+ccache is a build tool that can help speed up redundant compilations.  It's not strictly necessary; you can disable it by adding `ENABLE_CCACHE := 0` to your Makefile.local.  It's enabled by default, so to use it you can run 
+```
 sudo apt-get install ccache
-# Note: ccache is useful enough that it's enabled by default, but if you'd rather
-# not install it, you can add "ENABLE_CCACHE:=0" to your Makefile.local
+```
 
-curses, zlib:
+### LLVM dependencies
+```
 sudo apt-get install libncurses5-dev zlib1g-dev
+```
+
+### LLVM + clang
+
+LLVM and clang depend on a pretty modern compiler; the steps below assume yo uinstalled GCC 4.8.2 as described above.  It should be possible to build using clang >= 3.1, such as what you might find on a Mac, but that will require changes to the following setup that I haven't tested.
 
-LLVM: # note: requires gcc-4.7+, and pyston by default assumes you've installed gcc-4.8.2 as above)
+```
 cd ~/pyston_deps
 git clone http://llvm.org/git/llvm.git llvm-trunk
 git clone http://llvm.org/git/clang.git llvm-trunk/tools/clang
@@ -34,8 +49,13 @@ cd ~/pyston/src
 make llvm_up
 make llvm_configure
 make llvm -j4
+```
 
-libunwind:
+There seem to be some lingering build issues with LLVM that I haven't identified; if the last step fails with errors along the lines of "rm: could not find file foo.tmp", it is quite likely that simply running it again will have it continue successfully.  You may have to do this multiple times, unfortunately.
+
+### libunwind
+
+```
 cd ~/pyston_deps
 wget http://download.savannah.gnu.org/releases/libunwind/libunwind-1.1.tar.gz
 tar xvf libunwind-1.1.tar.gz
@@ -43,10 +63,17 @@ cd libunwind-1.1
 ./configure
 make -j4
 sudo make install
-# TODO would be nice to install this locally like the rest of the dependencies
+```
+
+TODO would be nice to install this locally like the rest of the dependencies
+
+### valgrind
 
-valgrind:
-# not sure exactly what version is required, but 3.7.0 doesn't seem quite good enough (can't handle 'tzcnt' instruction)
+valgrind is close to being an optional dependency, but since Pyston contains a custom memory allocator, it has some basic (and mostly-broken) valgrind hooks to let it know what memory is safe to access or not.  TODO it'd be nice to be able to turn that off by default.
+
+You may be able to install valgrind from your system package manager (`apt-get install valgrind`), but it is likely to be an old enough version that it doesn't support some newer instructions and may crash when running.  The safest thing to do is to do a full installation from source:
+
+```
 cd ~/pyston_deps
 wget http://valgrind.org/downloads/valgrind-3.9.0.tar.bz2
 tar xvf valgrind-3.9.0.tar.bz2
@@ -56,45 +83,72 @@ cd valgrind-3.9.0
 make -j4
 make install
 sudo apt-get install libc6-dbg
-# Add this line to Makefile.local:
+```
+
+Then, add this line to your Makefile.local:
+```
 VALGRIND := VALGRIND_LIB=$(HOME)/pyston_deps/valgrind-3.9.0-install/lib/valgrind $(HOME)/pyston_deps/valgrind-3.9.0-install/bin/valgrind
+```
 
-OPTIONAL DEPENDENCIES:
+# Optional dependencies
 
-distcc:
+### distcc
+```
 sudo apt-get install distcc distcc-pump
+```
 
-gtest:
+### gtest
+```
 cd ~/pyston_deps
 wget https://googletest.googlecode.com/files/gtest-1.7.0.zip
 unzip gtest-1.7.0.zip
 cd gtest-1.7.0
 ./configure
 make -j4
+```
 
-gdb:
+### gdb
+A new version of gdb can be highly useful since debugging a JIT tends to stress GDB:
+
+```
 cd ~/pyston_deps
 wget http://ftp.gnu.org/gnu/gdb/gdb-7.6.2.tar.gz
 tar xvf gdb-7.6.2.tar.gz
 cd gdb-7.6.2
 ./configure
 make -j4
-# then add this to Makefile.local:
+```
+
+Then add this to your Makefile.local:
+```
 GDB := $(HOME)/pyston_deps/gdb-7.6.2/gdb/gdb
+```
 
-gperftools (-lprofiler):
+### gperftools (-lprofiler)
+```
 download from http://code.google.com/p/gperftools/downloads/list
 standard ./configure, make, make install
+```
 
-gold, if not installed (instructions mostly from http://llvm.org/docs/GoldPlugin.html):
+### gold
+
+gold is highly recommended as a faster linker.  Pyston contains build-system support for automatically using gold if available.  gold may already be installed on your system; you can check by typing `which gold`.
+
+```
 cd ~/pyston_deps
 git clone --depth 1 git://sourceware.org/git/binutils-gdb.git binutils
 mkdir binutils-build
 cd binutils-build
 ../binutils/configure --enable-gold --enable-plugins --disable-werror
 make all-gold
+```
 
-perf:
+### perf
+The `perf` tool is the best way we've found to profile JIT'd code; you can find more details in docs/PROFILING.
+
+```
 sudo apt-get install linux-tools
 sudo apt-get install linux-tools-`uname -r`
 # may need to strip off the -generic from that last one
+```
+