Build mod_pagespeed From Source

Note: If you're using CentOS, Fedora, RHEL, Debian, Ubuntu, or any other Linux distribution that uses RPM or DEB packages, we recommend that you install mod_pagespeed from binary packages.

The build has been tested on Ubuntu Lucid and CentOS 5.4. It should work elsewhere; if you try it somewhere new, please send a note to our discussion group with your success or failure.

Prerequisites

We require Apache (>= 2.2), Python (>= 2.7), g++ (>= 4.1), svn (>= 1.8), git (>= 1.8), gperf, and make. To install these on Debian or Ubuntu run:

  sudo apt-get install apache2 g++ python subversion gperf make devscripts fakeroot git curl zlib1g-dev uuid-dev

On CentOS, run:

  sudo yum install httpd gcc-c++ python subversion gperf make rpm-build git curl zlib-devel libuuid-devel

CentOS 5 does not include git in its repositories. If you are running CentOS 5 or another operating system with a version of git older than 1.8, to install git 1.8 or higher, you must build it from source.

sudo yum install curl-devel expat-devel gettext-devel openssl-devel zlib-devel perl-devel
wget https://www.kernel.org/pub/software/scm/git/git-2.0.4.tar.gz
tar -xf git-2.0.4.tar.gz
cd git-2.0.4/
./configure
make
sudo make install

To build on CentOS 5, or on older versions of Debian or Ubuntu, you can install Python 2.7 from source.

  wget http://www.python.org/ftp/python/2.7/Python-2.7.tgz
  tar xzf Python-2.7.tgz
  cd Python-2.7
  ./configure --prefix=/usr/local
  make -j >make.log
  sudo make install

Install the Chromium Depot Tools

We require the Chromium depot_tools, which are used to build open-source projects with dependencies on other open-source projects. Download it with:

  mkdir -p ~/bin
  cd ~/bin
  git clone https://chromium.googlesource.com/chromium/tools/depot_tools.git --depth=1

You will need to add the depot_tools to your path. In bash you would run:

  export PATH=$PATH:~/bin/depot_tools

Check out mod_pagespeed and dependencies

For building version 1.12 and later:

  git clone -b latest-stable --recursive https://github.com/apache/incubator-pagespeed-mod.git --depth=1
  cd incubator-pagespeed-mod
  python build/gyp_chromium --depth=.
  make BUILDTYPE=Release mod_pagespeed_test pagespeed_automatic_test

For version 1.11.x and older, the build system is different:

You need to download the source code for mod_pagespeed and all of its dependenceies. The gclient command (which is one of the depot_tools) will do this for you.

  mkdir ~/mod_pagespeed    # Any directory is fine.
  cd ~/mod_pagespeed
  gclient config https://github.com/apache/incubator-pagespeed-mod.git --unmanaged --name=src
  git clone https://github.com/apache/incubator-pagespeed-mod.git src --depth=1
  cd src
  git checkout latest-stable
  cd ..
  gclient sync --force --jobs=1
  cd src
  make AR.host=`pwd`/build/wrappers/ar.sh AR.target=`pwd`/build/wrappers/ar.sh \
      BUILDTYPE=Release mod_pagespeed_test pagespeed_automatic_test

Build & Run Tests

To make sure mod_pagespeed will work on your system we provide some automated tests. To run the tests:

  ./out/Release/mod_pagespeed_test
  ./out/Release/pagespeed_automatic_test

To successfully pass the HTTPS fetching tests, you may need to first set environment variables to find the certificate files. On Ubuntu, the test binaries should have the correct paths by default. On CentOS, these settings should work:

  export SSL_CERT_DIR=/etc/pki/tls/certs
  export SSL_CERT_FILE=/etc/pki/tls/cert.pem

If you get any other errors while running tests, report a bug or write to our discussion group.

Compile

To compile mod_pagespeed, run the commands below. You should to omit the AR arguments for latest-beta.

  cd ~/mod_pagespeed/src
  make AR.host=`pwd`/build/wrappers/ar.sh AR.target=`pwd`/build/wrappers/ar.sh BUILDTYPE=Release

To see the actual g++ commands, you can add V=1 to the above command. If you ran the tests above, this step should complete quickly.

Install

