Note: These

code examples assume the HipHop compiler is fully built.

1 . Setting Up Your Environment (构建环境)

To get started, you need to configure two environment variables.

cd .. # into the root of the hphp checkout

export HPHP_HOME=`pwd`

export HPHP_LIB=`pwd`/bin

# if you followed the Ubuntu 9.10 instructions, you also need

export CMAKE_PREFIX_PATH=`/bin/pwd`/../

2 . Choosing which Mode to Run HipHop  (HipHop运行模式)

You can run HipHop in 5 different modes. These Hello World examples demonstrate each one. All commands are run from the src/ directory in these examples.

First, create a file called test.php. Populate it with some text, like, “echo Hello, World! > test.php”. Then choose from the following modes:

Mode 1 (直接运行模式): Compiling HipHop and running it directly.

echo "Hello, World!" > test.php

hphp/hphp test.php

Mode 2 (命令行运行编译程序): Compiling HipHop in a temporary directory and running the compiled program from the command line.

hphp/hphp test.php --keep-tempdir=1 --log=3

/tmp/hphp_p6vSsP/program (use your own temporary directory name from output)

--keep-tempdir=1 can

also be specified with -k

1. Note it’s single dash and there is a space, not “=” between “k” and “1”. This is something to watch out when working with boost command line options.

--log=3 outputs

some verbose information, so you can find out which temporary directory it created. You may always specify your own output directory with --output-dir=mypath or -o

mypath.

Mode 3 (使用web 运行编译模程序 ): Compiling HipHop in a temporary directory and running the compiled program as a web server.

hphp/hphp test.php --keep-tempdir=1 --log=3

sudo /tmp/hphp_p6vSsP/program -m server

Then, from another window, run:

curl localhost/test.php

If you don’t want to use sudo, you can run HipHop on port 8080.

hphp/hphp test.php --keep-tempdir=1 --log=3

/tmp/hphp_p6vSsP/program -m server -p 8080

curl http://localhost:8080/test.php

Run this command to administer your server:

curl http://localhost:8080

You can also run the server as a daemon:

sudo /tmp/hphp_p6vSsP/program -m daemon

Mode 4 (直接解释运行): Interpreting HipHop directly.

hphpi/hphpi -f test.php (note the "-f" flag)

Mode

5 (web服务器运行源代码): Starting a Web server or daemon and interpreting HipHop on the fly.

sudo hphpi/hphpi -m server (or daemon)

curl localhost/test.php

curl localhost:8088

说明：

curl localhost/test.php其实就是客户端浏览器访问模式，好多人都问hiphop怎么和web服务器结合?

我们前面安装了库libevent。而PHP也能直接使用libevent构建web服务器.

其实HipHop可以当作web服务器来运行，说白了hphpi/hphpi -m server就是监听个端口守护进程，默认是80端口。

命令

我的安装目录是/opt/hiphop/hiphop-php/

如图：

1)sudo src/hphpi/hphpi -m server相当apache的守护进程启动，并监听80端口。

2)目录/opt/hiphop/hiphop-php/相当于apache的web根目录

3)在这个目录下可以新建文件

test.php,内容如下：

使用浏览器访问：

再新建test文件夹，

cp  test.php   test/

访问结果：

3. Compiling a Large Codebase (编译代码库)

First, familiarize yourself with the various of switches of the compiler:

hphp/hphp --help

There are 3 ways to specify some flags.

(1) by a configuration file in HDF format.

Please read doc/hdf for more details with the format. Then use--config to

specify the config file.

(2) For almost every option in HDF file,

you can list it directly in its dot notation format. For example,-v

"node.subnode=value".

(3) We created some shortcuts for most frequently used ones. They will look like --force.

The most important flags to learn are the ones for including or excluding files and directories. They were not designed cleanly and we may have to improve the way how they work. When in doubt, simply use the --input-list switch

to take a list of file names prepared in a separate file.

You can get all the possible flags here: Runtime

options

Using Parse-on-demand Mode (optional)

You can include files that are not specified from the command line into the compilation only if

the compiler can determine where to find them. This means your include statements themselves are either:

Formed by simple literals; so the compiler can compute them during compilation time.

Written in simple form like "include_once

$MY_ROOT.'/path/file.php';"

Note: You

can tell the compiler where to look for $MY_ROOT by creating a configuration file with content like this:

IncludeRoots {

* {

root = $MY_ROOT

path = lib/my_code

}

* {

root = $ANOTHER_ROOT

path = anotherlib

}

}

Use --config to

include this configuration file. The compiler resolves the above include statement as “lib/my_code/path/file.php”.

Note: If

you find parse-on-demand mode difficult to configure, try using --input-list to

include every PHP file

you want to compile.

Using distcc

For large compilations, we recommend setting up distcc.

4 . Example: Compiling PHPUnit

1.Check out PHPUnit’s PHP files:

git clone git://github.com/sebastianbergmann/phpunit.git

cd phpunit

git checkout -b 3.4 origin/3.4

2. We will use the safest and the cleanest way to specify input files,

find . -name "*.php" > files.list

This prepares a list of all PHP files

we want to compile.

3. Now we’re ready to compile the project.

$HPHP_HOME/src/hphp/hphp --input-list=files.list -k 1 --log=3 \

--include-path="." --force=1 --cluster-count=50 \

-v "AllDynamic=true" -v "AllVolatile=true"

-k

1 or --keep-tempdir=1 so

it creates a new temporary directory every time. This is convenient when you’re experimenting the compilation.

The --include-path is

needed, because PHPUnit has file includes relative to root directory of phpunit. Without specifying this option, all includes in a format of “include ‘somepath/file.php’;” will be treated as relative path to the containing file.

