/docs/docbook5/en/source/chapters/settingup.xml
XML | 382 lines | 345 code | 37 blank | 0 comment | 0 complexity | 945f8ebe91edef36470cc1f5be781f01 MD5 | raw file
Possible License(s): LGPL-3.0
- <?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.4.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.0+</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 1.4.0+ (PEAR package)</entry>
- <entry>Optional; enables additional task(s)</entry>
- <entry><link xlink:href="http://pear.php.net/package/PhpDocumentor"
- role="external">http://pear.php.net/package/PhpDocumentor</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>
- <row>
- <entry>DocBlox 0.17.0+</entry>
- <entry>Optional; enables additional task(s)</entry>
- <entry><link xlink:href="http://www.docblox-project.org" role="external"
- >http://www.docblox-project.org</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 & 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>$> pear channel-discover pear.phing.info
- $> 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 <file> use given file for log
- -logger <classname> the class which is to perform logging
- -f -buildfile <file> use given buildfile
- -D<property>=<value> use value for given property
- -propertyfile <file> load all properties from file
- -find <file> search for buildfile towards the root of the
- filesystem and use it
- -inputhandler <file> the class to use to handle user input</programlisting>
- </sect2>
- </sect1>
- </chapter>