/docs/docbook5/en/source/chapters/settingup.xml

<?xml version="1.0" encoding="UTF-8"?>
<?xml-model href="http://www.oasis-open.org/docbook/xml/5.0/rng/docbookxi.rng" 
            schematypens="http://relaxng.org/ns/structure/1.0"?>
<chapter xmlns="http://docbook.org/ns/docbook" xmlns:xi="http://www.w3.org/2001/XInclude"
	xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" xml:id="ch.settingup">
	<title>Setting-up Phing</title>


	<para>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.</para>

	<sect1>
		<title> System Requirements </title>

		<para>To use Phing you must have installed PHP version 5.2 or above compiled
				<literal>--with-libxml2</literal>, as well as <literal>--with-xsl</literal> if you
			want to make use of advanced functionality.</para>

		<para>For more information on PHP and the required modules see the PHP <link
				xlink:href="Bibliography.html#php">[php]</link> website. For a brief list of
			software dependencies see below.</para>

		<sect2>
			<title> Operating Systems </title>

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

			<para>To get the most out of Phing, a Unix style platform is recommended. Namely: Linux,
				FreeBSD, OpenBSD, etc.</para>
		</sect2>
		<sect2>
			<title> Software Dependencies </title>

			<para>For a detailed list of required and/or optional software and libraries, refer to the
				following table of Software Dependencies.</para>

			<para>NB: This list is not exhaustive, please refer to individual Phing tasks to find
				out additional software requirements.</para>

			<table>
				<title>Software Dependencies</title>
				<tgroup cols="3">
					<colspec colname="c1" colnum="1" colwidth="1*"/>
					<colspec colname="c2" colnum="2" colwidth="1*"/>
					<colspec colname="c3" colnum="3" colwidth="2*"/>
					<thead>
						<row>
							<entry>Software</entry>
							<entry>Required for</entry>
							<entry>Source</entry>
						</row>
					</thead>
					<tbody>
						<row>
							<entry>PHP 5.2+</entry>
							<entry>Execution</entry>
							<entry><link xlink:href="http://www.php.net" role="external"
									>http://www.php.net</link>
							</entry>
						</row>
						<row>
							<entry>PHPUnit 3.6.0+</entry>
							<entry>Optional; enables additional task(s)</entry>
							<entry><link xlink:href="http://www.phpunit.de" role="external"
									>http://www.phpunit.de</link>
							</entry>
						</row>
						<row>
							<entry>Xdebug 2.0.5+</entry>
							<entry>Optional; enables additional task(s)</entry>
							<entry><link xlink:href="http://www.xdebug.org" role="external"
									>http://www.xdebug.org</link>
							</entry>
						</row>
						<row>
							<entry>SimpleTest 1.0.1 beta+</entry>
							<entry>Optional; enables additional task(s)</entry>
							<entry><link xlink:href="http://simpletest.sourceforge.net"
									role="external">http://simpletest.sourceforge.net</link>
							</entry>
						</row>
						<row>
							<entry>phpDocumentor 2.0.0b7+ (PEAR package)</entry>
							<entry>Optional; enables additional task(s)</entry>
							<entry><link xlink:href="http://pear.phpdoc.org"
									role="external">http://pear.phpdoc.org</link>
							</entry>
						</row>
						<row>
							<entry>VersionControl_SVN (PEAR package)</entry>
							<entry>Optional; enables additional task(s)</entry>
							<entry><link xlink:href="http://pear.php.net/package/VersionControl_SVN"
									role="external"
									>http://pear.php.net/package/VersionControl_SVN</link>
							</entry>
						</row>
						<row>
							<entry>VersionControl_Git (PEAR package)</entry>
							<entry>Optional; enables additional task(s)</entry>
							<entry><link xlink:href="http://pear.php.net/package/VersionControl_Git"
									role="external"
									>http://pear.php.net/package/VersionControl_Git</link>
							</entry>
						</row>
						<row>
							<entry>PHP_CodeSniffer (PEAR package)</entry>
							<entry>Optional; enables additional task(s)</entry>
							<entry><link xlink:href="http://pear.php.net/package/PHP_CodeSniffer"
									role="external"
									>http://pear.php.net/package/PHP_CodeSniffer</link>
							</entry>
						</row>
						<row>
							<entry>Archive_Tar (PEAR package)</entry>
							<entry>Optional; enables additional task(s)</entry>
							<entry><link xlink:href="http://pear.php.net/package/Archive_Tar"
									role="external">http://pear.php.net/package/Archive_Tar</link>
							</entry>
						</row>
						<row>
							<entry>Services_Amazon_S3 (PEAR package)</entry>
							<entry>Optional; enables additional task(s)</entry>
							<entry><link xlink:href="http://pear.php.net/package/Services_Amazon_S3"
									role="external"
									>http://pear.php.net/package/Services_Amazon_S3</link>
							</entry>
						</row>
						<row>
							<entry>HTTP_Request2 (PEAR package)</entry>
							<entry>Optional; enables additional task(s)</entry>
							<entry><link xlink:href="http://pear.php.net/package/HTTP_Request2"
									role="external">http://pear.php.net/package/HTTP_Request2</link>
							</entry>
						</row>
						<row>
							<entry>PHP Depend</entry>
							<entry>Optional; enables additional task(s)</entry>
							<entry><link xlink:href="http://www.pdepend.org" role="external"
									>http://www.pdepend.org</link>
							</entry>
						</row>
						<row>
							<entry>PHP Mess Detector</entry>
							<entry>Optional; enables additional task(s)</entry>
							<entry><link xlink:href="http://www.phpmd.org" role="external"
									>http://www.phpmd.org</link>
							</entry>
						</row>
						<row>
							<entry>PHP Copy/Paste Detector</entry>
							<entry>Optional; enables additional task(s)</entry>
							<entry><link xlink:href="http://pear.phpunit.de" role="external"
									>http://pear.phpunit.de</link>
							</entry>
						</row>
					</tbody>
				</tgroup>
			</table>

			<warning>
				<para>Phing does not work with safe mode enabled in PHP!</para>
			</warning>
		</sect2>
	</sect1>

	<sect1>
		<title> Obtaining Phing </title>

		<para>Phing is free software distributed under the terms of the LGPL.</para>

		<sect2>
			<title> Distribution Files </title>

			<para>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, register an account at GitHub as described below.</para>

			<para>The easiest way to obtain the distribution package is to visit the Phing website <link
					xlink:href="Bibliography.html#phing">[phing] </link>and download the current
				distribution package in the format you desire.</para>
			<para>As of version 2.0, 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 &amp; install the PEAR package.</para>
		</sect2>
		<sect2>
			<title>Getting the latest source from Phing Git repository</title>
			<para>The latest snapshot can always be downloaded directly the official Phing Git
				repository. However, be warned that there is not guarantee that the momentous state
				of the repository represents a completely stable application without any
				problems.</para>
			<para>You can download a snapshot as a zip-tarball from:</para>
			<itemizedlist>
				<listitem>
					<para><link xlink:href="https://github.com/phingofficial/phing"
							>https://github.com/phingofficial/phing</link></para>
				</listitem>
			</itemizedlist>
		</sect2>

	</sect1>
	<sect1>
		<title> PEAR Install </title>
		<para>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):</para>
		<screen>$&gt; pear channel-discover pear.phing.info
