PageRenderTime 79ms CodeModel.GetById 52ms app.highlight 13ms RepoModel.GetById 1ms app.codeStats 0ms

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

http://github.com/phingofficial/phing
XML | 375 lines | 338 code | 37 blank | 0 comment | 0 complexity | 6c4d1e5ca7802bde008028cb282190e5 MD5 | raw file
  1<?xml version="1.0" encoding="UTF-8"?>
  2<?xml-model href="http://www.oasis-open.org/docbook/xml/5.0/rng/docbookxi.rng" 
  3            schematypens="http://relaxng.org/ns/structure/1.0"?>
  4<chapter xmlns="http://docbook.org/ns/docbook" xmlns:xi="http://www.w3.org/2001/XInclude"
  5	xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" xml:id="ch.settingup">
  6	<title>Setting-up Phing</title>
  7
  8
  9	<para>The goal of this chapter is to help you obtain and correctly setup and execute Phing on
 10		your operating system. Once you setup Phing properly you shouldn't need to revisit this
 11		chapter, unless you're re-installing or moving your installation to another platform.</para>
 12
 13	<sect1>
 14		<title> System Requirements </title>
 15
 16		<para>To use Phing you must have installed PHP version 5.2 or above compiled
 17				<literal>--with-libxml2</literal>, as well as <literal>--with-xsl</literal> if you
 18			want to make use of advanced functionality.</para>
 19
 20		<para>For more information on PHP and the required modules see the PHP <link
 21				xlink:href="Bibliography.html#php">[php]</link> website. For a brief list of
 22			software dependencies see below.</para>
 23
 24		<sect2>
 25			<title> Operating Systems </title>
 26
 27			<para>Designed for portability from the get go, Phing runs on all platforms that run PHP. However
 28				some advanced functionality may not work properly or is simply ignored on some
 29				platforms (i.e. <literal>chmod</literal> on the Windows platform).</para>
 30
 31			<para>To get the most out of Phing, a Unix style platform is recommended. Namely: Linux,
 32				FreeBSD, OpenBSD, etc.</para>
 33		</sect2>
 34		<sect2>
 35			<title> Software Dependencies </title>
 36
 37			<para>For a detailed list of required and/or optional software and libraries, refer to the
 38				following table of Software Dependencies.</para>
 39
 40			<para>NB: This list is not exhaustive, please refer to individual Phing tasks to find
 41				out additional software requirements.</para>
 42
 43			<table>
 44				<title>Software Dependencies</title>
 45				<tgroup cols="3">
 46					<colspec colname="c1" colnum="1" colwidth="1*"/>
 47					<colspec colname="c2" colnum="2" colwidth="1*"/>
 48					<colspec colname="c3" colnum="3" colwidth="2*"/>
 49					<thead>
 50						<row>
 51							<entry>Software</entry>
 52							<entry>Required for</entry>
 53							<entry>Source</entry>
 54						</row>
 55					</thead>
 56					<tbody>
 57						<row>
 58							<entry>PHP 5.2+</entry>
 59							<entry>Execution</entry>
 60							<entry><link xlink:href="http://www.php.net" role="external"
 61									>http://www.php.net</link>
 62							</entry>
 63						</row>
 64						<row>
 65							<entry>PHPUnit 3.6.0+</entry>
 66							<entry>Optional; enables additional task(s)</entry>
 67							<entry><link xlink:href="http://www.phpunit.de" role="external"
 68									>http://www.phpunit.de</link>
 69							</entry>
 70						</row>
 71						<row>
 72							<entry>Xdebug 2.0.5+</entry>
 73							<entry>Optional; enables additional task(s)</entry>
 74							<entry><link xlink:href="http://www.xdebug.org" role="external"
 75									>http://www.xdebug.org</link>
 76							</entry>
 77						</row>
 78						<row>
 79							<entry>SimpleTest 1.0.1 beta+</entry>
 80							<entry>Optional; enables additional task(s)</entry>
 81							<entry><link xlink:href="http://simpletest.sourceforge.net"
 82									role="external">http://simpletest.sourceforge.net</link>
 83							</entry>
 84						</row>
 85						<row>
 86							<entry>phpDocumentor 2.0.0b7+ (PEAR package)</entry>
 87							<entry>Optional; enables additional task(s)</entry>
 88							<entry><link xlink:href="http://pear.phpdoc.org"
 89									role="external">http://pear.phpdoc.org</link>
 90							</entry>
 91						</row>
 92						<row>
 93							<entry>VersionControl_SVN (PEAR package)</entry>
 94							<entry>Optional; enables additional task(s)</entry>
 95							<entry><link xlink:href="http://pear.php.net/package/VersionControl_SVN"
 96									role="external"
 97									>http://pear.php.net/package/VersionControl_SVN</link>
 98							</entry>
 99						</row>
