Merge pull request travitch#44 from bchurchill/master

Update tutorial.  I suppose I should not look a gift horse in the mouth.

Author: ianamason

README.md

@@ -31,6 +31,11 @@ of a build process requires that.
 
 WLLVM works with either clang or the gcc dragonegg plugin.
 
+Tutorial
+====
+
+See the tutorial markdown files for detailed instructions on how to compile apache with wllvm on Ubuntu.
+
 Usage
 =====
 

tutorial-ubuntu-16.04.md

@@ -0,0 +1,108 @@
+# Compiling Apache on Ubuntu
+
+
+On a clean 16.04 server machine I will build apache.  Desktop instructions should be no different.
+
+```
+>pwd
+
+/home/me/
+
+>more /etc/lsb-release
+
+DISTRIB_ID=Ubuntu
+DISTRIB_RELEASE=16.04
+DISTRIB_CODENAME=xenial
+DISTRIB_DESCRIPTION="Ubuntu 16.04 LTS"
+```
+
+
+## Step 0.
+
+Checkout the wllvm repository
+
+```
+>git clone https://github.com/SRI-CSL/whole-program-llvm.git
+```
+
+## Step 1.
+
+Set up the environment 
+
+```
+>export WLLVM_HOME=/home/me/whole-program-llvm
+
+>export PATH=${WLLVM_HOME}:${PATH}
+
+>which wllvm
+
+/home/me/whole-program-llvm/wllvm
+```
+
+## Step 2.
+
+I am only going to build apache, not apr, so I first install the prerequisites.
+
+```
+>sudo apt-get update
+
+>sudo apt-get install llvm clang libapr1-dev libaprutil1-dev libpcre3-dev gcc make
+
+```
+
+At this point, you should check your clang version with `which clang` and `ls -l /usr/bin/clang`.  It should be clang-3.8.
+
+## Step 3.
+
+  Configure the wllvm tool to use clang and be relatively quiet:
+
+```
+>export LLVM_COMPILER=clang
+
+>export WLLVM_OUTPUT=WARNING
+```
+
+## Step 4.
+
+ Fetch apache, untar, configure, then build:
+
+```
+>cd && pwd
+
+/home/me
+
+>wget http://apache.mirrors.pair.com/httpd/httpd-2.4.23.tar.gz
+
+>tar xfz httpd-2.4.12.tar.gz
+
+>cd httpd-2.4.23
+
+>CC=wllvm ./configure
+
+>make
+```
+
+## Step 5.
+
+Extract the bitcode.
+
+```
+>extract-bc -l llvm-link-3.8 httpd
+
+>ls -la httpd.bc
+-rw-r--r-- 1 vagrant vagrant 829960 Jun  1  2015 httpd.bc
+```
+
+The extra command line argument to `extract-bc` is because `apt`
+installs `llvm-link` as `llvm-link-3.8` so we need to tell `extract-bc`
+to use that one.
+
+## Step 6.  
+
+Turn the bitcode into a second executable binary. (optional -- just for fun and sanity checking)
+
+```
+llgc httpd.bc -o httpd.s
+as httpd.s -o httpd.o
+gcc httpd.o -lpthread -lapr-1 -laprutil-1 -lpcre -o httpd.new
+```