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.phpIf 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:8080You can also run the server as a daemon:
sudo /tmp/hphp_p6vSsP/program -m daemonMode 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端口。
使用浏览器访问：
3. Compiling a Large Codebase （编译代码库）
First, familiarize yourself with the various of switches of the compiler:
hphp/hphp --helpThere 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.listThis 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.phpNote 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 withrealpath()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.phpHaiping: 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.list4. 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=50This 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
sudobecause we need to listen to port 80, the only port WordPress works on.
-m serverruns the program in server mode.-m daemonis 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.hdfhas 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