These instructions have been updated for version 0.1.6.

phc needs a Unix-like environment to run (it has been tested on Linux,
Solaris, and Mac OS X). To compile phc, you will need

  * gcc version 3.4.0 or higher (other compilers may work too, but they
    need to support covariant return types; YMMV)
  * make

To make full use of phc, you will also need

  * Xerces-C++ if you want support for XML parsing (you don't need Xerces
    for XML unparsing).
  * a DOT viewer such as graphviz if you want to be able to view the
    graphical output generated by phc (for example, syntax trees)

Finally, if you want to modify the internals of phc (in other ways than
through the explicit API we provide for doing so), you will need the
following tools:

  * flex (if you need to modify the lexical analyser)
  * bison (if you need to modify the syntax analyser)
  * patch (if you modify either the lexical or the syntax analyser)
  * ghc (to compile maketea, which is written in Haskell; you will need to
    compile maketea either if you want to modify the phc grammar (not an
    easy thing to do), or modify maketea itself)
  * gengetopt (if you need to add additional command line arguments; you
    will need version 0.16 or higher)
  * gperf (if you need to modify the list of keywords recognized by the
    lexical analyser)

However, most people should not need these tools (even if you are
implementing tools based on phc).

It is possible to link phc to the Boehm garbage collector (known as libgc
in many Linux distributions), but this feature is experimental and seems
to lead to runtime errors on some systems. Use with care.

                        Installation Instructions

First of all, you must download the latest release of phc, and save it to
some temporary location, for example /tmp. If VERSION is the version
number of the copy of phc you have downloaded, the file will be called
phc-VERSION.tar.gz. Thus, you should now have a file
/tmp/phc-VERSION.tar.gz (for example, /tmp/phc-0.1.6.tar.gz).

Next you must decide where you want to extract phc. Here, we will assume
that you want to extract it to your home directory (~). Extract phc as
follows.

cd ~
tar xvfz /tmp/phc-VERSION.tar.gz

This will create a new directory ~/phc-VERSION that contains the phc
source tree. Finally, you must compile phc. You should be able to simply
type

cd ~/phc-VERSION
./configure
make

This should compile without any warnings or errors. If this step fails,
please send a bug report to the mailing list with as much information
about your system as you can give, and we will try to resolve it.

Once you have installed phc, run it by typing

./phc --help

You should see something like

phc 0.1.7

Usage: phc [OPTIONS]... [FILES]...

  -h, --help                   Print help and exit
      --full-help              Print help, including hidden options, and exit
  -V, --version                Print version and exit
      --run=STRING             Run the specified plugin
      --dump-php               Dump PHP code back immediately after parsing to
                                 standard output (pretty printing)
                                 (default=off)
      --dump-ast-dot           Dump the AST from the source in dot format
                                 (default=off)
      --dump-ast-xml           Dump the AST from the source in XML format
                                 (default=off)
      --read-ast-xml           Assume the input is a phc AST in XML format
                                 (default=off)
      --compile-time-includes  When possible, replace include() statements with
                                 the parsed contents of the specified file
                                 (default=off)
      --tab=STRING             String to use for tabs while unparsing
                                 (default=`     ')

(the exact output will depend on the version of phc)

Now write a very small PHP script, for example

<? echo "Hello world!"; ?>

and store it in a file, for example in helloworld.php. Then run phc as follows:

./phc --dump-php helloworld.php

This should output a pretty-printed version of your PHP script back to standard
output:

<?php
   echo "Hello world!";
?>

Graphical Output

phc represents PHP scripts internally as trees (this is further explained in
Tutorial 1). If you have a DOT viewer installed on your system (for example,
graphviz), you can view this tree graphically. First, ask phc to output the tree
in DOT format:

./phc --dump-ast-dot helloworld.php > helloworld.dot

You can then view the tree (helloworld.dot) using Graphviz. In most Unix/Linux
systems, you should be able to do

dotty helloworld.dot

And you should see the tree (it should look similar to the one we generated).

Writing and Reading XML

phc can also output an XML representation of the tree. You can use this
representation if you want to process PHP scripts without using the phc
framework, but yet using the phc abstract representation of PHP scripts. To
generate an XML version of the tree, run

./phc --dump-ast-xml helloworld.php > helloworld.xml

phc can also read the XML back in, after which all the usual features of phc are
again available; in particular, it is possible to read an XML file, and write
PHP syntax. To convert the XML file we just generated back to PHP syntax, run

./phc --dump-php helloworld.xml

The generated XML uses the schema http://www.phpcompiler.org/phc-1.0.

Compile-time Includes

phc now has initial support for compile-time processing of PHP's include
built-in. Enabling this feature inserts the included statements in the AST in
the place of the include statement. Included functions become part of the %MAIN%
class, and included classes become part of the script. In the event that phc is
not able to process the include statement (for example, if it would require
using the remote feature of include), a warning is issued, and the include
statement is left in place. To enable this support, run

./phc --compile-time-includes script_with_includes.php

The include support is intended to mimic PHP's include built-in, as far as can
be achieved at compile time. phc supports:
  * Moving included statements to the point at which include was called.
    Naturally, these statement's use the variable scope at the point at which
    they are included,
  * Preserving __FILE__ and __LINE__ statements,
  * Moving included functions to the %MAIN% class, and importing the included
    classes,
  * include, and require. If the specified file cannot be found, parsed, or if
    the argument to include is not a string literal, the include statement is
    left in place.
phc does not support:
  * Return values in included scripts. We intend to support these in the future.
    They will likely be supported in a later stage of the compilation process,
    instead of in the AST,
  * Calling include on anything other than a literal string containing the
    filename of a local file. This excludes variables and remote files. These
    may be supported when more static analyses are available,
  * include_once and require_once, as we cannot guarantee that the file to be
    included is not included elsewhere. These statements will not be processed,
    and combinations of include or require and include_once or require_once may
    cause incorrect behaviour with this option set,
  * Updating get_included_files() to reflect the included files.
