options.compiler

<h2>Configurable Options for Compiler</h2>

Compiler has a --config option to take a configuration file in HDF format, and
it has a --config-value to take ad-hoc configurable options in HDF format.
This documentation describes what's available for both of them.

When in doubt, look for how these options are parsed in compiler/options.cpp.

= UseHHBBC

Default is true. Determines whether whole-program optimizations should
performed on the bytecode using hhbbc as part of the hphp run. When
false, you can still separately run hhbbc on the repo that hphp
produces (useful for development on hhbbc itself).

= AllDynamic

Default is false. When turned on, all functions and methods can be invoked
dynamically even without a literal string. When turned off, some dynamic
function calls may fail, if compiler is not able to tell that function may be
invoked dynamically. Recommend to turn on this switch.

= AllVolatile

Default is false. When turned on, order-dependent function or class declaration
vs. existence testing can work. When turned off, some function_exists(),
class_exists(), get_defined_functions() or get_declared_classes() may return
different results than PHP does. Most programs don't have dependencies on their
behaviors, so this is recommended to leave as off.

= EnableEval

Default is 0, eval() will throw a fatal error. When 1, eval() is supported in
a limited way, mixed together with compiled program. When 2, eval() is fully
supported as an interpreter mode.

= IncludeRoots

Only needed when --input-list is not used.
In this case, compiler needs to understand every single include. Currently it
only understands these formats (compiler/analysis/dependency_graph.cpp),

  include 'literal_file_path';
  include $SOME_VARIABLE . 'literal_file_path';

IncludeRoots is designed to look up $SOME_VARIABLE in the second case, so to
resolve file paths at compilation time. It will look like this,

  IncludeRoots {
    * {
      root = $SOME_VARIABLE
      path = lib/
    }
    * {
      root = $SOME_OTHER_ROOT
      path = lib/another
    }
  }

= IncludeSearchPaths

Only needed when --input-list is not used.
Specifies more paths to search for include files. For example,

  IncludeSearchPaths {
    * = lib/thrift/packages
    * = lib/common
  }

= PackageDirectories

Add all PHP files under these directories. For example,

  PackageDirectories {
    * = lib/thrift/packages
    * = lib/common
  }

= PackageExcludeDirs

Exclude file under these directories. Same as --exclude-dir command line
option. For example,

  PackageExcludeDirs {
    * = scripts/
    * = tests/
  }

= PackageExcludeFiles

Exclude these files. Same as --exclude-file command line option. For example,

  PackageExcludeFiles {
    * = scripts/delete_user.php
    * = tests/create_database.php
  }

= PackageExcludeStaticFiles

Exclude files matching these patterns from static file content cache. A static
content cache creates one single file from all static contents, including
css, js, html, images and other MIME format files. When building static
content cache, the compiler will look for all non-PHP files to try to include
them. This option allows one to exclude certain files. Same as
--exclude-static-pattern command line option. For example,

  PackageExcludeStaticFiles {
    * = .*\\.js
    * = .*\\.css
  }

= CachePHPFile

Default is false. Whether to include PHP files in static content cache.

= ScalarArrayFileCount

Default is 1. Scalar arrays are arrays with scalar values, including literal
strings, numbers and scalar arrays as keys and values, so their values are
entirely determined at compilation time. We pre-generate these arrays during
program startup time just once to avoid initialization costs. These scalar
arrays are groups into their own files. This option specifies how many files
to generate or split up scalar arrays, so we can compile them faster. For
large project with a lot of scalar arrays, use a higher value. Then each file
is smaller. When using distcc, normally it finishes compilation faster.

= ScalarArrayOverflowLimit

Default is 2000. Some scalar arrays can become extremely large when nested
with lots of elements and levels. This option controls how to split them up
into small ones, having sub-arrays defined by their own, so to flatten array
data structure for faster compilation.

= LiteralStringFileCount

Default is 1. Similar to scalar arrays, we have literal strings pre-generated
in files. This option specifies how many of these files are generated for
faster compilation.

= EnableShortTags

Default is true. Is &lt;? allowed with PHP code?

= EnableXHP

Whether to enable XHP extension. XHP adds some syntax sugar to allow better and
safer HTML templating. For more information, search XHP.

= NativeXHP

Whether to use HPHP to directly handle XHP.

= ParserThreadCount

How many threads to use when parsing PHP files. By default, it's 2x CPU count.

= FlibDirectory

Facebook specific. Ignore.

= PregenerateCPP

Default is false. In case clustering of output files has been requested and this
option is set to true, the files are pre-generated in memory in order to perform
a more precise partitioning.

= GCCOptimization

Default is disabled. This option allows one to selectively decrease the compiler
optimization level for long functions. It is specified as:

  GCCOptimization {
    O2 = X
    O1 = Y
    O0 = Z
  }

where X, Y, Z are the minimum length functions must have (measured as line
count) for their optimization level to be decreased respectively to O2, O1,
O0. Note that all these parameters are optional, so it is possible for example
to only specify O1 and O0 but not O2, meaning that O2 will never be used as an
optimization level. In general it is expected that if specified, the minimum
line counts will be increasing for a decreasing optimization level.

= DynamicFunctionPrefix

Deprecating. These are options for specifying which functions may be called
dynamically. This turned out to be hard to configure, and it's replaced by
AllDynamics.

= DynamicFunctionPostfix

Deprecating. These are options for specifying which functions may be called
dynamically. This turned out to be hard to configure, and it's replaced by
AllDynamics.

= DynamicMethodPrefix

Deprecating. These are options for specifying which methods may be called
dynamically. This turned out to be hard to configure, and it's replaced by
AllDynamics.

= ConstantFunctions

This is a list of functions and static class methods that may be assumed to
always return a constant value. Each entry should be in the format
function_name|serialized_value, like so:

  ConstantFunctions {
    * = SomeClass::GetString|s:8:"a_string";
    * = some_function|b:0;
  }

= CodeGeneration

Under "CodeGeneration", one can specify alternative name prefixes that are
used in different places of code generation.

- IdPrefix
- LambdaPrefix
- UserFilePrefix