Perforce Public Knowledge Base - Installing Perforce Chronicle Under Mac OSX
Reset Search



Installing Perforce Chronicle Under Mac OSX

« Go Back



How to install Perforce Chronicle under Mac OS X.



Currently Perforce Chronicle is supported under Max OS X 10.6 (Snow Leopard) or later. Snow Leopard has all the components required (Apache 2.2 and PHP 5.3) installed by default. For more information, please see the file INSTALL.txt that comes with the Chronicle release package. Tip

Installing Chronicle requires the use of the terminal program. To correct command line typos or change the cursor position in text editors (such as vi), click the mouse cursor in the terminal window while holding the "option" key down. The cursor will be positioned where you clicked.

Installing Chronicle

  1. Download the release archive (p4chronicle.tgz) from the Perforce Chronicle Website.
  2. Using the Finder, double click the archive. The Mac OS X Archive Utility will decompress and untar the file.
  3. Rename the extracted folder to "p4chronicle". This will simplify setup in later steps.
  4. Move the resulting directory to the path:
  5. Make the data directory writable by the web server:
    sudo chown _www:_www /Library/WebServer/Documents/p4chronicle/data
    Note the understore before "www".
  6. Open the Apache configuration file:
    sudo vi /etc/apache2/httpd.conf
  7. Uncomment the line:
    LoadModule php5_module        libexec/apache2/
  8. Uncomment the line:
    Include /private/etc/apache2/extra/httpd-vhosts.conf
  9. Save the httpd.conf file and exit the editor.
  10. Open the Apache virtual hosts configuration file for edit:
    sudo vi /etc/apache2/extra/httpd-vhosts.conf
  11. Create a vhost (virtual host) entry in the file. This example assumes a host of "p4chronicle":
    NameVirtualHost *:80
    <VirtualHost *:80>
       DocumentRoot "/Library/WebServer/Documents/p4chronicle/"
       ErrorLog "/private/var/log/apache2/p4chronicle.err"
       CustomLog "/private/var/log/apache2/p4chronicle.log" common
    <Directory /Library/WebServer/Documents/p4chronicle/>
        AllowOverride All
        Allow From All

    ... where is the fully qualified domain name (FQDN) of your Chronicle-backed site.
  12. Save the httpd-vhosts.conf file and exit the editor.
  13. Restart Apache:
    sudo apachectl restart
  14. (Optional) If is not registered in your DNS, do the following to make it resolvable on your desktop:
    1. Open the hosts file for editing:
      sudo vi /etc/hosts
    2. Change the line:	localhost
      To the value:	localhost
  15. Save the hosts file and exit the editor.

Testing the Chronicle Installation

To confirm that Chronicle has been installed correctly, open a supported web browser and go to the URL:

Note: Some web proxies and systems may not honor the "p4chronicle" host name, and attempts to resolve to a DNS server. In that case, try connecting using the hosts IP address. For example:

Once connected you should see the Chronicle start page. Click the "Start Setup" button to check the "Setup Requirements" page.

Optional install


Chronicle comes with the P4PHP scripting API to give better performance when interacting with the backend Perforce server. It can be activated using the following steps:

  1. Create a php.ini using the defaults as a template:
    sudo cp /etc/php.ini.default /etc/php.ini
    sudo chmod 644 /etc/php.ini
  2. Open the file using a text editor such as vi:
    sudo vi /etc/php.ini
  3. Add the following line to the php.ini file:

Alternative PHP Cache (APC)

APC (Alternative PHP Cache) is an optional PHP package that improves Chronicle performance. When it isn't present Chronicle will suggest running the command:
pecl install APC

However Mac OS X 10.6 does not contain all of the dependencies required for this command to work. While MacPorts does have a pre-compiled package for PHP (php5-apc) it does not currently work with Chronicle.

You can install APC by doing one of the following:

  1. Install an Apache and PHP bundle that comes with APC. For example, MAMP.
  2. Compile and APC on your own (see below).


Compiling and Installing APC Manually

Note: Apple's Developer Tools (XCode) must be installed for the following steps to work. You can download the Apple Developer Tools free of charge from Apple.
  1. Create a work directory to use to compile the needed packages:
    mkdir -p /sourcecache
  2. Change to that directory:
    cd /sourcecache
  3. To compile APC the PCRE (Perl Compatible Regular Expressions) library source needs to be downloaded and compiled:
    curl -O

    Note: If you are behind a web proxy you will need to use the "-x" flag to pass the proxy information to the curl utility. For example, for a web proxy which does not require authentication:
    curl -O -x

    If you need to supply a user name and password to your web proxy:
    curl -O -x
  4. Decompress the PCRE archive:
    tar xzf pcre-8.11.tar.gz
  5. Switch to the PCRE directory:
    cd /sourcecache/pcre-8.11
  6. Run make to compile the PCRE source:
    sudo make
  7. To install the PCRE library, enter the command:
    sudo make install
  8. To compile APC, switch back to the sourcecache directory:
    cd /sourcecache
  9. Download the APC source code:
    curl -O
  10. Decompress the APC archive:
    tar xzf APC
  11. Switch to the APC directory:
    cd /sourcecache/APC-3.1.7
  12. Prepare the source files for PHP:
    sudo phpize
  13. Set the compiler flags for a Mac OS X 10.6 (Snow Leopard) 64-bit Intel system:
    MACOSX_DEPLOYMENT_TARGET=10.6 CFLAGS="-arch x86_64 -g -Os -pipe -no-cpp-precomp" CCFLAGS="-arch x86_64 -g -Os -pipe" CXXFLAGS="-arch x86_64 -g -Os -pipe" LDFLAGS="-arch x86_64 -bind_at_load" ./configure
  14. Run make to compile the APC source:
    sudo make
  15. To install APC, enter the command:
    sudo make install
  16. Once completed, open php.ini for edit:
    sudo vi /etc/php.ini
  17. Add this line to php.ini:
  18. Restart apache to load the new extension:
    sudo apachectl graceful

Reloading the Setup Requirements page for Chronicle should remove the "APC not installed" warning.




Apache Restarts with ULIMIT Error

If starting Apache produces an error similar to:


ulimit: open files: cannot modify limit


  1. Edit the apachectl file:
    sudo vi /usr/sbin/apachectl
  2. Change the line:
    ULIMIT_MAX_FILES="ulimit -S -n `ulimit -H -n`"
    To this value:
  3. Save the file and run:
    sudo apachectl restart


PHP Not at Version 5.3 or Higher

Confirm installed PHP version by running the following command in the terminal:
php -v
You should see output similar to:
PHP 5.3.1 (cli) (built: Apr  8 2010 14:09:29) 
Copyright (c) 1997-2009 The PHP Group
Zend Engine v2.3.0, Copyright (c) 1998-2009 Zend Technologies

Mac OS X 10.6 (Snow Leopard) and higher comes with PHP 5.3 as a default, so this error indicates that you are using Mac OS X 10.5 (Leopard) or below. Use MacPorts to upgrade to PHP 5.3.

The MacPorts project (formerly DarwinPorts) is an ongoing effort to port major Unix packages to Mac OS X. MacPorts can be used to install PHP 5.3 (a requirement) for Leopard using the MacPorts Leopard installer. While not a supported configuration currently, the command line to install PHP is:
sudo port install php5

Enter your password when prompted. PHP 5.3 (and any dependencies) will be installed.


Related Links



Was this article helpful?



Please tell us how we can make this article more useful.

Characters Remaining: 255