hphp/doc/options.compiler

   1 <h2>Configurable Options for Compiler</h2>
   2
   3 Compiler has a --config option to take a configuration file in HDF format, and
   4 it has a --config-value to take ad-hoc configurable options in HDF format.
   5 This documentation describes what's available for both of them.
   6
   7 When in doubt, look for how these options are parsed in compiler/options.cpp.
   8
   9 = UseHHBBC
  10
  11 Default is true. Determines whether whole-program optimizations should
  12 performed on the bytecode using hhbbc as part of the hphp run. When
  13 false, you can still separately run hhbbc on the repo that hphp
  14 produces (useful for development on hhbbc itself).
  15
  16 = AllDynamic
  17
  18 Default is false. When turned on, all functions and methods can be invoked
  19 dynamically even without a literal string. When turned off, some dynamic
  20 function calls may fail, if compiler is not able to tell that function may be
  21 invoked dynamically. Recommend to turn on this switch.
  22
  23 = AllVolatile
  24
  25 Default is false. When turned on, order-dependent function or class declaration
  26 vs. existence testing can work. When turned off, some function_exists(),
  27 class_exists(), get_defined_functions() or get_declared_classes() may return
  28 different results than PHP does. Most programs don't have dependencies on their
  29 behaviors, so this is recommended to leave as off.
  30
  31 = EnableEval
  32
  33 Default is 0, eval() will throw a fatal error. When 1, eval() is supported in
  34 a limited way, mixed together with compiled program. When 2, eval() is fully
  35 supported as an interpreter mode.
  36
  37 = IncludeRoots
  38
  39 Only needed when --input-list is not used, and --parse-on-demand is turned on.
  40 In this case, compiler needs to understand every single include. Currently it
  41 only understands these formats (compiler/analysis/dependency_graph.cpp),
  42
  43   include 'literal_file_path';
  44   include $SOME_VARIABLE . 'literal_file_path';
  45
  46 IncludeRoots is designed to look up $SOME_VARIABLE in the second case, so to
  47 resolve file paths at compilation time. It will look like this,
  48
  49   IncludeRoots {
  50     * {
  51       root = $SOME_VARIABLE
  52       path = lib/
  53     }
  54     * {
  55       root = $SOME_OTHER_ROOT
  56       path = lib/another
  57     }
  58   }
  59
  60 = AutoloadRoots
  61
  62 Only needed when --input-list is not used, and --parse-on-demand is turned on.
  63 In this case, compiler needs to understand all autoloads to find a class file.
  64 It will look like this,
  65
  66   AutoloadRoots {
  67     * {
  68       root = $GLOBALS['THRIFT_AUTOLOAD']
  69       path = lib/thrift/packages
  70     }
  71   }
  72
  73 With the above configuration, whenever a class name is added to the array,
  74
  75   $GLOBALS['THRIFT_AUTOLOAD'][] = 'myclass';
  76
  77 It will be searched against the specified path. Please note that, this is
  78 not a good way to work around the problem. --include-list is recommended to
  79 specify all class files explicitly. Then this option isn't needed.
  80
  81 = IncludeSearchPaths
  82
  83 Only needed when --input-list is not used, and --parse-on-demand is turned on.
  84 Specifies more paths to search for include files. For example,
  85
  86   IncludeSearchPaths {
  87     * = lib/thrift/packages
  88     * = lib/common
  89   }
  90
  91 = PackageDirectories
  92
  93 Add all PHP files under these directories. For example,
  94
  95   PackageDirectories {
  96     * = lib/thrift/packages
  97     * = lib/common
  98   }
  99
 100 = PackageExcludeDirs
 101
 102 Exclude file under these directories. Same as --exclude-dir command line
 103 option. For example,
 104
 105   PackageExcludeDirs {
 106     * = scripts/
 107     * = tests/
 108   }
 109
 110 = PackageExcludeFiles
 111
 112 Exclude these files. Same as --exclude-file command line option. For example,
 113
 114   PackageExcludeFiles {
 115     * = scripts/delete_user.php
 116     * = tests/create_database.php
 117   }
 118
 119 = PackageExcludeStaticFiles
 120
 121 Exclude files matching these patterns from static file content cache. A static
 122 content cache creates one single file from all static contents, including
 123 css, js, html, images and other MIME format files. When building static
 124 content cache, the compiler will look for all non-PHP files to try to include
 125 them. This option allows one to exclude certain files. Same as
 126 --exclude-static-pattern command line option. For example,
 127
 128   PackageExcludeStaticFiles {
 129     * = .*\\.js
 130     * = .*\\.css
 131   }
 132
 133 = CachePHPFile
 134
 135 Default is false. Whether to include PHP files in static content cache.
 136
 137 = ScalarArrayFileCount
 138
 139 Default is 1. Scalar arrays are arrays with scalar values, including literal
 140 strings, numbers and scalar arrays as keys and values, so their values are
 141 entirely determined at compilation time. We pre-generate these arrays during
 142 program startup time just once to avoid initialization costs. These scalar
 143 arrays are groups into their own files. This option specifies how many files
 144 to generate or split up scalar arrays, so we can compile them faster. For
 145 large project with a lot of scalar arrays, use a higher value. Then each file
 146 is smaller. When using distcc, normally it finishes compilation faster.
 147
 148 = ScalarArrayOverflowLimit
 149
 150 Default is 2000. Some scalar arrays can become extremely large when nested
 151 with lots of elements and levels. This option controls how to split them up
 152 into small ones, having sub-arrays defined by their own, so to flatten array
 153 data structure for faster compilation.
 154
 155 = LiteralStringFileCount
 156
 157 Default is 1. Similar to scalar arrays, we have literal strings pre-generated
 158 in files. This option specifies how many of these files are generated for
 159 faster compilation.
 160
 161 = EnableHipHopSyntax
 162
 163 Default is false. Enables new syntax, including yield, new type names for
 164 function parameter, function return and class variable type hints (string,
 165 int, boolean, etc..), new array types (vector, map, set).
 166
 167 = EnableHipHopExperimentalSyntax
 168
 169 Default is false. Enables experimental syntax, including type hints for local
 170 variables and global variables.
 171
 172 = EnableShortTags
 173
 174 Default is true. Is &lt;? allowed with PHP code?
 175
 176 = EnableAspTags
 177
 178 Default is false. Is &lt;% %&gt; allowed with PHP code?
 179
 180 = EnableXHP
 181
 182 Whether to enable XHP extension. XHP adds some syntax sugar to allow better and
 183 safer HTML templating. For more information, search XHP.
 184
 185 = NativeXHP
 186
 187 Whether to use HPHP to directly handle XHP.
 188
 189 = ParserThreadCount
 190
 191 How many threads to use when parsing PHP files. By default, it's 2x CPU count.
 192
 193 = FlibDirectory
 194
 195 Facebook specific. Ignore.
 196
 197 = GenerateDocComments
 198
 199 Default is true. Whether to store doc comments in class map, so they can be
 200 queried from reflection.
 201
 202 = PregenerateCPP
 203
 204 Default is false. In case clustering of output files has been requested and this
 205 option is set to true, the files are pre-generated in memory in order to perform
 206 a more precise partitioning.
 207
 208 = GCCOptimization
 209
 210 Default is disabled. This option allows one to selectively decrease the compiler
 211 optimization level for long functions. It is specified as:
 212
 213   GCCOptimization {
 214     O2 = X
 215     O1 = Y
 216     O0 = Z
 217   }
 218
 219 where X, Y, Z are the minimum length functions must have (measured as line
 220 count) for their optimization level to be decreased respectively to O2, O1,
 221 O0. Note that all these parameters are optional, so it is possible for example
 222 to only specify O1 and O0 but not O2, meaning that O2 will never be used as an
 223 optimization level. In general it is expected that if specified, the minimum
 224 line counts will be increasing for a decreasing optimization level.
 225
 226 = DynamicFunctionPrefix
 227
 228 Deprecating. These are options for specifying which functions may be called
 229 dynamically. This turned out to be hard to configure, and it's replaced by
 230 AllDynamics.
 231
 232 = DynamicFunctionPostfix
 233
 234 Deprecating. These are options for specifying which functions may be called
 235 dynamically. This turned out to be hard to configure, and it's replaced by
 236 AllDynamics.
 237
 238 = DynamicMethodPrefix
 239
 240 Deprecating. These are options for specifying which methods may be called
 241 dynamically. This turned out to be hard to configure, and it's replaced by
 242 AllDynamics.
 243
 244 = DynamicInvokeFunctions
 245
 246 This is a list of functions which we should assume can be used with
 247 fb_rename_function or fb_intercept in RepoAuthoritative mode.  (Note
 248 that they can be used with fb_rename_function even if
 249 EvalJitEnableRenameFunction is false at runtime.)
 250
 251 We should probably rename this option to something like
 252 InterceptableFunctions, but we haven't yet.
 253
 254 = ConstantFunctions
 255
 256 This is a list of functions and static class methods that may be assumed to
 257 always return a constant value. Each entry should be in the format
 258 function_name|serialized_value, like so:
 259
 260   ConstantFunctions {
 261     * = SomeClass::GetString|s:8:"a_string";
 262     * = some_function|b:0;
 263   }
 264
 265 = CodeGeneration
 266
 267 Under "CodeGeneration", one can specify alternative name prefixes that are
 268 used in different places of code generation.
 269
 270 - IdPrefix
 271 - LambdaPrefix
 272 - UserFilePrefix