psol: support a binary distribution

We want people to be able to install ngx_pagespeed like any other nginx module.
If PSOL were a full-fledged library with a stable interface we could simply say
"install PSOL" which might be as easy as `apt-get install psol-dev`, but it's
not.  Instead we directly include a precompiled binary library along with its
headers.  By building the binaries on something sufficiently old (Centos 5.4)
they should work pretty much everywhere someone might think to run
ngx_pagespeed, but building from source is still a documented option if they
don't.

Headers and binaries are from trunk of r2338, as documented in the READMEs.

README.md

@@ -31,6 +31,24 @@ content or workflow. Features include:
 Because nginx does not support dynamic loading of modules, you need to add
 ngx_pagespeed as a build-time dependency.
 
+### Simple method: Using a binary Pagespeed Optimization Library
+
+Check out ngx_pagespeed:
+
+    $ cd ~
+    $ git clone https://github.com/pagespeed/ngx_pagespeed.git
+
+Download and build nginx:
+
+    $ # check http://nginx.org/en/download.html for the latest version
+    $ wget http://nginx.org/download/nginx-1.2.6.tar.gz
+    $ tar -xvzf nginx-1.2.6.tar.gz
+    $ cd nginx-1.2.6/src/
+    $ ./configure --add-module=$HOME/ngx_pagespeed
+    $ make install
+
+### Complex method: Building the Pagespeed Optimization Library from source
+
 First build mod_pagespeed against the current revision we work at:
 
     $ mkdir ~/mod_pagespeed
@@ -60,13 +78,11 @@ Download and build nginx:
     $ wget http://nginx.org/download/nginx-1.2.6.tar.gz
     $ tar -xvzf nginx-1.2.6.tar.gz
     $ cd nginx-1.2.6/src/
-    $ ./configure --with-debug --add-module=$HOME/ngx_pagespeed
+    $ MOD_PAGESPEED_DIR="$HOME/mod_pagespeed/src" ./configure --with-debug --add-module=$HOME/ngx_pagespeed
     $ make install
 
-(This assumes you put everything in your home directory; if not, change paths
-appropriately.  The only restriction is that the `mod_pagespeed` and
-`ngx_pagespeed` directories need to have the same parent so that ngx_pagespeed
-can find the pagespeed optimization library.)
+This assumes you put everything in your home directory; if not, change paths
+appropriately.
 
 ## How to use
 
@@ -225,3 +241,40 @@ adjustment: replace '"ModPagespeed"' with '"pagespeed "':
       pagespeed RunExperiment on;
       pagespeed ExperimentSpec "id=3;percent=50;default";
       pagespeed ExperimentSpec "id=4;percent=50";
+
+## Preparing the binary distribution
+
+If you just want to run ngx_pagespeed you don't need this.  This is
+documentation on how the `psol/` directory was created and is maintained.
+
+We redistribute precompiled libraries and the accompanying headers for the
+pagespeed optimization library and its dependencies.  To update the headers,
+run:
+
+    $ cd ngx_pagespeed/
+    $ scripts/copy_includes.sh /path/to/mod_pagespeed/src
+
+This will delete `psol/include/` and recreate it from `mod_pagespeed/src` by
+copying over all the headers and a few selected source files.  The commit diff
+should only be the changes, but it can be huge.
+
+To update the binaries, create a virtual machine running an old version of
+Linux.  The current binaries were created on two CentOS 5.4 virtual machines,
+32-bit and 64-bit.  Because the binaries will usually work on systems that are
+more recent, it's important not to do this on your development machine.
+Building the binaries meant building mod_pagespeed and pagespeed_automatic from
+source, in separate directories with `BUILDTYPE=Release` on and off, and then
+copying the resulting binaries over to `psol/lib/`:
+
+    $ for buildtype in Debug Release ; do
+        for arch in ia32 x64 ; do
+          for library in
+            net/instaweb/automatic/pagespeed_automatic.a
+            out/Debug/obj.target/third_party/aprutil/libaprutil.a
+            out/Debug/obj.target/third_party/apr/libapr.a
+            out/Debug/obj.target/third_party/serf/libserf.a ; do
+              scp machine-${arch}:mod_pagespeed_${buildtype}/src/${library}
+                  psol/lib/${buildtype}/linux/${arch}/
+          done
+        done
+      done