$&gt; pear install phing/phing</screen>
		<para>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).</para>
	</sect1>
	<sect1>
		<title> Non-PEAR Install </title>

		<para> 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: <filename
				role="dir">bin</filename> , <filename role="dir">docs</filename> and <filename
				role="dir">classes</filename>. Only the <filename role="dir">bin</filename>,
				<filename role="dir">classes</filename> and <filename role="dir">etc</filename>
			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 <literal>PHING_HOME</literal> .</para>

		<warning>
			<para>On earlier Windows installations, the script used to launch Phing will have
				problems if <literal>PHING_HOME</literal> 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 <filename
					role="dir">C:\opt\phing</filename>.</para>
		</warning>

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

		<itemizedlist>
			<listitem>
				<para>Add the full path to the <filename role="dir">bin/</filename> directory to
					your path.</para>
			</listitem>
			<listitem>
				<para>Set the <literal>PHING_HOME</literal> 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). However, it is better to not
					rely on this behavior.</para>
			</listitem>
			<listitem>
				<para>Set the <literal>PHP_COMMAND</literal> environment variable to where your Php
					binary is located (including the binary i.e. PHP_COMMAND=/usr/bin/php).</para>
			</listitem>
			<listitem>
				<para>Set the <literal>PHP_CLASSPATH</literal> 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.</para>
			</listitem>
			<listitem>
				<para>Check your php.ini file to make sure that you have the following
					settings:</para>
				<itemizedlist>
					<listitem>
						<para><code>max_execution_time = 0 // unlimited execution time</code></para>
					</listitem>
					<listitem>
						<para><code>memory_limit = 32M // you may need more memory depending on size
								of your build files</code></para>
					</listitem>
				</itemizedlist>
			</listitem>
		</itemizedlist>

		<para>If you are using Phing in conjunction with another application, you may need to add
			additional paths to <literal>PHP_CLASSPATH</literal>.</para>

		<sect2>
			<title> Unix </title>

			<para> Assuming you are running a Unix dialect operating system with the bash bourne
				shell and Phing is installed in <filename role="dir">/opt/phing</filename> . The
				following sets up the environment properly: </para>

			<screen>export PHP_COMMAND=/usr/bin/php
