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 = EnableShortTags
 162
 163 Default is true. Is &lt;? allowed with PHP code?
 164
 165 = EnableXHP
 166
 167 Whether to enable XHP extension. XHP adds some syntax sugar to allow better and
 168 safer HTML templating. For more information, search XHP.
 169
 170 = NativeXHP
 171
 172 Whether to use HPHP to directly handle XHP.
 173
 174 = ParserThreadCount
 175
 176 How many threads to use when parsing PHP files. By default, it's 2x CPU count.
 177
 178 = FlibDirectory
 179
 180 Facebook specific. Ignore.
 181
 182 = PregenerateCPP
 183
 184 Default is false. In case clustering of output files has been requested and this
 185 option is set to true, the files are pre-generated in memory in order to perform
 186 a more precise partitioning.
 187
 188 = GCCOptimization
 189
 190 Default is disabled. This option allows one to selectively decrease the compiler
 191 optimization level for long functions. It is specified as:
 192
 193   GCCOptimization {
 194     O2 = X
 195     O1 = Y
 196     O0 = Z
 197   }
 198
 199 where X, Y, Z are the minimum length functions must have (measured as line
 200 count) for their optimization level to be decreased respectively to O2, O1,
 201 O0. Note that all these parameters are optional, so it is possible for example
 202 to only specify O1 and O0 but not O2, meaning that O2 will never be used as an
 203 optimization level. In general it is expected that if specified, the minimum
 204 line counts will be increasing for a decreasing optimization level.
 205
 206 = DynamicFunctionPrefix
 207
 208 Deprecating. These are options for specifying which functions may be called
 209 dynamically. This turned out to be hard to configure, and it's replaced by
 210 AllDynamics.
 211
 212 = DynamicFunctionPostfix
 213
 214 Deprecating. These are options for specifying which functions may be called
 215 dynamically. This turned out to be hard to configure, and it's replaced by
 216 AllDynamics.
 217
 218 = DynamicMethodPrefix
 219
 220 Deprecating. These are options for specifying which methods may be called
 221 dynamically. This turned out to be hard to configure, and it's replaced by
 222 AllDynamics.
 223
 224 = DynamicInvokeFunctions
 225
 226 This is a list of functions which we should assume can be used with
 227 fb_rename_function or fb_intercept in RepoAuthoritative mode.  (Note
 228 that they can be used with fb_rename_function even if
 229 EvalJitEnableRenameFunction is false at runtime.)
 230
 231 We should probably rename this option to something like
 232 InterceptableFunctions, but we haven't yet.
 233
 234 = ConstantFunctions
 235
 236 This is a list of functions and static class methods that may be assumed to
 237 always return a constant value. Each entry should be in the format
 238 function_name|serialized_value, like so:
 239
 240   ConstantFunctions {
 241     * = SomeClass::GetString|s:8:"a_string";
 242     * = some_function|b:0;
 243   }
 244
 245 = CodeGeneration
 246
 247 Under "CodeGeneration", one can specify alternative name prefixes that are
 248 used in different places of code generation.
 249
 250 - IdPrefix
 251 - LambdaPrefix
 252 - UserFilePrefix