100						<row>
101							<entry>VersionControl_Git (PEAR package)</entry>
102							<entry>Optional; enables additional task(s)</entry>
103							<entry><link xlink:href="http://pear.php.net/package/VersionControl_Git"
104									role="external"
105									>http://pear.php.net/package/VersionControl_Git</link>
106							</entry>
107						</row>
108						<row>
109							<entry>PHP_CodeSniffer (PEAR package)</entry>
110							<entry>Optional; enables additional task(s)</entry>
111							<entry><link xlink:href="http://pear.php.net/package/PHP_CodeSniffer"
112									role="external"
113									>http://pear.php.net/package/PHP_CodeSniffer</link>
114							</entry>
115						</row>
116						<row>
117							<entry>Archive_Tar (PEAR package)</entry>
118							<entry>Optional; enables additional task(s)</entry>
119							<entry><link xlink:href="http://pear.php.net/package/Archive_Tar"
120									role="external">http://pear.php.net/package/Archive_Tar</link>
121							</entry>
122						</row>
123						<row>
124							<entry>Services_Amazon_S3 (PEAR package)</entry>
125							<entry>Optional; enables additional task(s)</entry>
126							<entry><link xlink:href="http://pear.php.net/package/Services_Amazon_S3"
127									role="external"
128									>http://pear.php.net/package/Services_Amazon_S3</link>
129							</entry>
130						</row>
131						<row>
132							<entry>HTTP_Request2 (PEAR package)</entry>
133							<entry>Optional; enables additional task(s)</entry>
134							<entry><link xlink:href="http://pear.php.net/package/HTTP_Request2"
135									role="external">http://pear.php.net/package/HTTP_Request2</link>
136							</entry>
137						</row>
138						<row>
139							<entry>PHP Depend</entry>
140							<entry>Optional; enables additional task(s)</entry>
141							<entry><link xlink:href="http://www.pdepend.org" role="external"
142									>http://www.pdepend.org</link>
143							</entry>
144						</row>
145						<row>
146							<entry>PHP Mess Detector</entry>
147							<entry>Optional; enables additional task(s)</entry>
148							<entry><link xlink:href="http://www.phpmd.org" role="external"
149									>http://www.phpmd.org</link>
150							</entry>
151						</row>
152						<row>
153							<entry>PHP Copy/Paste Detector</entry>
154							<entry>Optional; enables additional task(s)</entry>
155							<entry><link xlink:href="http://pear.phpunit.de" role="external"
156									>http://pear.phpunit.de</link>
157							</entry>
158						</row>
159					</tbody>
160				</tgroup>
161			</table>
162
163			<warning>
164				<para>Phing does not work with safe mode enabled in PHP!</para>
165			</warning>
166		</sect2>
167	</sect1>
168
169	<sect1>
170		<title> Obtaining Phing </title>
171
172		<para>Phing is free software distributed under the terms of the LGPL.</para>
173
174		<sect2>
175			<title> Distribution Files </title>
176
177			<para>There are several ways to get a Phing distribution package. If you do not want to
178				participate in developing Phing itself it is recommended that you get the latest
179				snapshot or stable packaged distribution. If you are interested in helping with
180				Phing development, register an account at GitHub as described below.</para>
181
182			<para>The easiest way to obtain the distribution package is to visit the Phing website <link
183					xlink:href="Bibliography.html#phing">[phing] </link>and download the current
184				distribution package in the format you desire.</para>
185			<para>As of version 2.0, you have the option of downloading a PEAR-installable package
186				or the full phing distribution. If you wish to modify phing we suggestion
187				downloading the full version so that you can (e.g.) create your own PEAR package. If
188				you simply wish to use Phing for your own project or need it to build another
189				package, download &amp; install the PEAR package.</para>
190		</sect2>
191		<sect2>
192			<title>Getting the latest source from Phing Git repository</title>
193			<para>The latest snapshot can always be downloaded directly the official Phing Git
194				repository. However, be warned that there is not guarantee that the momentous state
195				of the repository represents a completely stable application without any
196				problems.</para>
197			<para>You can download a snapshot as a zip-tarball from:</para>
198			<itemizedlist>
199				<listitem>
200					<para><link xlink:href="https://github.com/phingofficial/phing"
201							>https://github.com/phingofficial/phing</link></para>
202				</listitem>
203			</itemizedlist>
204		</sect2>
205
206	</sect1>
207	<sect1>
208		<title> PEAR Install </title>
209		<para>The easiest way to install Phing is using the PEAR installer. Provided that the
210			package you downloaded is a the PEAR-ready package, you can install Phing simply from
211			the command line (Unix or Windows):</para>
212		<screen>$&gt; pear channel-discover pear.phing.info
213$&gt; pear install phing/phing</screen>
214		<para>The pear installer will check any dependencies and place the phing script (phing or
215			phing.bat) into your PHP script directoy (i.e. where the "pear" script resides).</para>
216	</sect1>
217	<sect1>
218		<title> Non-PEAR Install </title>
219
220		<para> If you are not using the PEAR installer, you will need to setup your environment in
221			order to run Phing. The distribution of Phing consists of three directories: <filename
222				role="dir">bin</filename> , <filename role="dir">docs</filename> and <filename
223				role="dir">classes</filename>. Only the <filename role="dir">bin</filename>,
224				<filename role="dir">classes</filename> and <filename role="dir">etc</filename>
225			directories are required to run Phing. To install Phing, choose a directory and
226			uncompress the distribution file in that directory (you may already have done this in a
227			prior step). This directory will be known as <literal>PHING_HOME</literal> .</para>
228
229		<warning>
230			<para>On earlier Windows installations, the script used to launch Phing will have
231				problems if <literal>PHING_HOME</literal> is a long filepath. This is due to
232				limitations in the OS's handling of the "for" batch-file statement. It is
233				recommended, therefore, that Phing be installed in a short path, such as <filename
234					role="dir">C:\opt\phing</filename>.</para>
235		</warning>
236
237		<para>Before you can run Phing there is some additional set up you will need to do
238			perform:</para>
239
240		<itemizedlist>
241			<listitem>
242				<para>Add the full path to the <filename role="dir">bin/</filename> directory to
243					your path.</para>
244			</listitem>
245			<listitem>
246				<para>Set the <literal>PHING_HOME</literal> environment variable to the directory
247					where you installed Phing. On some operating systems the Phing wrapper scripts
248					can guess PHING_HOME (Unix dialects and Windows). However, it is better to not
249					rely on this behavior.</para>
250			</listitem>
251			<listitem>
252				<para>Set the <literal>PHP_COMMAND</literal> environment variable to where your Php
253					binary is located (including the binary i.e. PHP_COMMAND=/usr/bin/php).</para>
254			</listitem>
255			<listitem>
256				<para>Set the <literal>PHP_CLASSPATH</literal> environment variable (see the section
257					below). This should be set at least point to PHING_HOME/classes. Alternatively,
258					you can also just add the phing/classes directory to your PHP include_path ini
259					setting.</para>
260			</listitem>
261			<listitem>
262				<para>Check your php.ini file to make sure that you have the following
263					settings:</para>
264				<itemizedlist>
265					<listitem>
266						<para><code>max_execution_time = 0 // unlimited execution time</code></para>
267					</listitem>
268					<listitem>
269						<para><code>memory_limit = 32M // you may need more memory depending on size
270								of your build files</code></para>
271					</listitem>
272				</itemizedlist>
273			</listitem>
274		</itemizedlist>
275
276		<para>If you are using Phing in conjunction with another application, you may need to add
277			additional paths to <literal>PHP_CLASSPATH</literal>.</para>
278
279		<sect2>
280			<title> Unix </title>
281
282			<para> Assuming you are running a Unix dialect operating system with the bash bourne
283				shell and Phing is installed in <filename role="dir">/opt/phing</filename> . The
284				following sets up the environment properly: </para>
285
286			<screen>export PHP_COMMAND=/usr/bin/php
287export PHING_HOME=/opt/phing
288export PHP_CLASSPATH=${PHING_HOME}/classes
289export PATH=${PATH}:${PHING_HOME}/bin</screen>
290		</sect2>
291		<sect2>
292			<title> Windows </title>
293
294			<para>On the Windows platform, assuming Phing is installed in <filename role="dir"
295					>c:\opt\phing</filename>. The following sets up your environment:</para>
296
297			<screen>set PHP_COMMAND=c:\opt\php\php.exe
298set PHING_HOME=c:\opt\phing
299set PHP_CLASSPATH=c:\opt\phing\classes
300set PATH=%PATH%;%PHING_HOME%\bin</screen>
301		</sect2>
302		<sect2>
303			<title>Advanced</title>
304
305			<para>There are lots of variants that can be used to run/prepare Phing. You need at
306				least the following:</para>
307			<itemizedlist>
308				<listitem>
309					<para>If you want Phing to be able to use other packages / classes, you can either add them to
310						the <literal>PHP_CLASSPATH</literal> or to PHP's include_path.</para>
311				</listitem>
312				<listitem>
313					<para>Some Tasks in <filename role="dir">phing/tasks/ext</filename> may require 3rd party
314						libraries to be installed. Generally, tools with compatible license (and
315						stable releases) are included in phing/lib so that outside dependencies can
316						be avoided. PEAR libs will not, however, be bundled with Phing since they
317						are generally bundled with PHP. If you are using a 3rd party task, see the
318						Task documentation to be aware of any dependencies.</para>
319				</listitem>
320			</itemizedlist>
321
322			<para> You are now ready to use the <command>phing</command> command at your command
323				prompt, from everywhere in your directory tree.</para>
324		</sect2>
325	</sect1>
326	<sect1>
327		<title> Calling Phing </title>
328
329		<para>Now you are prepared to execute Phing on the command line or via script files. The
330			following section briefly describe how to properly execute phing.</para>
331
332		<sect2>
333			<title> Command Line </title>
334
335			<para>Phing execution on the command line is simple. Just change to the directory where
336				your buildfile resides and type</para>
337
338			<screen>$ phing [target [target2 [target3] ...]]</screen>
339
340			<para> at the command line (where [target...] are the target(s)
341				you want to be executed). If no target is specified Phing
342				will try to execute the default target, as specified in the
343				<literal>project</literal> tag. When calling multipe targets, Phing
344				will invoke each target independently of the other targets.
345				Optionally, you may specify command line arguments as listed in <link
346					xlink:href="appendixes/AppendixA-FactSheet.html#CommandLineArguments">Appendix
347					A</link>.</para>
348
349			<para> For example, the following command line calls the default buildscript
350					<filename>build.xml</filename> using the default target with the property
351					<literal>ftp.upload</literal> set to true.</para>
352			<screen>$ phing -Dftp.upload=true</screen>
353		</sect2>
354		<sect2>
355			<title>Supported command line arguments</title>
356			<para>As of version 2.4.9 the following command line arguments are supported</para>
357			<programlisting>  -h -help               print this message
358  -l -list               list available targets in this project
359  -v -version            print the version information and exit
360  -q -quiet              be extra quiet
361  -verbose               be extra verbose
362  -debug                 print debugging information
363  -longtargets           show target descriptions during build
364  -logfile &lt;file>        use given file for log
365  -logger &lt;classname>    the class which is to perform logging
366  -f -buildfile &lt;file>   use given buildfile
367  -D&lt;property>=&lt;value>   use value for given property
368  -propertyfile &lt;file>   load all properties from file
369  -find &lt;file>           search for buildfile towards the root of the
370                         filesystem and use it
371  -inputhandler &lt;file>   the class to use to handle user input</programlisting>
372		</sect2>
373	</sect1>
374
375</chapter>