Setting-Up Phing

The goal of this chapter is to help you obtain and correctly setup and execute Phing on your operating system. Once you setup Phing properly you shouldn't need to revisit this chapter, unless you're re-installing or moving your installation to another platform.

System Requirements

To use Phing you must have installed PHP version 5.0.0b1 or above compiled --with-libxml2, as well as --with-xsl if you want to make use of advanced functionality. At the time of writing PHP5.0.0b2-dev is currently unable to run Phing due to segmentation faults arising somewhere in the XML parsing of the build file.

For more information on PHP and the required modules see the PHP [php] website. For a brief list of software dependencies see below.

Operating Systems

Designed for portability from the get go, Phing runs on all platforms that run PHP. However some advanced funcionality may not work properly or is simply ignored on some platforms (i.e. chmod on the Windows platform).

To get the most out of Phing, a Unix style platform is recommended. Namely: Linux, FreeBSD, OpenBSD, etc.

Software Dependencies

For a detailed list of required sofware and libraries, refer to the following table of Software dependencies

Obtaining Phing

Phing is free software distributed under the terms of the LGPL.

Distribution Files

There are several ways to get a Phing distribution package. If you do not want to participate in developing Phing itself it is recommended that you get the latest snapshot or stable packaged distribution. If you are interested in helping with Phing development, get a CVS revision of the files, as described below.

The easiest way to obtain the distribution package is to visit the Phing website [phing] and download the current distribution package in the format you desire.

As of version 2.0.0b1, you have the option of downloading a PEAR-installable package or the full phing distribution. If you wish to modify phing we suggestion downloading the full version so that you can (e.g.) create your own PEAR package. If you simply wish to use Phing for your own project or need it to build another package, download & install the PEAR package.

Getting A Development Copy From CVS

You are encouraged to contibute to the development of Phing. If you want to participate in Phing development or if you are simply intereseted in the latest features and development, obtain a CVS copy as described in the following paragraphs.

The CVS revisions of Phing are not bullet-proof and may fail to execute properly on your machine. Only obtain the CVS versions if you are absolutely aware of limitations and constraints of such an action. Additionally you should sign up to the development mailinglist to report and notice errors and incompatibilities.

We assume that you are running a Unix style operating system. So we expect the CVS software is installed ant the cvs executable is in your system's search path.. However, the steps for a Windows based system are very similar. There is plenty additional resources available on how to use CVS [cvs-howto] and on CVS speciaities on the Tigris project management platfrom [cvs-tigris].

The frist thing you have to do is log onto the CVS server. Therefore type the following line at your command promt:

 cvs -d :pserver:guest@cvs.tigris.org:/cvs login

If you signed-up as developer at the Tigris website, login with your own password, the same as the one you use to access the site. Or use the password "guest" with username "guest".

If this is the only project you working on, you only need to set the cvsroot once. Thereafter when you log in to this domain, the cvs repository for this project is assumed. If you are working multiple projects, however, you must specify the cvsroot each time you log in to ensure that the cvs repository you are accessing is the right one.

To check out the project source repository an individual module (if you don't need the entire repository), type:

cvs -d :pserver:guest@cvs.tigris.org:/cvs checkout phing

This command should result in a scrolling list of files being added to the local directory you specified on your machine. Now you are ready to use your favourite file editor to work with individual files and make changes.

The top-level CVS module contains the Phing project website in addition to the phing application; the Phing files, therefore, reside in the phing/ subdirectory:

./phing/phing

PEAR Install

The easiest way to install Phing is using the PEAR installer. Provided that the package you downloaded is a the PEAR-ready package, you can install Phing simply from the command line (Unix or Windows):

$> pear install phing-2.0.0b1-pear.tar.gz

The pear installer will check any dependencies and place the phing script (phing or phing.bat) into your PHP script directoy (i.e. where the "pear" script resides).

Non-PEAR Install

If you are not using the PEAR installer, you will need to setup your environment in order to run Phing. The distribution of Phing consists of three directories: bin , docs and classes . Only the bin and classes directories are required to run Phing. To install Phing, choose a directory and uncompress the distribution file in that directory (you may already have done this in a prior step). This directory will be known as PHING_HOME .

On Windows 95 and Windows 98, the script used to launch Phing will have problems if PHING_HOME is a long filepath. This is due to limitations in the OS's handling of the "for" batch-file statement. It is recommended, therefore, that Phing be installed in a short path, such as C:\opt\phing.

Before you can run Phing there is some additional set up you will need to do perform:

• Add the full path to the bin/ directory to your path.
• Set the PHING_HOME environment variable to the directory where you installed Phing. On some operating systems the Phing wrapper scripts can guess PHING_HOME (Unix dialects and Windows NT/2000). However, it is better to not rely on this behavior.
• Set the PHP_COMMAND environment variable to where your Php binary is located (including the binary i.e. PHP_COMMAND=/usr/bin/php).
• Set the PHP_CLASSPATH environment variable (see the section below). This should be set at least point to PHING_HOME/classes. Alternatively, you can also just add the phing/classes directory to your PHP include_path ini setting.
• Check your php.ini file to make sure that you have the following settings:
  • max_execution_time = 0 // unlimited execution time
  • memory_limit = 32M // you may need more memory depending on size of your build files

If you are using Phing in conjunction with another application, you may need to add additional paths to PHP_CLASSPATH.

Unix

Assuming you are running a Unix dialect operating system with the bash bourne shell and Phing is installed in /opt/phing . The following sets up the environment properly:

  export PHP_COMMAND=/usr/bin/php
  export PHING_HOME=/opt/phing
  export PHP_CLASSPATH=${PHING_HOME}/classes
  export PATH=${PATH}:${PHING_HOME}/bin

Windows

On the Windows platfrom, assuming Phing is installed in c:\opt\phing. The following sets up your environment:

  set PHP_COMMAND=c:\opt\php\php.exe
  set PHING_HOME=c:\opt\phing
  set PHP_CLASSPATH=c:\opt\phing\classes
  set PATH=%PATH%;%PHING_HOME%\bin

Advanced

There are lots of variants that can be used to run/prepare Phing. You need at least the following:

• If you want Phing to be able to use other packages / classes, you can either add them to the PHP_CLASSPATH or to PHP's include_path.
• Some Tasks in phing/tasks/ext may require 3rd party libraries to be installed. Generally, tools with compatible license (and stable releases) are included in phing/lib so that outside dependencies can be avoided. PEAR libs will not, however, be bundled with Phing since they are generally bundled with PHP. If you are using a 3rd party task, see the Task documentation to be aware of any dependencies.

You are now ready to use the phing command at your command prompt, from everywhere in your directory tree.

Calling Phing

Now you are prepared to execute Phing on the command line or via script files. The following section briefly describe how to properly execute phing.

Command Line

Phing execution on the command line is simple. Just change to the directory where your buildfile resides and type

$ phing [targetname]

at the command line (where [targetname] is the target you want to be executed). Optionally, you may specify command line arguments as listed in Appendix A.