command.project

<h2>Various Commands for Developing HipHop</h2>

= Learning "make"

"make" is used extensively for different commands throughout the project. The
most common way is,

  cd {directory}
  make {target}

This can be simplied to,

  make -C {directory} {target}

Throughout this doc, we will use -C form to show which directory under hphp/
the target is at, but you may always change to the directory to run "make
{target}" directly.

= Building the project

Just do a simple,

  make -C src

For verbose outputs,

  SHOW_COMPILE=1 make -C src    # show all compilation commands
  SHOW_LINK=1 make -C src       # show all linking commands
  V= make -C src                # show all commands

= Separate build directories

The default build puts all the files into the source tree. This makes it hard
to keep both DEBUG and RELEASE builds up to date, and also leaves a lot of
unversioned files in amongst your versioned files.

To solve this, there are a couple of environment variables you can use.

Setting OUTPUT_ROOT explicitly tells make where to put the generated files. You 
can put them anywhere.

Setting OUTDIR_BY_TYPE will append -g or -O to the OUTPUT_ROOT depending on
whether its a DEBUG, or RELEASE build. If you set OUTDIR_BY_TYPE without
setting OUTPUT_ROOT, OUTPUT_ROOT defaults to $(PROJECT_ROOT)/bin, and so the
generated files will all go in $(PROJECT_ROOT)/bin-g or $(PROJECT_ROOT)/bin-O.

If you set OUTDIR_BY_TYPE, the targets debug, release, and both are available
in the top-level makefile.

make debug # debug build into $(PROJECT_ROOT)/bin-g
make release # release build into $(PROJECT_ROOT)/bin-O
make both # build both

When OUTPUT_ROOT, or OUTDIR_BY_TYPE is set, all executables, static libs and
shared libs are built into the top level output directory; so you should
point HPHP_LIB and PATH at that directory.

= "make clean" or "make clobber"

Whenever you want to remove all intermediate files, you can run "make clean"
or "make clobber" from almost every directory. These two commands are the same,
although historically, "make clean" leaves built targets or binaries while
deleting all intermediate files, whereas "make clobber" removes everything. In
our case, they will both remove everything.

= Monitoring build status

This command can bring up "top" like screen to show you which .cpp files are
being built by distcc:

  make -C src top

= Running a unit test

These commands are available to run some unit tests:

  cd src/
  test/test
  test/test TestExtFile
  test/test TestExtFile test_fseek
  test/test TestExtFile::test_fseek

  make fast_tests   # 2 minutes to finish, required for every check-in
  make slow_tests   # hours to finish, required for in-depth changes

= Running a benchmark

We have "benchmark" directory set up, and you can simply throw in a PHP file
and run it under benchmark mode,

  make -C benchmark {test.run}  # if the file name is "test.php"