For RPM/DEB platforms, you can use the packaging instructions in the Building Packages section below. For other platforms you can use the custom installer documented here:

  cd install

If you built and installed the Apache web server from source (as opposed to installing using a RPM/DEB package manager), you can use the install_apxs.sh script:

  ./install_apxs.sh

The script will infer the proper installation locations for your system, based on information gathered from the Apache apxs tool. These defaults can be overridden on the command line by specifying environment variables. See the contents of the install_apxs.sh script for specific details on these environment variables. If you installed Apache in a non-default location, you may need to tell the script where to find the apxs tool, like so:

  # Specify the path to your apxs binary
  APXS_BIN=/usr/local/exampleapache/bin/apxs ./install_apxs.sh

Alternatively, if you already know all of the installation details for your system, then you can run the Makefile with custom parameters for:

  APACHE_ROOT=/etc/httpd
  APACHE_MODULES=/etc/httpd/modules
  APACHE_CONTROL_PROGRAM=/etc/init.d/httpd
  APACHE_USER=www-data
  APACHE_DOC_ROOT=/var/www/html
  ... # see Makefile for more options

Run:

  make APACHE_ROOT=...  ... staging
  sudo make ... install  # Use make ... -n install to see the commands without
  executing
  sudo make ... stop start  # Restart your apache server

For the common configurations of Ubuntu and CentOS, we have included simple installer wrappers ubuntu.sh and centos.sh for your convenience. You can use these as examples to build scripts for your custom environment and then run them as:

  ./ubuntu.sh staging
  sudo ./ubuntu.sh install
  sudo ./ubuntu.sh stop start

Update

You can repeat the install process at any time to re-install mod_pagespeed and update it to the latest version.

To update to the latest version, first checkout the latest tag:

  git pull --tags  # pulls tags and all required commits
  git checkout latest-beta
  git cherry-pick 651a2503f81  # The gyp dependency moved after we released.

Then sync your client:

  gclient sync --force --jobs=1

Now you can re-build and install using the instructions above.

Build Packages

You can build RPM or DEB packages using the following commands:

  python build/gyp_chromium -Dchannel=beta
  make BUILDTYPE=Release AR.host=`pwd`/build/wrappers/ar.sh AR.target=`pwd`/build/wrappers/ar.sh linux_package_rpm

  python build/gyp_chromium -Dchannel=beta
  make BUILDTYPE=Release AR.host=`pwd`/build/wrappers/ar.sh AR.target=`pwd`/build/wrappers/ar.sh linux_package_deb

The resulting package file will be in the out/Release directory.

Note: These packages will only work if you installed Apache using RPM or DEB packages as well. Notably, if you installed Apache using cPanel, these packages will not work. Instead you must follow the installation instructions above. See also: FAQ: I installed Apache 2.2 using cPanel, and can't get mod_pagespeed to work when I install from the .deb or .rpm.

Standalone CSS Minification

The PageSpeed CSS minifier can be built as a stand-alone command-line program. To build it, in the same directory that you ran the other make commands above (~/mod_pagespeed/src in the example), run:

  make AR.host=`pwd`/build/wrappers/ar.sh AR.target=`pwd`/build/wrappers/ar.sh BUILDTYPE=Release css_minify_main

You can run it as:

  ./out/Release/css_minify_main FILENAME.css > FILENAME-MINIFIED.css

Previously we recommended using the standlone CSS minifier for locating CSS constructs that PageSpeed had difficulty handling, but as of 1.9.32.1 we recommend using the debug filter instead.

This will print the parsing errors encountered to stderr. css_minify_main also prints the minified CSS to stdout, but because we are interested only in finding parsing errors we redirect that to /dev/null.

Standalone JS Minification

A command-line JavaScript minifier is now installed when you install mod_pagespeed. This generates the same minified code as mod_pagespeed itself. It can be used as follows:

  pagespeed_js_minify myfile.js > myfile.min.js

The minifier can also be used to generate metadata for JavaScript library canonicalization, as described in the documentation for that filter.

Other Systems

An installation guide for for mod_pagespeed on Gentoo was contributed by nikola.derikonjic, and openSUSE packages are maintained by Robert Munteanu. If you know of any other resources, please let us know by writing to our discussion group.