--force=1 is

needed to ignore warnings and errors HipHop found in the code. Without this option, the compiler will halt and dump out the errors on the screen, if any. With --force=1,

those errors will mostly turn into run-time ones, and you may still find them in CodeError.js generated under the output directory.

--cluster-count=50 helps

compilation, with or without distcc. Without this flag, each PHP file

generates one .cpp file. When the number of PHPfiles

is large, we may end up with too many .cpp files to compile. With clustering, no matter how many PHP files

we have, HipHop will generate roughly the specified number of .cpp files, so it’s easier to feed them into distcc with fewer rounds. What we found is, cluster count should be slightly smaller than number of distcc workers. For example, if you have 20 machines

each with 8 distcc workers, cluster count of 100 may be suitable. But one should change the numbers up and down to compare compilation time to find out the optimal value.

-v

"AllDynamic=true" With this option, we can support dynamic function calls and dynamic method calls without any problems. Recommended to turn on, if coding has them. It will sacrifice performance a little bit, but it’s safe to have it.

-v

"AllVolatile=true" With this option, we can support dynamic declarations of functions and classes without any problems. This is not recommended to turn on, unless your coding has crazy testing of function_exists() or class_exists() before

or after declarations and the order is meaningful. PHPUnit happens to call get_declared_classes() before

and after loading some class files and compare their returns to find new classes. Therefore, we need to add this switch to PHPUnit. Most likely, you don’t have to. It sacrifices performance in various degrees.

4. Now you should have a compiled PHPUnit binary. Report any problems to us, if you cannot reach this far. To run the binary,

php phpunit.php (in PHP)

/tmp/hphp_po33pK/program -f phpunit.php (in HipHop, note the -f flag)php phpunit.php PHPUnit/Tests/Framework/SuiteTest.php

/tmp/hphp_po33pK/program -v "Server.SourceRoot=`pwd`" \

-f phpunit.php PHPUnit/Tests/Framework/SuiteTest.php

Note that the compiled binary “program” has to run from the same directory you normally run phpunit.php,

only because PHPUnit hasfile_exists() testing

that goes to local disk to look for some .php files. There is a way to remove this disk location dependency by building a static file cache, but we will leave that to some more advanced instructions.

Also note that -v

"Server.SourceRoot=`pwd`" normally is not needed. But PHPUnit has quite a few file location based operations that will try to compare source file name with what’s on local disk with realpath() calls.

So we had to add this one to run through the tests.

5.Some useful tips:

(1) If you just created a binary with --keep-tempdir=1,

but forgot to copy the name, a simple command can normally find it,

ls -altrd /tmp/hphp_* | tail -1

(2) You may run out of disk space with too many temporary directories. Just rm all HipHop temps like this,

rm -fR /tmp/hphp_*

5 . Example: Running PHPUnit under HPHPi

$HPHP_HOME/src/hphpi/hphpi -f phpunit.php

$HPHP_HOME/src/hphpi/hphpi -f phpunit.php PHPUnit/Tests/Framework/SuiteTest.php

Haiping: We can pass all in SuiteTest.php, but we do have several other tests under PHPUnit/Tests/Framework that we’re not able to fully pass yet, due to some local disk assumption in PHPUnit and perhaps some minor bugs. Still debugging

to see if we can fix all these issues.

6 . Example: Compiling WordPress

1. Get a copy of WordPress. Please note, we identified 2 or 3 problems with WordPress that need to be fixed before HipHop can compile it. These have been fixed in trunk of the Wordpress SVN but

not backported.

wget http://wordpress.org/latest.tar.gz

tar zxvf wordpress-2.9.1.tar.gz

cd wordpress

[patch to fix some PHP coding problems that will cause compilation errors]

2. Create a config.php, perhaps by copying config.sample.php and set up database information. This file needs to be prepared BEFORE the

compilation, so it’s compiled into the final binary. Any changes of this file need a re-compilation of the whole package. NOTE:

use the loopback interface (typically ‘127.0.0.1’) instead of ‘localhost’; see this

thread on the mailing list for an explanation.

3. This prepares a list of all PHP files

we want to compile:

find . -name "*.php" > files.list

4.Now we’re ready to compile the project.

$HPHP_HOME/src/hphp/hphp --input-list=files.list -k 1 --log=3 \

--force=1 --cluster-count=50

This is simpler than PHPUnit, because WordPress doesn’t have as much dynamic coding as PHPUnit does.

5. Now you should have a compiled binary. To run it,

sudo /tmp/hphp_xpl7hT/program -m server -v "Server.SourceRoot=`pwd`" \

-v "Server.DefaultDocument=index.php" -c $HPHP_HOME/bin/mime.hdf

sudo because

we need to listen to port 80, the only port WordPress works on.

-m

server runs the program in server mode. -m

daemon is okay as well.

-v

"Server.SourceRoot=`pwd`" We still need this to locate image and css files.

-v

"Server.DefaultDocument=index.php", so http://server/ would work.

-c

$HPHP_HOME/bin/mime.hdf has a list of static content file extensions that need to be loaded by the server to be able to serve those files with different MIME headers.

If you want to see verbose logging, add these flags,

-v

"Log.Level=Verbose" This will output a lot more errors, warnings and information.

-v

"Log.NoSilencer=on" This prints out errors from statements that have “@” operators, which WordPress code uses a lot.

-v

"Log.Header=on" This will print a header for each line of logging. The most interesting in the header is a long string with hex-encoding. That’s hex-encoded stacktrace. To translate it into something readable, run this command,

/tmp/hphp_xpl7hT/program -m translate the-long-hex-string-without-brackets