export PHING_HOME=/opt/phing
export PHP_CLASSPATH=${PHING_HOME}/classes
export PATH=${PATH}:${PHING_HOME}/bin</screen>
		</sect2>
		<sect2>
			<title> Windows </title>

			<para>On the Windows platform, assuming Phing is installed in <filename role="dir"
					>c:\opt\phing</filename>. The following sets up your environment:</para>

			<screen>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</screen>
		</sect2>
		<sect2>
			<title>Advanced</title>

			<para>There are lots of variants that can be used to run/prepare Phing. You need at
				least the following:</para>
			<itemizedlist>
				<listitem>
					<para>If you want Phing to be able to use other packages / classes, you can either add them to
						the <literal>PHP_CLASSPATH</literal> or to PHP's include_path.</para>
				</listitem>
				<listitem>
					<para>Some Tasks in <filename role="dir">phing/tasks/ext</filename> 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.</para>
				</listitem>
			</itemizedlist>

			<para> You are now ready to use the <command>phing</command> command at your command
				prompt, from everywhere in your directory tree.</para>
		</sect2>
	</sect1>
	<sect1>
		<title> Calling Phing </title>

		<para>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.</para>

		<sect2>
			<title> Command Line </title>

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

			<screen>$ phing [target [target2 [target3] ...]]</screen>

			<para> at the command line (where [target...] are the target(s)
				you want to be executed). If no target is specified Phing
				will try to execute the default target, as specified in the
				<literal>project</literal> tag. When calling multipe targets, Phing
				will invoke each target independently of the other targets.
				Optionally, you may specify command line arguments as listed in <link
					xlink:href="appendixes/AppendixA-FactSheet.html#CommandLineArguments">Appendix
					A</link>.</para>

			<para> For example, the following command line calls the default buildscript
					<filename>build.xml</filename> using the default target with the property
					<literal>ftp.upload</literal> set to true.</para>
			<screen>$ phing -Dftp.upload=true</screen>
		</sect2>
		<sect2>
			<title>Supported command line arguments</title>
			<para>As of version 2.4.9 the following command line arguments are supported</para>
			<programlisting>  -h -help               print this message
  -l -list               list available targets in this project
  -v -version            print the version information and exit
  -q -quiet              be extra quiet
  -verbose               be extra verbose
  -debug                 print debugging information
  -longtargets           show target descriptions during build
  -logfile &lt;file>        use given file for log
  -logger &lt;classname>    the class which is to perform logging
  -f -buildfile &lt;file>   use given buildfile
  -D&lt;property>=&lt;value>   use value for given property
  -propertyfile &lt;file>   load all properties from file
  -find &lt;file>           search for buildfile towards the root of the
                         filesystem and use it
  -inputhandler &lt;file>   the class to use to handle user input</programlisting>
		</sect2>
	</sect1>

</chapter>