WHAT IS PHC

phc is a compiler for PHP that will translate PHP code directly into
Linux assembly code. It can be used as a (C++) framework for developing
refactoring tools, aspect weavers, script obfuscators and any other
tools that operate on PHP scripts.

At the moment, phc gives the programmer a nice representation of a PHP
script (not unlike the DOM tree representation of an XML script),
provides an interface for modifying this tree, and provides a way to
output this tree back to normal PHP code.

Note that in particular, the current release does not yet compile PHP.
It is therefore not yet useful for end-users, but can be very useful for
programmers wishing to implement tools for PHP.

Full documentation can be found at http://www.phpcompiler.org.
	
SYSTEM REQUIREMENTS

phc needs a Unix-like environment to run (it has been tested on Solaris
and Linux). To compile phc, you need at least the following tools.

    * C and C++ compiler (we have only tested with gcc)
    * make
    * flex
    * bison
    * patch
    * grep 

However, these tools should come pre-installed on most systems. In addition,
you may need two other tools (which are less commonly pre-installed): If you
want to add extra command line arguments to phc, you will need gengetopt
<http://www.gnu.org/software/gengetopt/gengetopt.html>. If you are feeling
adventurous and want to modify the actual parser, you may also need gperf
<http://www.gnu.org/software/gperf/gperf.html> to make the lexical analyser
recognize extra keywords.

Finally, phc has some graphical output in the form of trees and graphs.  These
graphics use the "dot" format, and you will need something like graphviz
<http://www.graphviz.org> to view them.

phc does not need any special libraries (other than the ones included with the
distribution).

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.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
make

This should compile without any warnings or errors (there might be one warning
about patching |php.tab.cpp| that can safely be ignored). 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.

TESTING YOUR INSTALLATION 

If everything went smoothly, you should now have a new binary called "phc" in
the current directory. Run it by typing

./phc

You should see something like

phc revision 316 (2005/09/30)

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

  -h, --help               Print help and exit
  -V, --version            Print version and exit
      --dump-tokens        Perform lexical analysis only (spits out a token 
                             list). Probably only useful for debugging phc.  
                             (default=off)
      --dump-php           Dump PHP code back immediately after parsing to 
                             standard output (pretty printing).  (default=off)
      --dump-ast           Dump the AST from the source in dot format.  
                             (default=off)

RUNNING PHC 

In this section, we very briefly show how to run phc. 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
   /*
    * PHP output generated by the phc unparser
    * phc revision 359 (2005/10/11)
    */

   print("Hello world!");
?>

Finally, phc represents PHP scripts internally as trees (this is further
explained in Tutorial 1, available from the phc website). 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 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

dot helloworld.dot

And you should see the tree. If all this works, congratulations!  You have
successfully installed phc :-) Read Getting Started (also available from the
phc website) for more information on using phc.
