{namespace buck.buckconfig}

/**
 * @param title
 */
{template .section}
  <h2 id="{$title}">[{$title}]</h2>
  <p>
{/template}

/***/
{template .soyweb}
  {call buck.page}
    {param title: '.buckconfig' /}
    {param navid: 'concept_buckconfig' /}
    {param description}
      An optional file that contains configuration information for Buck.
    {/param}
    {param prettify: true /}
    {param content}
<p>

The root of your project must contain a configuration file
named <code>.buckconfig</code>. If present, Buck will read this file
before executing its business logic so that any customizations specified
in <code>.buckconfig</code> will take effect. This file uses the
{sp}<a href="http://en.wikipedia.org/wiki/INI_file">INI file format</a>
with a few extensions discussed below.

<p>

Although the INI format only recognizes strings as values, Buck allows
fields to be parsed as a list of strings, separated by a separator character.
For example, a field containing command line flags to be passed to a compiler
may parse its value as a list of strings, separated by space, so
that <code>-foo -bar</code> is parsed as a list of two strings, instead of
a single string.

<p>

To ensure that any character can be encoded in a .buckconfig value, Buck
allows values or part of values to be quoted by surrounding them by double
quotes. Inside double quotes, escape sequences can be used to encode
characters that would otherwise be problematic to use in values. The
following escape sequences are supported:

<table summary="Escape sequences in .buckconfig"><tr>
<td>\\</td><td>backslash</td>
</tr><tr>
<td>\"</td><td>double quote</td>
</tr><tr>
<td>\n</td><td>newline</td>
</tr><tr>
<td>\r</td><td>carriage return</td>
</tr><tr>
<td>\t</td><td>tab</td>
</tr><tr>
<td>\x##</td><td>unicode character with code point ## (in hex)</td>
</tr><tr>
<td>\u####</td><td>unicode character with code point #### (in hex)</td>
</tr><tr>
<td>\U########</td><td>unicode character with code point ######## (in hex)</td>
</tr></table>

<p>

In addition, when a field is parsed as a list instead of a string,
the separator character is only interpreted as a separator when it occurs
outside double quotes. For example, if <em>flags</em> is a field being
interpreted as a list of strings separated by
spaces, <code>flags=-foo "-bar \u0429"</code> will result in two
strings: <q>foo</q> and <q>-bar &#1065;</q>.

<p>
Finally, other fields' values can be interpolated by including <code>$(config &lt;section&gt;.&lt;field&gt;)</code> inside of a value. For example, if you want to use the go vendor path in a custom setting, you can use:
</p>

<p>
{literal}<pre class="prettyprint lang-ini">
[custom_section]
custom_value = $(config go.vendor_path)
</pre>
{/literal}
</p>

<h2>.buckconfig.local</h2>

The root of your project may also contain a second configuration file
named <code>.buckconfig.local</code>. Its format is exactly the same as
that of <code>.buckconfig</code>, but any definition in <code>.buckconfig.local</code>{sp}
will override that of <code>.buckconfig</code>. In practice, <code>.buckconfig</code> will be a
version-controlled file that contains settings that are applicable to all team members (such as
standard includes for build files), whereas <code>.buckconfig.local</code> will be excluded from
version control because it contains user-specific overrides (such as personal aliases).

<p>

If a configuration option is not found in the project's <code>.buckconfig</code>, it will fall
back to a <code>.buckconfig</code> file and <code>.buckconfig.d</code> directory in your home
directory. Each of those has the same format as a <code>.buckconfig</code> file but will have
any settings overridden by project-specific configurations. If you have build issues, make sure
that there is nothing in your <code>.buckconfig</code> or <code>.buckconfig.d</code> that could
be conflicting with the project you're trying to build.

<h2>Sections</h2>

The following sections are recognized by Buck:

<p>

{foreach $name in [
    'adb',
    'alias',
    'android',
    'apple',
    'build',
    'buildfile',
    'cache',
    'client',
    'color',
    'credentials',
    'cxx',
    'd',
    'doctor',
    'download',
    'go',
    'groovy',
    'halide',
    'intellij',
    'java',
    'kotlin',
    'httpserver',
    'log',
    'lua',
    'maven_repositories',
    'ndk',
    'ocaml',
    'parser',
    'project',
    'python',
    'resources',
    'resources_per_rule',
    'rust',
    'sandbox',
    'test',
    'thrift',
    'tools',
    'ui',
    'unknown_flavors_messages',
    'worker',
    ]}
  <a href="#{$name}"><code>[{$name}]</code></a><br>
{/foreach}

{call buckconfig.section}
  {param name: 'adb' /}
  {param description}
    This section configures adb behavior.
  {/param}
{/call}

{call buckconfig.entry}
  {param section: 'adb' /}
  {param name: 'adb_restart_on_failure' /}
  {param example_value: 'true' /}
  {param description}
    This specifies whether to restart adb on failure or not.
  {/param}
{/call}

{call buckconfig.entry}
  {param section: 'adb' /}
  {param name: 'multi_install_mode' /}
  {param example_value: 'false' /}
  {param description}
    This specifies whether multi-install mode is enabled or disabled by default.
  {/param}
{/call}

{call buckconfig.section}
  {param name: 'alias' /}
  {param description}
<p>
  This section contains definitions of {call buck.build_target/} aliases.
</p>

{literal}<pre class="prettyprint lang-ini">
[alias]
  app     = //apps/myapp:app
  apptest = //apps/myapp:test
</pre>{/literal}

<p>
  These aliases can then be used from the command line:
</p>

{literal}<pre class="prettyprint">
$ buck build app
$ buck test apptest
</pre>{/literal}

<p>
  You can also suffix aliases with flavors:
</p>

{literal}<pre class="prettyprint">
$ buck build app#src_jar
# This will expand the alias and effectively build the target returned by:
$ buck targets --resolve-alias app#src_jar
//apps/myapp:app#src_jar
</pre>{/literal}
  {/param}
{/call}

{call buckconfig.section}
  {param name: 'android' /}
  {param description}
    This section configures android-specific build behavior.
  {/param}
{/call}

{call buckconfig.entry}
  {param section: 'android' /}
  {param name: 'build_tools_version' /}
  {param example_value: '23.0.1' /}
  {param description}
    This specifies the version of the Android SDK Build-tools that all Android code in the project
    should be built against.  By default, Buck will select the newest version found on the system.
  {/param}
{/call}

{call buckconfig.entry}
  {param section: 'android' /}
  {param name: 'sdk_path' /}
  {param example_value: '/Library/Android/sdk' /}
  {param description}
    This specifies the absolute path to the Android SDK that all Android code in the project should
    be built against.  This is equivalent to setting the environment variable
    <code>ANDROID_SDK=/Library/Android/sdk</code>. The environment variables
    <code>ANDROID_SDK</code> and <code>ANDROID_HOME</code> both supercede the buckconfig setting.
    The default is empty.
  {/param}
{/call}

{call buckconfig.entry}
  {param section: 'android' /}
  {param name: 'target' /}
  {param example_value: 'Google Inc.:Google APIs:21' /}
  {param description}
    This specifies the version of the Android SDK that all Android code in the project should be
    built against.  Even if not specified, the version that Buck chose to use will be printed to the
    console during the build.  A list of valid values on your system can be found by running{sp}
    <code>android list targets --compact</code>.
  {/param}
{/call}

{call buckconfig.section}
  {param name: 'apple' /}
  {param description}
    This section includes settings that control settings that are specific to Apple platform rules.
  {/param}
{/call}

{call buckconfig.entry}
  {param section: 'apple' /}
  {param name: 'xcode_developer_dir' /}
  {param example_value: 'path/to/developer/directory' /}
  {param description}
    By default, Buck will use the output of <code>xcode-select --print-path</code> to determine
    where Xcode's developer directory is.  However, you can specify a directory in the config to
    override whatever value that would return.
  {/param}
{/call}

{call buckconfig.entry}
  {param section: 'apple' /}
  {param name: 'xcode_developer_dir_for_tests' /}
  {param example_value: 'path/to/developer/directory/for_tests' /}
  {param description}
    Optionally override the Xcode developer directory for running tests, if you want them to be run
    with a different Xcode version than the version used for building.  If absent, falls back
    to <code>xcode_developer_dir</code> and finally <code>xcode-select --print-path</code>.
  {/param}
{/call}

{call buckconfig.entry}
  {param section: 'apple' /}
  {param name: 'target_sdk_version' /}
  {param description}
    For each platform, you can specify the target SDK version to use.  The format is
    {sp}<code>{lb}platform{rb}_target_sdk_version</code>.
  {/param}
  {param raw_example}
{literal}<pre class = "prettyprint lang-ini">
[apple]
  iphonesimulator_target_sdk_version = 7.0
  iphoneos_target_sdk_version = 7.0
  macosx_target_sdk_version = 10.9
</pre>{/literal}
  {/param}
{/call}

{call buckconfig.entry}
  {param section: 'apple' /}
  {param name: 'xctool_path' /}
  {param example_value: 'path/to/binary/of/xctool' /}
  {param description}
    If you want to run tests with Buck, you will need to get
    {sp}<a href="https://github.com/facebook/xctool"><code>xctool</code></a> and tell Buck where to
    find it.  This setting lets you specify a path to a binary.  You should use either this setting
    or {call buckconfig.apple_xctool_zip_target /}.
  {/param}
{/call}

{call buckconfig.entry}
  {param section: 'apple' /}
  {param name: 'xctool_zip_target' /}
  {param example_value: '//path/to/target/that/creates:xctool-zip' /}
  {param description}
    If you want to run tests with Buck, you will need to get
    {sp}<a href="https://github.com/facebook/xctool"><code>xctool</code></a> and tell Buck where to
    find it.  This setting lets you specify a {call buck.build_target /}.  You should use either
    this setting or {call buckconfig.apple_xctool_path /}.
  {/param}
{/call}

{call buckconfig.entry}
  {param section: 'apple' /}
  {param name: 'codesign' /}
  {param example_value: '//path/to/target/that/creates:codesign' /}
  {param description}
    To override a default path to <code>codesign</code>, set this setting to either a file path or
    buck target.
  {/param}
{/call}

{call buckconfig.entry}
  {param section: 'apple' /}
  {param name: 'test_log' /}
  {param description}
    When running Apple tests via <code>xctool</code>, Buck can set environment variables to
    tell the tests where to write debug logs and what log level to use. By default, Buck
    tells <code>xctool</code> to set two environment variables named <code>FB_LOG_DIRECTORY</code>
    and <code>FB_LOG_LEVEL</code> when running tests which you can read from your test environment:

{literal}<pre class="prettyprint lang-sh">
  FB_LOG_DIRECTORY=buck-out/gen/path/to/logs
  FB_LOG_LEVEL=debug
</pre>{/literal}

    You can override the default names for these environment variables and the value for the debug
    log level via the following config settings:
  {/param}
  {param raw_example}
{literal}<pre class="prettyprint lang-init">
  [apple]
    test_log_directory_environment_variable=MY_LOG_DIRECTORY
    test_log_level_environmant_variable=MY_LOG_LEVEL
    test_log_level=verbose
</pre>{/literal}
  {/param}
{/call}

{call buckconfig.entry}
  {param section: 'apple' /}
  {param name: 'xctool_default_destination_specifier' /}
  {param example_value: 'platform=iOS Simulator' /}
  {param description}
    This setting is passed directly to <code>xctool</code>, and then to <code>xcodebuild</code> as
    the <code>-destination</code> argument.  See the
    {sp}<a href="https://developer.apple.com/library/mac/documentation/Darwin/Reference/ManPages/man1/xcodebuild.1.html">
    man page</a> for the proper syntax.
  {/param}
{/call}

{call buckconfig.entry}
  {param section: 'apple' /}
  {param name: 'default_debug_info_format_for_binaries' /}
  {param example_value: 'NONE' /}
  {param description}
    <code>default_debug_info_format_for_binaries</code> setting controls the default debug info format that
    is used when building binary targets. If you don't specify it, <code>DWARF_AND_DSYM</code> value will be used.
    You can disable debug data by specifying <code>NONE</code> value. You can produce unstripped binary by specifying
    <code>DWARF</code> value.
  {/param}
{/call}

{call buckconfig.entry}
  {param section: 'apple' /}
  {param name: 'default_debug_info_format_for_libraries' /}
  {param example_value: 'DWARF' /}
  {param description}
    <code>default_debug_info_format_for_libraries</code> setting controls the default debug info format that
    is used when building dynamic library targets. If you don't specify it, <code>DWARF</code> value will be used.
    You can disable debug data by specifying <code>NONE</code> value. You can produce dSYM file for the library by specifying
    <code>DWARF_AND_DSYM</code> value.
  {/param}
{/call}

{call buckconfig.entry}
  {param section: 'apple' /}
  {param name: 'default_debug_info_format_for_tests' /}
  {param example_value: 'DWARF_AND_DSYM' /}
  {param description}
    <code>default_debug_info_format_for_tests</code> setting controls the default debug info format that
    is used when building test targets. If you don't specify it, <code>DWARF</code> value will be used.
    You can disable debug data by specifying <code>NONE</code> value. You can produce dSYM file by specifying
    <code>DWARF_AND_DSYM</code> value.
  {/param}
{/call}

{call buckconfig.entry}
  {param section: 'apple' /}
  {param name: 'device_helper_path' /}
  {param example_value: 'third-party/fbsimctl/fbsimctl' /}
  {param description}
    If you want to have Buck be able to install to devices, you need to provide the path to the{sp}
    <a href="https://github.com/facebook/FBSimulatorControl/"><code>fbsimctl</code></a> binary.
  {/param}
{/call}

{call buckconfig.entry}
  {param section: 'apple' /}
  {param name: 'provisioning_profile_read_command' /}
  {param example_value: 'path/to/command --arg1 --arg2' /}
  {param description}
    Specifies a command with any optional arguments that Buck will use to decode Apple's
    provisioning profiles for iOS builds.  The full path of the provisioning profile will be
    appended after the command and any arguments specified here.  If unspecified,
    Buck will use <code>openssl smime -inform der -verify -noverify -in</code>.
  {/param}
{/call}

{call buckconfig.entry}
  {param section: 'apple' /}
  {param name: 'provisioning_profile_search_path' /}
  {param example_value: 'path/to/provisioning/profiles' /}
  {param description}
    Specifies a path where Buck will look for provisioning profiles (files with extension <code>
    .mobileprovision</code>) that it can use to provision the application to be used on a device.
    You can specify either an absolute path or one relative to the project root.  If unspecified,
    Buck will look in <code>~/Library/MobileDevice/Provisioning Profiles</code>.
  {/param}
{/call}

{call buckconfig.entry}
  {param section: 'apple' /}
  {param name: 'code_sign_identities_command' /}
  {param example_value: 'path/to/command --arg1 --arg2' /}
  {param description}
    Specifies a command with any optional arguments that Buck will use to get
    the current key fingerprints available for code signing.  This command should
    output a list of hashes and common names to standard output in the same format
    as <code>security find-identity -v -p codesigning</code>.  If unspecified,
    Buck will use <code>security find-identity -v -p codesigning</code>.
  {/param}
{/call}

{call buckconfig.entry}
  {param section: 'apple' /}
  {param name: 'use_header_maps_in_xcode' /}
  {param example_value: 'false' /}
  {param description}
    Xcode projects generated by Buck by default use header maps for header search paths. This speeds
    up builds for large projects over using regular directory header search paths, but breaks some
    Xcode features, like header file name autocompletion. If that is an issue, use the following
    option to disable the use of header maps.
  {/param}
{/call}

{call buckconfig.entry}
  {param section: 'apple' /}
  {param name: 'asset_catalog_validation' /}
  {param example_value: 'XCODE' /}
  {param description}
    Buck can check errors in .xcassets' contents that can later cause silent failures, like having
    multiple images with the same name or missing <code>Contents.json</code> files. To add extra
    validation above what Xcode does, set this option to <code>STRICT</code>.
  {/param}
{/call}

{call buckconfig.entry}
  {param section: 'apple' /}
  {param name: '*_package_command' /}
  {param description}
    Specify a custom command to run for <code>apple_package()</code> rules. The syntax of this field
    is similar to the <code>cmd</code> field of {call buck.genrule /}, and supports some expansions:

    <dl>
        <dt><code>SRCS</code></dt>
        <dd>
            Expands to the absolute path of the <code>bundle</code> argument output to the
            <code>apple_package()</code> rule.
        </dd>
        <dt><code>OUT</code></dt>
        <dd>
            Expands to the output file for the <code>apple_package()</code> rule. The file specified
            by this variable must always be written by this command.
        </dt>
        <dt><code>SDKROOT</code></dt>
        <dd>
            Expands to the SDK root directory for the requested SDK.  For example,
            <code>/Applications/Xcode.app/Contents/Developer/Platforms/iPhoneOS.platform/Developer/SDKs/iPhoneOS9.2.sdk/</code>.
        </dd>
    </dl>

    Note that since strings in the config can be quoted, literal quotes can only be written by
    quoting the string and use escaped quotes.

    If omitted, this will revert to the built-in behavior.

    When this option is specified, <code>*_package_extension</code> must also be specified.
  {/param}
  {param raw_example}
      {literal}
      <pre class = "prettyprint lang-ini">
[apple]
  iphoneos_package_command = "\"$PLATFORM_DIR/Developer/usr/bin/PackageApplication\" \"$SRCS\" \"$OUT\""
  iphoneos_package_extension = zip</pre>
      {/literal}
  {/param}
{/call}

{call buckconfig.entry}
  {param section: 'apple' /}
  {param name: '*_package_extension' /}
  {param description}
    Specify the output extension for custom <code>apple_package</code> rules configured with
    <code>*_package_command</code>.

    This config option must be specified when <code>*_package_command</code> is specified, or both
    omitted.
  {/param}
{/call}

{call buckconfig.entry}
  {param section: 'apple' /}
  {param name: '*_toolchains_override' /}
  {param description}
    Specify a comma-delimited custom list of toolchains to use when building with a particular SDK.

    This is the Buck equivalent of the <code>TOOLCHAINS</code> environment variable
    when building with Xcode.

    If omitted, this will revert to the built-in behavior.
  {/param}
{/call}

{call buckconfig.section}
  {param name: 'build' /}
  {param description}
    This section includes settings that control build engine behavior.
  {/param}
{/call}

{call buckconfig.entry}
  {param section: 'build' /}
  {param name: 'engine' /}
  {param example_value: 'shallow' /}
  {param description}
    This has two possible values that change the behavior of how Buck operates when building a{sp}
    {call buck.build_target /}:
    <ul>
      <li>
        <code>shallow</code> (default): only the required transitive dependencies of a{sp}
        {call buck.build_target /} are materialized locally. Cache hits can result in missing
        transitive dependencies that are not needed for the final output.
      </li>
      <li>
        <code>deep</code>: ensure that all transitive dependencies of a {call buck.build_target /}
        {sp}are materialized locally.
      </li>
    </ul>
  {/param}
{/call}

{call buckconfig.entry}
  {param section: 'build' /}
  {param name: 'depfiles' /}
  {param example_value: 'enabled' /}
  {param description}
    Configures the use of dependency files for rules that support them.  This is an optimization
    that is useful when dependencies are over-specified and the rule can dynamically determine the
    subset of dependencies it actually needs.  The possible values are:
    <ul>
      <li>
        <code>enabled</code> (default): Use dependency files to avoid unnecessary rebuilds.
      </li>
      <li>
        <code>cache</code>: Use dependency files to avoid unnecessary rebuilds and to store/fetch
        artifacts to/from the cache.
      </li>
      <li>
        <code>disabled</code>: Do not use dependency files for rebuild detection.
      </li>
    </ul>
  {/param}
{/call}

{call buckconfig.entry}
  {param section: 'build' /}
  {param name: 'max_depfile_cache_entries' /}
  {param example_value: '256' /}
  {param description}
    Sets the maximum size of the depfile cache for each input source file.  This is only used when
    setting {call buckconfig.build_depfiles /} to <code>cache</code>.  An ideal setting for this
    should be big enough for the working set of all possible header states that a given unchanged
    source file uses.
  {/param}
{/call}

{call buckconfig.entry}
  {param section: 'build' /}
  {param name: 'type' /}
  {param example_value: 'RELEASE_PEX' /}
  {param description}
    Sets the type of the build that buck has been built with. This allows buck to distinguish
    different kinds of builds. When you run <code>ant</code> locally, this will be automatically
    set to <code>LOCAL_ANT</code>. When you build buck using buck locally, e.g. <code>buck build buck</code>,
    this will be automatically set to <code>LOCAL_PEX</code>. If you are deploying buck through
    central deployment system, you may want to set build type to <code>RELEASE_PEX</code>:{sp}
    <pre>buck build buck --config build.type=RELEASE_PEX</pre>
    <p><b>Note:</b> this setting does not affect how buck builds other rules. It only affects
    the way how <i>buck will build buck</i>.</p>
  {/param}
{/call}

{call buckconfig.entry}
  {param section: 'build' /}
  {param name: 'threads' /}
  {param example_value: '4' /}
  {param description}
    Sets the maximum number of threads to use for building.  By default, Buck uses the number of
    available cores multipled by <code>1.25</code>.
  {/param}
{/call}

{call buckconfig.entry}
  {param section: 'build' /}
  {param name: 'thread_core_ratio' /}
  {param example_value: '0.75' /}
  {param description}
    Sets the maximum number of threads to use for building as a ratio of the number of available
    cores (e.g. <code>0.75</code> on a 4 core machine would limit building
    to 3 threads, or a value of <code>1.25</code> on the same machine would attempt to use 5
    threads).
  {/param}
{/call}

{call buckconfig.entry}
  {param section: 'build' /}
  {param name: 'thread_core_ratio_max_threads' /}
  {param example_value: '10' /}
  {param description}
    The maximum number of threads to use when calculating the number of build threads from
    thread_core_ratio. (e.g. a value of 2 on a 4 core machine would ensure that, at most, 2 threads
    were used, and value of 10 on a 40 core machine would ensure that, at most, 10 threads were used).
  {/param}
{/call}

{call buckconfig.entry}
  {param section: 'build' /}
  {param name: 'thread_core_ratio_min_threads' /}
  {param example_value: '1' /}
  {param description}
    The minimum number of threads to use when calculating the number of build threads from
    thread_core_ratio. (e.g. a value of 1 on a 4 core machine would ensure that, at least, 1 thread
    was used, and value of 4 on a 40 core machine would ensure that, at least, 10 threads were used).
  {/param}
{/call}

{call buckconfig.entry}
  {param section: 'build' /}
  {param name: 'thread_core_ratio_reserved_cores' /}
  {param example_value: '1' /}
  {param description}
    Limit the maximum number of build threads to be the number of detected cores minus this value.
    (e.g. a value of 1 on a 4 core machine would ensure that, at most, 3 cores were used, and a
    value of 2 on a 40 core machine would ensure that, at most, 38 cores were used).
  {/param}
{/call}

{call buckconfig.entry}
  {param section: 'build' /}
  {param name: 'network_threads' /}
  {param example_value: '8' /}
  {param description}
    The number of threads to be used for network I/O. The default value is number of cores of the
    machine.
  {/param}
{/call}

{call buckconfig.entry}
  {param section: 'build' /}
  {param name: 'rule_key_caching' /}
  {param example_value: 'true' /}
  {param description}
    Enables caching of rule key calculations between builds when using the Buck daemon.
  {/param}
{/call}

{call buckconfig.section}
  {param name: 'buildfile' /}
  {param description}
    This section includes settings that control build file behavior.
  {/param}
{/call}

{call buckconfig.entry}
  {param section: 'buildfile' /}
  {param name: 'includes' /}
  {param example_value: '//core/DEFS' /}
  {param description}
    This sets a list of paths to files that will be automatically included by every build file.
    This is equivalent to calling {call buck.fn_include_defs /} in every build file.
  {/param}
{/call}

{call buckconfig.entry}
  {param section: 'buildfile' /}
  {param name: 'name' /}
  {param example_value: 'TARGETS' /}
  {param description}
    The name of {call buck.build_file /}s within a project. This defaults to <code>BUCK</code>.
  {/param}
{/call}

{call buckconfig.section}
  {param name: 'cache' /}
  {param description}
    This section configures build artifact caching, which can be disabled (default), on the
    filesystem, or in a distributed cache that can be shared among developers.  Note that the{sp}
    {call buckconfig.cache_mode /} setting determines which other properties, if any, are relevant
    to the caching configuration; the irrelevant properties are ignored.
  {/param}
{/call}

{call buckconfig.entry}
  {param section: 'cache' /}
  {param name: 'mode' /}
  {param example_value: 'dir, http, sqlite' /}
  {param description}
    A comma-separated set of caching policies to use.  The valid values are:
    <ul>
      <li>
        <code>dir</code> (default): Use a directory-based cache on the local filesystem.
      </li>
      <li>
        <code>http</code>: Use an http-based cache.
      </li>
      <li>
        <code>sqlite</code>: Use a SQLite-based cache that inlines small artifacts in the database
        and stores large artifacts on the local filesystem.
      </li>
    </ul>
  {/param}
{/call}

{call buckconfig.entry}
  {param section: 'cache' /}
  {param name: 'dir' /}
  {param example_value: 'buck-cache' /}
  {param description}
    The directory path relative to the project root that is used for directory-based caching (
    {call buckconfig.cache_mode /} must contain <code>dir</code>).  This defaults to{sp}
    <code>buck-out/cache</code>.
  {/param}
{/call}

{call buckconfig.entry}
  {param section: 'cache' /}
  {param name: 'dir_max_size' /}
  {param example_value: '10GB' /}
  {param description}
    The maximum cache size for directory-based caching ({call buckconfig.cache_mode /} must contain
    {sp}<code>dir</code>).  The default size is unlimited.
  {/param}
{/call}

{call buckconfig.entry}
  {param section: 'cache' /}
  {param name: 'dir_mode' /}
  {param example_value: 'readwrite' /}
  {param description}
    Dictates if the cache is <code>readonly</code>, <code>passthrough</code> or
    {sp}<code>readwrite</code> (default) when using directory-based caching
    {sp}({call buckconfig.cache_mode /} must contain <code>dir</code>).
  {/param}
{/call}

{call buckconfig.entry}
  {param section: 'cache' /}
  {param name: 'dir_cache_names' /}
  {param description}
    A comma-separated list of names used to configure multiple dir caches.  The caches will be used{sp}
    <b>serially</b> in the order in which their names are specified here.  If an artifact is found
    further along in the list, an attempt to store it in the caches earlier in the list will be
    made.  In the following example, if the artifact is found in the <code>warm</code> cache, it
    will not be stored in the <code>local</code> cache. Note: if <code>[cache] dir</code> or <code>[cache] dir_mode</code>{sp}
    are found, then Buck will fall back to single dir cache more and <code>[cache] dir_cache_names</code>{sp}
    will be completely ignored.
  {/param}
  {param raw_example}
{literal}<pre class="prettyprint lang-ini">
[cache]
    mode = dir
    dir_cache_names = warm, local

[cache#warm]
    dir = ~/prefetched_cache
    dir_mode = readonly

[cache#local]
    dir = ~/buck_cache
    dir_mode = readwrite
</pre>{/literal}
  {/param}
{/call}

{call buckconfig.entry}
  {param section: 'cache' /}
  {param name: 'http_url' /}
  {param example_value: 'http://localhost:8080' /}
  {param description}
    The URL to use to contact the cache when using http-based caching{sp}
    ({call buckconfig.cache_mode /} must contain <code>http</code>).  Buck communicates with the
    server using a <a href="{ROOT}concept/http_cache_api.html">simple API</a>.

  {/param}
{/call}

{call buckconfig.entry}
  {param section: 'cache' /}
  {param name: 'http_mode' /}
  {param example_value: 'readwrite' /}
  {param description}
    Dictates if the cache is <code>readonly</code> or <code>readwrite</code> (default) when using
    http-based caching ({call buckconfig.cache_mode /} must contain <code>http</code>).
  {/param}
{/call}

{call buckconfig.entry}
  {param section: 'cache' /}
  {param name: 'http_read_headers' /}
  {param example_value: 'User-Agent: buck' /}
  {param description}
    A semicolon-separated set of HTTP headers to use when reading from the cache when using
    http-based caching ({call buckconfig.cache_mode /} must contain <code>http</code>).  The default
    is no headers.
  {/param}
{/call}

{call buckconfig.entry}
  {param section: 'cache' /}
  {param name: 'http_write_headers' /}
  {param example_value: 'Authorization: XXXXXXX; User-Agent: buck' /}
  {param description}
    A semicolon-separated set of HTTP headers to use when writing to the cache when using http-based
    caching ({call buckconfig.cache_mode /} must contain <code>http</code>).  The default is no
    headers.
  {/param}
{/call}

{call buckconfig.entry}
  {param section: 'cache' /}
  {param name: 'http_timeout_seconds' /}
  {param example_value: '3' /}
  {param description}
    Dictates the timeout per connection when using http-based caching{sp}
    ({call buckconfig.cache_mode /} must contain <code>http</code>).
    It will be the default value for http_connect_timeout_seconds, http_read_timeout_seconds,
    http_write_timeout_seconds if they're not set.  The default is <code>3</code>.
  {/param}
{/call}

{call buckconfig.entry}
  {param section: 'cache' /}
  {param name: 'http_connect_timeout_seconds' /}
  {param example_value: '3' /}
  {param description}
    Dictates the timeout on http connect when using http-based caching{sp}
    If the value is not set, it will try to use the value set for http_timeout_seconds
    then use the default value 3</code>.
  {/param}
{/call}

{call buckconfig.entry}
  {param section: 'cache' /}
  {param name: 'http_read_timeout_seconds' /}
  {param example_value: '3' /}
  {param description}
    Dictates the timeout on http writes when using http-based caching{sp}
    If the value is not set, it will try to use the value set for http_timeout_seconds
    then use the default value 3</code>.
  {/param}
{/call}

{call buckconfig.entry}
  {param section: 'cache' /}
  {param name: 'http_write_timeout_seconds' /}
  {param example_value: '3' /}
  {param description}
    Dictates the timeout on http reads when using http-based caching{sp}
    If the value is not set, it will try to use the value set for http_timeout_seconds
    then use the default value 3</code>.
  {/param}
{/call}

{call buckconfig.entry}
  {param section: 'cache' /}
  {param name: 'http_max_concurrent_writes' /}
  {param example_value: '1' /}
  {param description}
    The numver of writer threads to use to upload to the http cache when using http-based caching
    {sp}({call buckconfig.cache_mode /} must contain <code>http</code>).  The default is{sp}
    <code>1</code>.  Note that when using multiple http caches (see below), the writer thread pool
    is shared between them all.
  {/param}
{/call}

{call buckconfig.entry}
  {param section: 'cache' /}
  {param name: 'http_writer_shutdown_timeout_seconds' /}
  {param example_value: '1800' /}
  {param description}
    The length of time to wait after the build completes for any remaining http cache uploads to
    complete before forecfully shutting down the writer thread pool when using http-based caching
    {sp}({call buckconfig.cache_mode /} must contain <code>http</code>).  The default is{sp}
    <code>1800</code> (30 minutes).
  {/param}
{/call}

{call buckconfig.entry}
  {param section: 'cache' /}
  {param name: 'http_error_message_format' /}
  {param example_value}
    {literal}The cache named {cache_name} encountered an error: {error_message}{/literal}
  {/param}
  {param description}
    This setting allows for the customization of how http cache errors appear to the user.  If the
    text <code>{lb}cache_name{rb}</code> is present, it will be replaced with the name of the cache.
    If the text {sp}<code>{lb}error_message{rb}</code>, it will be replaced with the error message.
  {/param}
{/call}

{call buckconfig.entry}
  {param section: 'cache' /}
  {param name: 'http_max_store_size' /}
  {param example_value: '5000000' /}
  {param description}
    The max size in bytes that an artifact can be to get pushed to an http cache.
  {/param}
{/call}

{call buckconfig.entry}
  {param section: 'cache' /}
  {param name: 'serve_local_cache' /}
  {param example_value: 'false' /}
  {param description}
    Make the directory-based cache ({call buckconfig.cache_mode /} must contain <code>dir</code>)
    available to other hosts on the network via Buck's HTTP server (enabled under{sp}
    {call buckconfig.httpserver /}).
  {/param}
{/call}

{call buckconfig.entry}
  {param section: 'cache' /}
  {param name: 'served_local_cache_mode' /}
  {param example_value: 'readwrite' /}
  {param description}
    Dictates if the cache is <code>readonly</code> (default) or <code>readwrite</code> when{sp}
    {call buckconfig.cache_serve_local_cache /} is enabled.
  {/param}
{/call}

{call buckconfig.entry}
  {param section: 'cache' /}
  {param name: 'sqlite_inlined_size' /}
  {param example_value: '10kB' /}
  {param description}
    The maximum size for artifacts to be inlined ({call buckconfig.cache_mode /} must contain
    {sp}<code>sqlite</code>).  The default size is 40B.
  {/param}
{/call}

{call buckconfig.entry}
  {param section: 'cache' /}
  {param name: 'sqlite_max_size' /}
  {param example_value: '10GB' /}
  {param description}
    The maximum cache size for SQLite-based caching ({call buckconfig.cache_mode /} must contain
    {sp}<code>sqlite</code>).  The default size is unlimited.
  {/param}
{/call}

{call buckconfig.entry}
  {param section: 'cache' /}
  {param name: 'sqlite_mode' /}
  {param example_value: 'readwrite' /}
  {param description}
    Dictates if the cache is <code>readonly</code>, <code>passthrough</code> or
    {sp}<code>readwrite</code> (default) when using SQLite-based caching
    {sp}({call buckconfig.cache_mode /} must contain <code>sqlite</code>).
  {/param}
{/call}

{call buckconfig.entry}
  {param section: 'cache' /}
  {param name: 'sqlite_cache_names' /}
  {param description}
    A comma-separated list of names used to configure multiple SQLite caches.  The caches will be used{sp}
    <b>serially</b> in the order in which their names are specified here.  If an artifact is found
    further along in the list, an attempt to store it in the caches earlier in the list will be
    made.  In the following example, if the artifact is found in the <code>warm</code> cache, it
    will not be stored in the <code>local</code> cache.
  {/param}
  {param raw_example}
{literal}<pre class="prettyprint lang-ini">
[cache]
    mode = sqlite
    sqlite_cache_names = warm, local

[cache#warm]
    sqlite_mode = readonly

[cache#local]
    sqlite_mode = readwrite
</pre>{/literal}
  {/param}
{/call}

{call buckconfig.entry}
  {param section: 'cache' /}
  {param name: 'two_level_cache_enabled' /}
  {param example_value: 'false' /}
  {param description}
    Have the Buck client perform 2-level stores and lookups on the artifacts.
    Every cache operation consists of 2 steps: content hash-based and
    RuleKey-based. This makes it easier to reuse locally cached artifacts
    across different buck versions at the expense of higher latencies in the
    case where artifacts are not present in the local cache.
  {/param}
{/call}

{call buckconfig.entry}
  {param section: 'cache' /}
  {param name: 'two_level_cache_minimum_size' /}
  {param example_value: '1024' /}
  {param description}
    When performing a store artifacts smaller than this size will be stored
    directly, without the content hash redirection.
  {/param}
{/call}

{call buckconfig.entry}
  {param section: 'cache' /}
  {param name: 'two_level_cache_maximum_size' /}
  {param example_value: '1024' /}
  {param description}
    When performing a store artifacts bigger than this size will be stored
    directly, without the content hash redirection.
  {/param}
{/call}

{call buckconfig.entry}
  {param section: 'cache' /}
  {param name: 'action_graph_cache_check_enabled' /}
  {param example_value: 'false' /}
  {param description}
    It enables an integrity checking mechanism in the action graph cache that compares the a newly
    generated action graph with the one already in the cache in the case of a cache hit. If the
    graphs do not match the build is stopped and the mismatching rules are printed and logged.
  {/param}
{/call}

{call buckconfig.entry}
	{param section: 'cache' /}
	{param name: 'max_action_graph_cache_entries' /}
	{param example_value: '3' /}
	{param description}
		Sets the maximum number of action graphs to cache. After this number, the least-recently-used
		graph will be evicted. Defaults to 1.
	{/param}
{/call}

{call buckconfig.entry}
  {param section: 'cache' /}
  {param name: 'load_balancing_type' /}
  {param example_value: 'SINGLE_SERVER, CLIENT_SLB' /}
  {param description}
    Decides whether the distributed cache connects to a single url or
    it has a pool of servers and chooses which one to use based on
    client side load balancing.

    NOTE: 'slb_*' configs only apply when CLIENT_SLB is enabled.
  {/param}
{/call}

{call buckconfig.entry}
  {param section: 'cache' /}
  {param name: 'slb_server_pool' /}
  {param example_value: 'http://my.server.one/,http://my.server.two' /}
  {param description}
  A comma separated list of server URLs of valid servers. The client
  side loadbalancer will try to pick the best server to connect to for every
  single connection.
  {/param}
{/call}

{call buckconfig.entry}
  {param section: 'cache' /}
  {param name: 'slb_ping_endpoint' /}
  {param example_value: '/ping.php' /}
  {param description}
  The client side loadbalancer will use this endpoint to check whether the
  server is in healthy state or not. It will also be used to measure request
  latency.
  {/param}
{/call}

{call buckconfig.entry}
  {param section: 'cache' /}
  {param name: 'slb_health_check_internal_millis' /}
  {param example_value: '1000' /}
  {param description}
  The timeout in milliseconds between two consecutive client side loadbalancer
  health checks to the slb_server_pool.
  {/param}
{/call}

{call buckconfig.entry}
  {param section: 'cache' /}
  {param name: 'slb_timeout_millis' /}
  {param example_value: '1000' /}
  {param description}
  The connection timeout per health request made to each of the slb_server_pool
  servers. Any server that fails to respond within this period will be
  deemed unhealthy and not be used for cache requests.
  {/param}
{/call}

{call buckconfig.entry}
  {param section: 'cache' /}
  {param name: 'slb_error_check_time_range_millis' /}
  {param example_value: '300000' /}
  {param description}
  The error rate to each individual server taking part in the slb_server_pool
  will be measured in the time range/window specified by this config.
  In different words, 'errors per second' is computed only for the last
  slb_error_check_time_range_millis.
  {/param}
{/call}

{call buckconfig.entry}
  {param section: 'cache' /}
  {param name: 'slb_max_error_percentage' /}
  {param example_value: '0.1' /}
  {param description}
  The max error percentage allowed within the last
  slb_error_check_time_range_millis that is acceptable to keep a particular
  server marked as healthy and usable by the loadbalancer.

  Expects a float value in the interval [0, 1].
  {/param}
{/call}

{call buckconfig.entry}
  {param section: 'cache' /}
  {param name: 'slb_latency_check_time_range_millis' /}
  {param example_value: '300000' /}
  {param description}
  The latency to each individual server taking part in the slb_server_pool
  will be measured in the time range/window specified by this config.
  In different words, 'server latency' is computed only for the last
  slb_latency_check_time_range_millis.
  {/param}
{/call}

{call buckconfig.entry}
  {param section: 'cache' /}
  {param name: 'slb_max_acceptable_latency_millis' /}
  {param example_value: '1000' /}
  {param description}
  If the latency of a ping request to a server in slb_server_pool is higher than
  this, the server is deemed unhealthy and not used for cache operations.
  {/param}
{/call}

{call buckconfig.section}
  {param name: 'credentials' /}
  {param description}
    This section configures credentials to be used when fetching from
    authenticated Maven repositories via HTTPS.
    <p>
    For a repository <code>repo</code> appearing in{sp}
    {call buckconfig.maven_repositories /}, Buck reads the values of
    {sp}<code>repo_user</code> and <code>repo_pass</code> in this section
    (if present), and passes them to the server using {sp}
    <a href="https://en.wikipedia.org/wiki/Basic_access_authentication#Client_side">basic access authentication</a>
    {sp}when fetching.
    <p>
    Note that authenticating in this way over plain HTTP connections is
    disallowed and will result in an error.

{literal}<pre class="prettyprint lang-ini">
[maven_repositories]
  repo = https://example.com/repo
[credentials]
  repo_user = joeuser
  repo_pass = hunter2
</pre>{/literal}
  {/param}
{/call}

{call buckconfig.section}
  {param name: 'client' /}
  {param description}
    This section includes settings that provide information about the caller.
    Although these can be specified in <code>.buckconfig</code>, in practice,
    they are specified exclusively on the command line:
    <pre class="prettyprint lang-sh">
$ buck --config client.id=tool-making-this-buck-invocation build buck
    </pre>
  {/param}
{/call}

{call buckconfig.entry}
  {param section: 'client' /}
  {param name: 'id' /}
  {param description}
  It is good practice for tools that call Buck to identify themselves via{sp}
  <code>--config client.id=&lt;toolname></code>. This makes it easier for
  developers to audit the source of Buck invocations that they did not make
  directly.
  <p>
  Note that the value of <code>client.id</code> is not factored into a build
  rule's cache key. It is purely for auditing purposes.
  {/param}
{/call}

{call buckconfig.entry}
  {param section: 'client' /}
  {param name: 'skip-action-graph-cache' /}
  {param description}
  When Buck is run as a daemon, it caches the last Action Graph it used for a
  build so that if the next build identifies the same set of targets, the
  [possibly expensive] Action Graph construction step can be avoided. Because
  only the last Action Graph is cached, it may be costly to interleave a small
  build job among a series of incremental builds of an expensive rule:
  {literal}<pre class="prettyprint lang-sh">
$ buck build //big:expensive-rule            # Initial Action Graph.
$ buck build //big:expensive-rule            # Action Graph is reused.
$ buck build //library#compilation-database  # Evicts costly Action Graph.
$ buck build //big:expensive-rule            # Action Graph is rebuilt.</pre>
  {/literal}
  <p>
  Although this scenario may sound contrived, it is very common when other tools
  may also be running <code>buck build</code> in the background. Work done by
  IDEs and linters frequently fall into this category. In this case, the best
  practice is to add <code>--config
  client.skip-action-graph-cache=true</code> for any sort of "one-off" build
  for which the cost of caching the Action Graph for the new build likely
  outweights the benefit of evicting the Action Graph from the previous build.
  As this is commonly the case for tools, this flag is frequently used in
  concert with <code>--config client.id</code>:
  {literal}<pre class="prettyprint lang-sh">
$ buck build //big:expensive-rule            # Initial Action Graph.
$ buck build //big:expensive-rule            # Action Graph is reused.
$ buck build \                               # Cached Graph is unaffected.
    --config client.skip-action-graph-cache=true \
    --config client.id=nuclide \
    //library#compilation-database
$ buck build //big:expensive-rule            # Action Graph is reused.</pre>
  {/literal}
  {/param}
{/call}

{call buckconfig.section}
  {param name: 'color' /}
  {param description}
    This section configures colored output of Buck.
  {/param}
{/call}

{call buckconfig.entry}
  {param section: 'color' /}
  {param name: 'ui' /}
  {param example_value: 'true' /}
  {param description}
    Enables (default) or disables colorized output in the terminal.
  {/param}
{/call}

{call buckconfig.section}
  {param name: 'd' /}
  {param description}
    This section configures how code written in D is compiled.
  {/param}
{/call}

{call buckconfig.entry}
  {param section: 'd' /}
  {param name: 'base_compiler_flags' /}
  {param example_value: '-I/some/path -g -O3' /}
  {param description}
    Flags to pass to every invocation of the D compiler.
    This is a space-separated list.
    It defaults to an empty list.
  {/param}
{/call}

{call buckconfig.entry}
  {param section: 'd' /}
  {param name: 'compiler' /}
  {param example_value: '/opt/dmd/bin/dmd' /}
  {param description}
    Path to the D compiler.
    If this parameter is not specified, Buck attempts to find the D
    compiler automatically.
  {/param}
{/call}

{call buckconfig.entry}
  {param section: 'd' /}
  {param name: 'library_path' /}
  {param example_value: '/usr/local/lib:/opt/dmd/lib' /}
  {param description}
    Directories to be searched for the D runtime libraries.
    This is a colon-separated list.
    If this parameter is not specified, Buck attempts to detect the
    location of the libraries automatically.
  {/param}
{/call}

{call buckconfig.entry}
  {param section: 'd' /}
  {param name: 'linker_flags' /}
  {param example_value: '"-L/path to phobos" -lphobos2' /}
  {param description}
    Flags to pass to the linker when linking D code into an executable.
    This is a space-separated list.
    If omitted, this value is constructed from d.library_path.
  {/param}
{/call}

{call buckconfig.section}
  {param name: 'download' /}
  {param description}
    This section configures downloading from the network during {call buck.cmd_fetch /}.
  {/param}
{/call}

{call buckconfig.entry}
  {param section: 'download' /}
  {param name: 'proxy' /}
  {param description}
    Buck will attempt to fetch files from the network, however, if you happen to be behind a]
    firewall, this may not work correctly.  You can supply a proxy when downloading from HTTP[S]
    servers with these three settings.  Valid types for <code>proxy_type</code> are{sp}
    <code>HTTP</code> (default) and <code>SOCKS</code>.  These values correspond to {sp}
    <a href="http://docs.oracle.com/javase/8/docs/api/java/net/Proxy.Type.html">Java's
    Proxy.Type</a>.
  {/param}
  {param raw_example}
{literal}<pre class="prettyprint lang-ini">
[download]
    proxy_host=proxy.example.com
    proxy_port=8080
    proxy_type=HTTP
</pre>{/literal}
  {/param}
{/call}

{call buckconfig.entry}
  {param section: 'download' /}
  {param name: 'maven_repo' /}
  {param example_value: 'https://repo1.maven.org/maven2' /}
  {param description}
    If a remote file's URL starts with <code>mvn:</code>, that file (usually a jar) is supposed to
    come from a maven repo.  You can specify the repo to download from here, or by setting one or
    more repositories in {call buckconfig.maven_repositories /}.
  {/param}
{/call}

{call buckconfig.entry}
  {param section: 'download' /}
  {param name: 'max_number_of_retries' /}
  {param example_value: '3' /}
  {param description}
    In case buck is unable to download a file, it will retry specified number of times before
    giving up. By default it's not set, so Buck is not going to retry failed downloads.
  {/param}
{/call}

{call buckconfig.section}
  {param name: 'cxx' /}
  {param description}
    <p>
      This section configures the paths to the C++ and C toolchains' binaries and the default flags
      to pass to all invocations of them.
    </p>
  {/param}
{/call}

{call buckconfig.entry}
  {param section: 'cxx' /}
  {param name: 'cpp' /}
  {param example_value: '/usr/bin/gcc' /}
  {param description}
    The path to the C preprocessor.
  {/param}
{/call}

{call buckconfig.entry}
  {param section: 'cxx' /}
  {param name: 'cc' /}
  {param example_value: '/usr/bin/gcc' /}
  {param description}
    The path to the C compiler.
  {/param}
{/call}

{call buckconfig.entry}
  {param section: 'cxx' /}
  {param name: 'ld' /}
  {param example_value: '/usr/bin/g++' /}
  {param description}
    The path to the C/C++ linker driver.
  {/param}
{/call}

{call buckconfig.entry}
  {param section: 'cxx' /}
  {param name: 'linker_platform' /}
  {param example_value: 'MACOS' /}
  {param description}
    The platform for the linker.  Normally this is autodetected based on the system, but it useful
    to set when cross compiling.  Valid values are:
    <ul>
      <li><code>DARWIN</code></li>
      <li><code>GNU</code></li>
      <li><code>WINDOWS</code></li>
    </ul>
  {/param}
{/call}

{call buckconfig.entry}
  {param section: 'cxx' /}
  {param name: 'cxxpp' /}
  {param example_value: '/usr/bin/g++' /}
  {param description}
    The path to the C++ preprocessor.
  {/param}
{/call}

{call buckconfig.entry}
  {param section: 'cxx' /}
  {param name: 'cxx' /}
  {param example_value: '/usr/bin/g++' /}
  {param description}
    The path to the C++ compiler.
  {/param}
{/call}

{call buckconfig.entry}
  {param section: 'cxx' /}
  {param name: 'aspp' /}
  {param example_value: '/usr/bin/gcc' /}
  {param description}
    The path to the assembly preprocessor.
  {/param}
{/call}

{call buckconfig.entry}
  {param section: 'cxx' /}
  {param name: 'as' /}
  {param example_value: '/usr/bin/as' /}
  {param description}
    The path to the assembler.
  {/param}
{/call}

{call buckconfig.entry}
  {param section: 'cxx' /}
  {param name: 'ar' /}
  {param example_value: '/usr/bin/ar' /}
  {param description}
    The path to the archiver.
  {/param}
{/call}

{call buckconfig.entry}
  {param section: 'cxx' /}
  {param name: 'archiver_platform' /}
  {param example_value: 'MACOS' /}
  {param description}
    The platform for the archiver.  Normally this is autodetected based on the system, but it useful
    to set when cross compiling.  Valid values are:
    <ul>
      <li><code>LINUX</code></li>
      <li><code>MACOS</code></li>
      <li><code>FREEBSD</code></li>
      <li><code>WINDOWS</code></li>
    </ul>
  {/param}
{/call}

{call buckconfig.entry}
  {param section: 'cxx' /}
  {param name: 'cppflags' /}
  {param example_value: '-Wall' /}
  {param description}
    The flags to pass to the C preprocessor.
  {/param}
{/call}

{call buckconfig.entry}
  {param section: 'cxx' /}
  {param name: 'cflags' /}
  {param example_value: '-Wall' /}
  {param description}
    The flags to pass to the C compiler and preprocessor.
  {/param}
{/call}

{call buckconfig.entry}
  {param section: 'cxx' /}
  {param name: 'ldflags' /}
  {param example_value: '--strip-all' /}
  {param description}
    The flags to pass to the linker.
  {/param}
{/call}

{call buckconfig.entry}
  {param section: 'cxx' /}
  {param name: 'cxxppflags' /}
  {param example_value: '-Wall' /}
  {param description}
    The flags to pass to the C++ preprocessor.
  {/param}
{/call}

{call buckconfig.entry}
  {param section: 'cxx' /}
  {param name: 'cxxflags' /}
  {param example_value: '-Wall' /}
  {param description}
    The flags to pass to the C++ compiler and preprocessor.
  {/param}
{/call}

{call buckconfig.entry}
  {param section: 'cxx' /}
  {param name: 'asppflags' /}
  {param example_value: '-W' /}
  {param description}
    The flags to pass to the assembly preprocessor.
  {/param}
{/call}

{call buckconfig.entry}
  {param section: 'cxx' /}
  {param name: 'asflags' /}
  {param example_value: '-W' /}
  {param description}
    The flags to pass to the assembler and assembly preprocessor.
  {/param}
{/call}

{call buckconfig.entry}
  {param section: 'cxx' /}
  {param name: 'arflags' /}
  {param example_value: '-X32_64' /}
  {param description}
    The flags to pass to the archiver.
  {/param}
{/call}

{call buckconfig.entry}
  {param section: 'cxx' /}
  {param name: 'ranlibflags' /}
  {param example_value: '--plugin someplugin' /}
  {param description}
    The flags to pass to the archive indexer.
  {/param}
{/call}

{call buckconfig.entry}
  {param section: 'cxx' /}
  {param name: 'gtest_dep' /}
  {param example_value: '//third-party/gtest:gtest' /}
  {param description}
    The {call buck.build_rule /} to compile the <a href="https://github.com/google/googletest" target="_blank">Google Test</a> framework.
  {/param}
  {param raw_example}
    <p>
      If you had your Google Test code in <code>third-party/gtest/</code>, the {call buck.build_file /} in that directory would look something like this:
    </p>
    <pre class="prettyprint lang-py">
{literal}
cxx_library(
  name = 'gtest',
  srcs = [
    'googletest/src/gtest-all.cc',
    'googlemock/src/gmock-all.cc',
    'googlemock/src/gmock_main.cc',
  ],
  header_namespace = '',
  exported_headers = subdir_glob([
    ('googletest/include', '**/*.h'),
    ('googlemock/include', '**/*.h'),
  ]),
  headers = subdir_glob([
    ('googletest', 'src/*.cc'),
    ('googletest', 'src/*.h'),
    ('googlemock', 'src/*.cc'),
    ('googlemock', 'src/*.h'),
  ]),
  platform_linker_flags = [
    ('android', []),
    ('', ['-lpthread']),
  ],
  visibility = [
    '//test/...',
  ],
)
{/literal}
    </pre>
  {/param}
{/call}

{call buckconfig.entry}
  {param section: 'cxx' /}
  {param name: 'untracked_headers' /}
  {param example_value: 'error' /}
  {param description}
    How to handle header files that get included in a preprocessing step, but which aren't explicitly owned by
    any dependencies.  By default, Buck sandboxes headers into symlink trees, but file relative inclusion and
    explicit preprocessor flags can still cause untracked headers to get pulled into the build which can break
    caching.
    <ul>
      <li>
        <code>ignore</code> (default): Untracked headers are allowed in the build.
      </li>
      <li>
        <code>warn</code>: Print a warning to the console when an untracked header is used.
      </li>
      <li>
        <code>error</code>: Fail the build when an untracked header is used.
      </li>
    </ul>
  {/param}
{/call}

{call buckconfig.entry}
  {param section: 'cxx' /}
  {param name: 'untracked_headers_whitelist' /}
  {param example_value: '/usr/include/.*, /usr/local/include/.*' /}
  {param description}
    A list of regexes which match headers to exempt from untracked header verification.
  {/param}
{/call}

{call buckconfig.entry}
  {param section: 'cxx' /}
  {param name: 'pch_enabled' /}
  {param example_value: 'false' /}
  {param description}
    <p>
    Whether prefix headers used by a cxx_library or other such build rule's
    {sp}<code>prefix_header</code>{sp} parameter should be separately
    precompiled, and used in that rule's build.
    </p>

    <p>
    If this is disabled, the prefix header is included as-is, without
    precompilation.
    </p>

    <p>
    Default is <code>true</code>.
    </p>
  {/param}
{/call}

{call buckconfig.entry}
  {param section: 'cxx' /}
  {param name: 'link_weight' /}
  {param example_value: '3' /}
  {param description}
    The number of jobs that each C/C++ link rule consumes when running.
    By default, this is <code>1</code>, but this can overriden to change
    how many link rules can execute in parallel for a given <code>-j</code>
    value.
    This is useful for builds with large I/O intensive static links where using
    a lower <code>-j</code> value is undesirable (since it reduces the parallelism
    for other build rule types).
  {/param}
{/call}

{call buckconfig.entry}
  {param section: 'cxx' /}
  {param name: 'cache_links' /}
  {param example_value: 'false' /}
  {param description}
    C/C++ link rules are cached by default.  However, static C/C++ link jobs
    can take up lots of cache space and also get relatively low hit rates, so
    this config option provides a way to disable caching of all C/C++ link rules
    in the build.
  {/param}
{/call}

{call buckconfig.section}
  {param name: 'doctor' /}
  {param description}
    This section defines variables that are associated with command <code>doctor</code>.
  {/param}
{/call}

{call buckconfig.entry}
  {param section: 'doctor' /}
  {param name: 'protocol' /}
  {param example_value: 'json' /}
  {param description}
    The protocol of communication, it can be either simple or json.
  {/param}
{/call}

{call buckconfig.entry}
  {param section: 'doctor' /}
  {param name: 'endpoint_url' /}
  {param example_value: 'http://localhost:4545' /}
  {param description}
    The address of the remote endpoint that the request will go. This needs to be defined in order
    for the command to work.
  {/param}
{/call}

{call buckconfig.entry}
  {param section: 'doctor' /}
  {param name: 'endpoint_timeout_ms' /}
  {param example_value: '15' /}
  {param description}
    The timeout in milliseconds before giving up contacting the analysis endpoint.
  {/param}
{/call}

{call buckconfig.entry}
  {param section: 'doctor' /}
  {param name: 'endpoint_extra_request_args' /}
  {param example_value: 'ref=>1245,token=>42' /}
  {param description}
    This sections of keys and values is added as parameters to the POST request send to the doctor
    remote endpoint.
  {/param}
{/call}

{call buckconfig.entry}
  {param section: 'doctor' /}
  {param name: 'report_upload_path' /}
  {param example_value: 'http://localhost:4546' /}
  {param description}
    The address of the remote endpoint the report will be uploaded.
  {/param}
{/call}

{call buckconfig.entry}
  {param section: 'doctor' /}
  {param name: 'report_max_size' /}
  {param example_value: '512MB' /}
  {param description}
    The maximum size that the report endpoint can handle before giving up and storing it only
    locally.
  {/param}
{/call}

{call buckconfig.entry}
  {param section: 'doctor' /}
  {param name: 'report_timeout_ms' /}
  {param example_value: '15' /}
  {param description}
    The timeout in milliseconds before giving up contacting the report endpoint.
  {/param}
{/call}

{call buckconfig.entry}
  {param section: 'doctor' /}
  {param name: 'report_max_upload_retries' /}
  {param example_value: '2' /}
  {param description}
    Times to try to upload to the report endpoint.
  {/param}
{/call}

{call buckconfig.entry}
  {param section: 'doctor' /}
  {param name: 'report_extra_info_command' /}
  {param example_value: '/custom/script/to/run.sh' /}
  {param description}
    An extra command that the report should and attach the information to the uploaded report.
  {/param}
{/call}

{call buckconfig.section}
  {param name: 'go' /}
  {param description}
    This section defines the Go toolchain.  By default Buck will try to discovery the Go compiler
    and linker from the <code>go</code> tool found in your <code>PATH</code>.
  {/param}
{/call}

{call buckconfig.entry}
  {param section: 'go' /}
  {param name: 'root' /}
  {param example_value: '/opt/golang/libexec' /}
  {param description}
    If you have a non-standard Go install, you will need to set the Go root.  The root should
    contain <code>pkg</code> and <code>bin</code> directories.
  {/param}
{/call}

{call buckconfig.entry}
  {param section: 'go' /}
  {param name: 'prefix' /}
  {param example_value: 'github.com/facebook/buck' /}
  {param description}
    For interoperability with the go tool, you may specify a prefix for your default package names.
  {/param}
{/call}

{call buckconfig.entry}
  {param section: 'go' /}
  {param name: 'tool' /}
  {param example_value: '/usr/local/bin/go' /}
  {param description}
    You can specify the path to find the <code>go</code> tool.  This in turn will allow Buck to
    discover the compiler/linker by default.  This defaults to <code>${lb}go.root{rb}/bin/go</code>.
  {/param}
{/call}

{call buckconfig.entry}
  {param section: 'go' /}
  {param name: 'compiler' /}
  {param example_value: '/usr/local/libexec/go/pkg/tool/darwin_amd64/compile' /}
  {param description}
    The full path to the Go compiler.  This is normally automatically discovered.
  {/param}
{/call}

{call buckconfig.entry}
  {param section: 'go' /}
  {param name: 'assembler' /}
  {param example_value: '/usr/local/libexec/go/pkg/tool/darwin_amd64/asm' /}
  {param description}
    The full path to the Go assembler.  This is normally automatically discovered.
  {/param}
{/call}

{call buckconfig.entry}
  {param section: 'go' /}
  {param name: 'packer' /}
  {param example_value: '/usr/local/libexec/go/pkg/tool/darwin_amd64/pack' /}
  {param description}
    The full path to the Go packer.  This is normally automatically discovered.
  {/param}
{/call}

{call buckconfig.entry}
  {param section: 'go' /}
  {param name: 'linker' /}
  {param example_value: '/usr/local/libexec/go/pkg/tool/darwin_amd64/link' /}
  {param description}
    The full path to the Go linker.  This is normally automatically discovered.
  {/param}
{/call}

{call buckconfig.entry}
  {param section: 'go' /}
  {param name: 'vendor_path' /}
  {param example_value: 'third-party/go' /}
  {param description}
    A list of colon (:) separated list of directories to include for including in the importmap for
    Go dependencies.  Packages in these directories are allowed to be imported given just the
    relative path to the package.  This is similar to how 'vendor' directories work.

    e.g you can use <code>import golang.org/x/net</code> for a package that lives in
    <code><vendor_path>/golang.org/x/net</code>.
  {/param}
{/call}

{call buckconfig.section}
  {param name: 'groovy' /}
  {param description}
    This section configures the <a href="http://groovy-lang.org/">Groovy</a> toolchain.
  {/param}
{/call}

{call buckconfig.entry}
  {param section: 'groovy' /}
  {param name: 'groovy_home' /}
  {param example_value: '/path/to/groovy_home'/}
  {param description}
    This defines the value of <code>GROOVY_HOME</code> that Buck should use. If it is not provided,
    Buck will use the system's <code>GROOVY_HOME</code> by default.
  {/param}
{/call}

{call buckconfig.section}
  {param name: 'halide' /}
  {param description}
    This section configures the <a href="http://halide-lang.org/">Halide</a> platform mappings and
    toolchain.
  {/param}
{/call}

{call buckconfig.entry}
  {param section: 'halide' /}
  {param name: 'target' /}
  {param description}
    This defines the C++ platform flavor to Halide target mapping.  Each key should begin with the
    prefix <code>target_</code>, followed by the flavor name.  The corresponding value should be the
    Halide target string to use when building for that flavor.
  {/param}
  {param raw_example}
{literal}<pre class="prettyprint lang-ini">
[halide]
  target_iphonesimulator-x86_64 = x86-64-osx
  target_iphoneos-arm64         = arm-64-ios
</pre>{/literal}
  {/param}
{/call}

{call buckconfig.entry}
  {param section: 'halide' /}
  {param name: 'xcode_compile_script' /}
  {param example_value: '//path/to/script.sh' /}
  {param description}
    The optional path to a shell script which should be used for invoking the Halide AOT "compiler"
    when building projects that include Halide targets in Xcode.
  {/param}
{/call}

{call buckconfig.section}
  {param name: 'intellij' /}
  {param description}
    This section configures a project generated for IntelliJ IDEA by <code>buck project</code> command.
  {/param}
{/call}

{call buckconfig.entry}
  {param section: 'intellij' /}
  {param name: 'default_android_manifest_path' /}
  {param example_value: 'shared/AndroidManifest.xml' /}
  {param description}
    The default manifest file that should be used in Android IntelliJ modules when buck cannot
    detect the correct manifest to use.
  {/param}
{/call}

{call buckconfig.entry}
  {param section: 'intellij' /}
  {param name: 'jdk_name' /}
  {param example_value: 'Java SDK 1.6' /}
  {param description}
    IntelliJ project SDK name.
  {/param}
{/call}

{call buckconfig.entry}
  {param section: 'intellij' /}
  {param name: 'jdk_type' /}
  {param example_value: 'Android SDK or JavaSDK' /}
  {param description}
    IntelliJ project SDK type.
  {/param}
{/call}

{call buckconfig.entry}
  {param section: 'intellij' /}
  {param name: 'android_module_sdk_type' /}
  {param example_value: 'Android SDK' /}
  {param description}
    Default Android SDK type for android modules.
  {/param}
{/call}

{call buckconfig.entry}
  {param section: 'intellij' /}
  {param name: 'android_module_sdk_name' /}
  {param example_value: 'Android API 23 Platform' /}
  {param description}
    Default Android SDK name for android modules.
  {/param}
{/call}

{call buckconfig.entry}
  {param section: 'intellij' /}
  {param name: 'java_module_sdk_type' /}
  {param example_value: 'JavaSDK' /}
  {param description}
    SDK type for Java modules.
  {/param}
{/call}

{call buckconfig.entry}
  {param section: 'intellij' /}
  {param name: 'java_module_sdk_name' /}
  {param example_value: '1.8' /}
  {param description}
    SDK name for Java modules.
  {/param}
{/call}

{call buckconfig.entry}
  {param section: 'project' /}
  {param name: 'generate_android_manifest' /}
  {param example_value: 'true' /}
  {param description}
    Forces Buck to generate "AndroidManifest.xml" files for Android IntelliJ modules. The generated
    manifests contain package name only to allow Android IntelliJ plugin resolve references to
    resources correctly.
    <p>Manifests are generated for modules that have information about package name and have either
    none or more than one targets with Android manifests. When a module has exactly one target with
    Android manifest this manifest is used as a manifest in the module.</p>
  {/param}
{/call}

{call buckconfig.entry}
  {param section: 'intellij' /}
  {param name: 'generated_sources_label_map' /}
  {param example_value: 'generated_code_1 => __%name%_target1__, \n                       generated_code2 => __%name%_target2__' /}
  {param description}
    Allows adding folders with generated source code to IntelliJ project. These folders are added
    when a target has a label specified in this option. In the example below, if
    target <code>//app/target</code> has
    label <code>generated_code1</code> folder <code>buck-out/gen/app/lib/__lib_target1__</code> will
    be added to IntelliJ project.
  {/param}
{/call}

{call buckconfig.entry}
  {param section: 'intellij' /}
  {param name: 'include_transitive_dependencies' /}
  {param example_value: 'false' /}
  {param description}
    Add transitive dependencies as RUNTIME library.
  {/param}
{/call}

{call buckconfig.entry}
  {param section: 'intellij' /}
  {param name: 'module_group_name' /}
  {param example_value: 'modules' /}
  {param description}
    Specify module group name when grouping modules.  If it is set to '', modules are not grouped.
  {/param}
{/call}

{call buckconfig.entry}
  {param section: 'intellij' /}
  {param name: 'remove_unused_libraries' /}
  {param example_value: 'true' /}
  {param description}
    Removes unused libraries from .idea/libraries.
  {/param}
{/call}

{call buckconfig.entry}
  {param section: 'intellij' /}
  {param name: 'aggregate_android_resource_modules' /}
  {param example_value: 'true' /}
  {param description}
    Forces <code>buck project</code> to aggregate modules with Android resources. This aggregation
    is performed only if aggregation mode is not <code>none</code>.
    <p/>
    <b>Note:</b> using this type of aggregation disables Android layout editor provided by Android
    plugin. The layout files can still be edited using the XML editor.
  {/param}
{/call}

{call buckconfig.entry}
  {param section: 'intellij' /}
  {param name: 'android_resource_module_aggregation_limit' /}
  {param example_value: '1000' /}
  {param description}
    The maximum number of targets that can be aggregated into one module with Android resources. This
    limit is a workaround to avoid a problem when Android plugin cannot operate on modules with a big number
    of resource folders.
  {/param}
{/call}

{call buckconfig.entry}
  {param section: 'intellij' /}
  {param name: 'project_compiler_output_url' /}
  {param example_value: 'build-ij/classes' /}
  {param description}
    The output directory for IntelliJ's builds.
  {/param}
{/call}

{call buckconfig.entry}
  {param section: 'intellij' /}
  {param name: 'extra_compiler_output_modules_path' /}
  {param example_value: 'buck-out/extra-intellij-output' /}
  {param description}
    This option specifies the location of additional modules for code generated outside of buck
    graph. For example, it can be used to specify the location of R.java classes generated for
    Android plugin to help Layout Preview with resolving references to resources.
  {/param}
{/call}

{call buckconfig.section}
  {param name: 'java' /}
  {param description}
    This section configures the Java toolchain.
  {/param}
{/call}

{call buckconfig.entry}
  {param section: 'java' /}
  {param name: 'src_roots' /}
  {param example_value: 'src, /java/, /javatests/' /}
  {param description}
    The paths to roots of Java code (where a root contains a tree of Java folders where the folder
    structure mirrors the package structure).  This list of paths is comma-delimited.  Paths that
    start with a slash are relative to the root of the project, and all other paths can match a
    folder anywhere in the tree.  In the example below, we match all folders named <code>src</code>,
    and <code>java</code> and <code>javatests</code> at the root of the project.
  {/param}
{/call}

{call buckconfig.entry}
  {param section: 'java' /}
  {param name: 'extra_arguments' /}
  {param example_value: '-g' /}
  {param description}
    A comma-delimited list of flags to pass the Java compiler.
  {/param}
{/call}

{call buckconfig.entry}
  {param section: 'java' /}
  {param name: 'source_level' /}
  {param example_value: '7' /}
  {param description}
    The default version of Java for source files. Also defines the project language level in
    IntelliJ.
  {/param}
{/call}

{call buckconfig.entry}
  {param section: 'java' /}
  {param name: 'target_level' /}
  {param example_value: '7' /}
  {param description}
    The default version of Java for generated code.
  {/param}
{/call}

{call buckconfig.entry}
  {param section: 'java' /}
  {param name: 'skip_checking_missing_deps' /}
  {param example_value: 'false' /}
  {param description}
    Buck will attempt to analyze build failures and suggest dependencies that might not be declared
    in order to fix the failure.  On large projects, this can be slow.  This setting disables the
    check.
  {/param}
{/call}

{call buckconfig.entry}
  {param section: 'java' /}
  {param name: 'jar_spool_mode' /}
  {param example_value: 'intermediate_to_disk' /}
  {param description}
    Specifies how the compiler output to the <code>.jar</code> file should be spooled.  The valid
    modes are:
    <ul>
      <li>
        <code>intermediate_to_disk</code> (default): writes the intermediate <code>.class</code>{sp}
        files from the compiler output to disk.  They are then packed into a <code>.jar</code>.
      </li>
      <li>
        <code>direct_to_jar</code>: compiler output will be directly written to a <code>.jar</code>
        {sp}file with the intermediate <code>.class</code> files held in memory.  The compiler
        output will still be written to disk if there are any postprocessing commands specified
        during the build.
      </li>
    </ul>
  {/param}
{/call}

{call buckconfig.entry}
  {param section: 'java' /}
  {param name: 'abi_generation_mode' /}
  {param example_value: 'source' /}
  {param description}
    <p>Specifies how Buck should create ABI jars when computing {call buck.abi_rule_keys /}. Values
    other than <code>class</code> may not be suitable for all rules; this setting may be overridden
    on a per-rule basis using the <code>abi_generation_mode</code> parameter on each rule.<p>

    <p>The valid modes are:
      <ul>
        <li>
          <code>class</code> (default): creates an ABI jar for each library by first building the
          library and then stripping out any information that is not part of the interface (such
          as method bodies and private members).
        </li>
        <li>
          <p><code>source</code>: creates an ABI jar for each library in the process of building the
          library, via a plugin to the Java compiler. This improves build times by allowing each
          library's dependents to start building before the library is done building.</p>
          <p>Implies <code>jar_spool_mode = direct_to_jar</code>.</p>
        </li>
        <li>
          <p><code>source_only</code>: creates an ABI jar for each library by referencing only the
          source code of the library, without considering (most of) its dependencies. This can
          drastically improve build times, especially in larger apps or in build environments with
          a large number of cores by allowing all ABI jars to be built in parallel, and then all
          library jars to be built in parallel (up to the available parallelism in the build
          environment). Additionally, in environments with network-based caches it can reduce
          the number of calls to the cache required for each build.</p>
          <p>Requires some changes to how Java code is written. To migrate, first do some builds
          in <code>migrating_to_source_only</code> mode, using {call buck.cmd_fix /} to
          fix any issues encountered. Once migrated, errors will still be encountered from time
          to time when new code does not meet the requirements of this mode.
          {call buck.cmd_fix /} can be used to address these.</p>
          <p>When building with <code>source_only</code>, using {call buck.cmd_build /}
          <code> --keep-going</code> is recommended since some errors that occur when building an
          ABI jar will actually have their root cause in another rule that builds later.</p>
          <p>Read more about source-only ABIs&nbsp;
          {call buck.concept_link}{param page: 'java_abis' /}{param name: 'here' /}{/call}.</p>
        </li>
        <li>
          <p><code>migrating_to_source_only</code>: used when migrating from <code>source</code> to&nbsp;
          <code>source_only</code>. Acts like <code>source</code>, but issues warnings (in
          <code>buck.log</code>, not to the console) for any Java code that would cause errors under
          <code>source_only</code>. {call buck.cmd_fix /} can be used to fix most such warnings.
        </li>
      </ul>
    </p>
  {/param}
{/call}

{call buckconfig.section}
  {param name: 'kotlin' /}
  {param description}
    This section configures various aspects of the <a href="https://kotlinlang.org">Kotlin</a>{sp}
    toolchain.
  {/param}
{/call}

{call buckconfig.entry}
  {param section: 'kotlin' /}
  {param name: 'kotlinc' /}
  {param example_value: '/usr/local/bin/kotlinc' /}
  {param description}
    The path to the <code>kotlinc</code> compiler executable to use when external compilation is
    forced.  This setting has no effect by itself and must be paired with the
    {sp}{call buckconfig.kotlin_external /} setting.
  {/param}
{/call}

{call buckconfig.entry}
  {param section: 'kotlin' /}
  {param name: 'external' /}
  {param example_value: 'true' /}
  {param description}
    Forces external compilation via <code>kotlinc</code>.  When external compilation is forced the
    following heuristics are used to locate the <code>kotlinc</code> executable:
    <ul>
      <li>If the <code>{call buckconfig.kotlin_kotlinc /}</code> setting is specified, the executable specified by that path
          will be used.
      </li>
      <li>If the {call buckconfig.kotlin_kotlin_home /} path setting is specified, Buck will look
          for a <code>bin</code> directory under that path for an executable named
          {sp}<code>kotlinc</code>.
      </li>
      <li>If a <code>KOTLIN_HOME</code> environment variable is present, Buck will look for a
          {sp}<code>bin</code> directory under that path for an executable named
          {sp}<code>kotlinc</code>.
      </li>
      <li>Lastly, if none of the above are specified, Buck will look for the <code>kotlinc</code>
          {sp}executable in the paths listed in the <code>PATH</code> environment variable.
      </li>
    </ul>
    Defaults to <code>false</code>.
  {/param}
{/call}

{call buckconfig.entry}
  {param section: 'kotlin' /}
  {param name: 'kotlin_home' /}
  {param example_value: '/usr/local/Cellar/kotlin/1.1.1' /}
  {param description}
    The path to the Kotlin root folder, typically the installation folder, where various Kotlin
    assets (executables and JAR files) can be found.  This path is used in the following ways:
    <ul>
      <li>
        When in-memory compilation is used, the <code>kotlin-compiler.jar</code> and other related
        Kotlin JARs required for compilation are located via this path using the following
        heuristics:
        <ul>
          <li>
            The root of the directory specified by this path is searched.
          </li>
          <li>
            If there is a <code>lib</code> directory under this path, it is searched.
          </li>
          <li>
            If there is a <code>libexec</code> directory under this path, it is searched.
          </li>
        </ul>
      </li>
      <li>
        If external compilation is called for (see {call buckconfig.kotlin_external /}), a
        {sp}<code>bin</code> directory under this directory will be searched to locate the
        {sp}<code>kotlinc</code> executable.
      </li>
    </ul>
    If this setting is not specified, the location of the Kotlin home directory can be specified
    via the <code>KOTLIN_HOME</code> environment variable.  If neither the
    {sp}{call buckconfig.kotlin_kotlin_home /} setting nor the <code>KOTLIN_HOME</code>{sp}
    environment variable is specified, Buck will attempt to locate the home directory by
    searching for the <code>kotlinc</code> executable in the paths specified by the
    {sp}<code>PATH</code> environment variable.  If the <code>kotlinc</code> executable is found,
    Buck assumes that the <i>parent directory</i> of that executable is the Kotlin home.
  {/param}
{/call}

{call buckconfig.section}
  {param name: 'dx' /}
  {param description}
    This section controls how Buck invokes the dx tool.
  {/param}
{/call}

{call buckconfig.entry}
  {param section: 'dx' /}
  {param name: 'max_threads' /}
  {param example_value: '8' /}
  {param description}
    The number of thread that will run the dexing steps. Since the dexing steps can use a lot of
    memory, it might be useful to set this to a lower value to avoid out-of-memory errors.
  {/param}
{/call}

{call buckconfig.entry}
  {param section: 'dx' /}
  {param name: 'max_heap_size' /}
  {param example_value: '2g' /}
  {param description}
    This option specifies how much memory is available when running dx out of process.
  {/param}
{/call}

{call buckconfig.section}
  {param name: 'httpserver' /}
  {param description}
    Option to enable an experimental web server that presents a UI to explore build data.  Note that
    Buck must be run as a daemon in order for the web server to be available.
  {/param}
{/call}

{call buckconfig.entry}
  {param section: 'httpserver' /}
  {param name: 'port' /}
  {param example_value: '8080' /}
  {param description}
    This sets the port to use for the web server.  There are three possible values:
    <ul>
      <li>
        <code>n > 0</code>: For any positive integer, Buck will attempt to make the server
        available on that port.
      </li>
      <li>
        <code>0</code>: Buck will find a free port for the server to use and print it out on the
        command line.
      </li>
      <li>
        <code>-1</code>: Explicitely disables the server.
      </li>
    </ul>
  {/param}
{/call}

{call buckconfig.section}
  {param name: 'log' /}
  {param description}
    This section controls how Buck will log information about builds for later inspection.
  {/param}
{/call}

{call buckconfig.entry}
  {param section: 'log' /}
  {param name: 'max_traces' /}
  {param example_value: '25' /}
  {param description}
    Sets the maximum number of <a href="{ROOT}about/performance_tuning.html">Chrome Traces</a> that
    Buck will create.
  {/param}
{/call}

{call buckconfig.entry}
  {param section: 'log' /}
  {param name: 'compress_traces' /}
  {param example_value: 'true' /}
  {param description}
    <code>true</code> if Buck should GZIP the traces, false otherwise.
  {/param}
{/call}

{call buckconfig.entry}
  {param section: 'log' /}
  {param name: 'machine_readable_logger_enabled' /}
  {param example_value: 'true' /}
  {param description}
    <code>true</code> if Buck should output to a machine readable log file under name <code>
    buck-machine-log</code>. Log entries are formatted one per line like <code>< Event type >
    < space >< Json ></code>.
  {/param}
{/call}

{call buckconfig.section}
  {param name: 'lua' /}
  {param description}
    This section defines settings relevant to <code>lua_*</code> rules.
  {/param}
{/call}

{call buckconfig.entry}
  {param section: 'lua' /}
  {param name: 'lua' /}
  {param example_value: '/usr/bin/lua' /}
  {param description}
    The path to the Lua interpreter.  By default, Buck will search for the binary{sp}
    <code>lua</code> in your <code>PATH</code>.
  {/param}
{/call}

{call buckconfig.entry}
  {param section: 'lua' /}
  {param name: 'cxx_library' /}
  {param example_value: '//third-party/lua:lua' /}
  {param description}
    The build target of the Lua C library to use to link a standalone interpreter.
    By default, Buck will use <code>-llua</code> from the C/C++ linker's default
    library search path.
  {/param}
{/call}

{call buckconfig.entry}
  {param section: 'lua' /}
  {param name: 'starter_type' /}
  {param example_value: 'pure' /}
  {param description}
    The method for bootstrapping Lua binaries.  By default, <code>native</code> is chosen
    if the binary contains native libraries and <code>pure</code> is chosen otherwise.
    <ul>
        <li>
          <code>pure</code>: The binary bootstrap process uses pure Lua code.  This method
          cannot be used if the binary includes native code.
        </li>
        <li>
          <code>native</code>: The binary bootstrap process links in the Lua C library
          (specified in {call buckconfig.lua_cxx_library /}) to form a standalone native
          interpreter.
        </li>
    </ul>
  {/param}
{/call}

{call buckconfig.entry}
  {param section: 'lua' /}
  {param name: 'native_starter_library' /}
  {param example_value: '//third-party/lua:starter' /}
  {param description}
    A C/C++ library to use as a custom starter for Lua binaries which use the
    <code>NATIVE</code> bootstrap method.  The library is expected to define the
    following function:

{literal}<pre class="prettyprint lang-cpp">
#ifdef __cplusplus
extern "C"
#endif
int run_starter(
    int argc,
    const char **argv,
    const char *main_module,
    const char *modules_dir,
    const char *extension_suffix);
</pre>{/literal}

    Where the arguments are as follows:
    <ul>
        <li>
          <code>argc</code>: The number of command-line arguments.
        </li>
        <li>
          <code>argv</code>: The array of command-line arguments.
        </li>
        <li>
          <code>main_module</code>: The name of the binary's main module.
        </li>
        <li>
          <code>modules_dir</code>: The path, relative the binary, to the modules directory.
        </li>
        <li>
          <code>extension_suffix</code>: The suffix used for native libraries (e.g. <code>.so</code>).
        </li>
    </ul>
  {/param}
{/call}

{call buckconfig.entry}
  {param section: 'lua' /}
  {param name: 'extension' /}
  {param example_value: '.lex' /}
  {param description}
    The extension to use for Lua binaries.  Defaults to <code>.lex</code>.
  {/param}
{/call}

{call buckconfig.section}
  {param name: 'maven_repositories' /}
  {param description}
    This section defines the set of maven repositories that Buck can use when attempting to resolve
    maven artifacts.  It takes the form of key value pairs of a short name for the repo and the URL.
    The URL may either be an HTTP(S) URL, or point to a directory on your local disk.

{literal}<pre class="prettyprint lang-ini">
[maven_repositories]
  central = https://repo1.maven.org/maven2
  m2 = ~/.m2/repository
</pre>{/literal}
  {/param}
{/call}

<p>
Note that if you using Buck to talk to Maven and you are using IPv6, you
might need to <a href="./buckjavaargs.html">add the following option to
your <code>.buckjavaargs</code> file</a>:
</p>

{literal}<pre>
-Djava.net.preferIPv6Addresses=true</pre>{/literal}

{call buckconfig.section}
  {param name: 'ndk' /}
  {param description}
    This section defines properties to configure building native code against the Android NDK.
  {/param}
{/call}

{call buckconfig.entry}
  {param section: 'ndk' /}
  {param name: 'ndk_version' /}
  {param example_value: 'r10c' /}
  {param description}
    The version of the NDK that Buck should use to build native code.  This is searched for in the
    subfolders defined by the folder found in the <code>ANDROID_NDK_REPOSITORY</code> environment
    variable.
    <p>NDKs with version prior r11 store their version in <code>RELEASE.TXT</code> file. For example,
    in version r10c this file contains "r10c (64-bit)". You need to put "r10c"
    in <code>ndk_version</code>.</p>
    <p>The NDKs after r11 store their version number in <code>source.properties</code> file
    in <code>Pkg.Revision</code> option. For example, this is the content of that file for version
    r13b:<p/>
    {literal}<pre class="prettyprint lang-js">
    Pkg.Desc = Android NDK
    Pkg.Revision = 13.1.3345770</pre>{/literal}
    <p>You need to put "13.1.3345770" in <code>ndk_version</code>.</p>
  {/param}
{/call}

{call buckconfig.entry}
  {param section: 'ndk' /}
  {param name: 'ndk_path' /}
  {param example_value: '/Library/Android/ndk/r10c' /}
  {param description}
    This specifies the absolute path to the Android NDK. This is equivalent to setting the
    environment variable <code>ANDROID_NDK=/Library/Android/ndk/r10c</code>. The environment
    variables <code>ANDROID_NDK</code> and <code>NDK_HOME</code> both supercede the buckconfig
    setting. The default is empty.
  {/param}
{/call}

{call buckconfig.entry}
  {param section: 'ndk' /}
  {param name: 'ndk_repository_path' /}
  {param example_value: '/Library/Android/ndk' /}
  {param description}
    This specifies the absolute path to a directory containing versions of the Android NDK. This is
    equivalent to setting the environment variable
    <code>ANDROID_NDK_REPOSITORY=/Library/Android/ndk</code>. The environment variable supercedes
    the buckconfig setting. The default is empty.
  {/param}
{/call}

{call buckconfig.entry}
  {param section: 'ndk' /}
  {param name: 'app_platform' /}
  {param example_value: 'android-21' /}
  {param description}
    The android platform libraries that the code is targetting.  This is equivalent to the{sp}
    <code>APP_TARGET</code> in the NDK build system.  The default is <code>android-9</code>.
  {/param}
{/call}

{call buckconfig.entry}
  {param section: 'ndk' /}
  {param name: 'cpu_abis' /}
  {param example_value: 'armv7, x86' /}
  {param description}
    A comma separated list of the CPU ABIs that this repo supports.  Buck will only build NDK code
    for these ABIs.
  {/param}
{/call}

{call buckconfig.entry}
  {param section: 'ndk' /}
  {param name: 'compiler' /}
  {param example_value: 'gcc' /}
  {param description}
    When compiling {call buck.cxx_library /} rules, this specifies the compiler family to use from
    the NDK.  The possible values are:
    <ul>
        <li><code>gcc</code> (default): Use the GCC family of compilation tools.</li>
        <li><code>clang</code>: Use the Clang family of compilation tools.</li>
    </ul>
  {/param}
{/call}

{call buckconfig.entry}
  {param section: 'ndk' /}
  {param name: 'gcc_version' /}
  {param example_value: '4.8' /}
  {param description}
    When compiling {call buck.cxx_library /} rules, this specifies the version of GCC to use.  This
    will be used regardless of the value in {call buckconfig.ndk_compiler /}, as other compiler
    families still use tools from the GCC toolchain (such as <code>ar</code>).  The default value is
    {sp}<code>4.8</code>.
  {/param}
{/call}

{call buckconfig.entry}
  {param section: 'ndk' /}
  {param name: 'clang_version' /}
  {param example_value: '3.4' /}
  {param description}
    When compiling {call buck.cxx_library /} rules, this specifies the version of Clang to use.  The
    default value is <code>3.4</code>.
  {/param}
{/call}

{call buckconfig.entry}
  {param section: 'ndk' /}
  {param name: 'cxx_runtime' /}
  {param example_value: 'gnustl' /}
  {param description}
    When compiling {call buck.cxx_library /} rules, this specifies the variant of the <a
    href="http://www.kandroid.org/ndk/docs/CPLUSPLUS-SUPPORT.html">C/C++ runtime</a> to use.
    Possible values are:
    <ul>
      <li><code>gabixx</code></li>
      <li><code>gnustl</code> (default)</li>
      <li><code>libcxx</code></li>
      <li><code>stlport</code></li>
      <li><code>system</code></li>
    </ul>
  {/param}
{/call}

{call buckconfig.section}
  {param name: 'ocaml' /}
  {param description}
    <p>
      This section configures the paths to the OCaml toolchain's binaries.
    </p>
  {/param}
{/call}

{call buckconfig.entry}
  {param section: 'ocaml' /}
  {param name: 'ocaml.bytecode.compiler' /}
  {param example_value: '/usr/local/bin/ocamlc.opt' /}
  {param description}
    The path to the <a href="https://caml.inria.fr/pub/docs/manual-ocaml/native.html">OCaml bytecode compiler (ocamlc)<a>.
  {/param}
{/call}

{call buckconfig.entry}
  {param section: 'ocaml' /}
  {param name: 'ocaml.compiler' /}
  {param example_value: '/usr/local/bin/ocamlopt.opt' /}
  {param description}
    The path to the <a href="https://caml.inria.fr/pub/docs/manual-ocaml/comp.html">OCaml native-code compiler (ocamlopt)</a>.
  {/param}
{/call}

{call buckconfig.entry}
  {param section: 'ocaml' /}
  {param name: 'dep.tool' /}
  {param example_value: '/usr/local/bin/ocamldep.opt' /}
  {param description}
    The path to the <a href="https://caml.inria.fr/pub/docs/manual-ocaml/depend.html">OCaml dependency generator (ocamldep)</a>.
  {/param}
{/call}

{call buckconfig.entry}
  {param section: 'ocaml' /}
  {param name: 'lex.compiler' /}
  {param example_value: '/usr/local/bin/ocamllex.opt' /}
  {param description}
    The path to the <a href="https://caml.inria.fr/pub/docs/manual-ocaml/lexyacc.html#sec296">OCaml lexer generator (ocamllex)</a>.
  {/param}
{/call}

{call buckconfig.entry}
  {param section: 'ocaml' /}
  {param name: 'yacc.compiler' /}
  {param example_value: '/usr/local/bin/ocamlyacc' /}
  {param description}
    The path to the <a href="https://caml.inria.fr/pub/docs/manual-ocaml/lexyacc.html#sec307">OCaml parser generator (ocamlyacc)</a>.
  {/param}
{/call}

{call buckconfig.entry}
  {param section: 'ocaml' /}
  {param name: 'debug' /}
  {param example_value: '/usr/local/bin/ocamldebug' /}
  {param description}
    The path to the <a href="https://caml.inria.fr/pub/docs/manual-ocaml/debugger.html">OCaml debugger (ocamldebug)</a>.
  {/param}
{/call}

{call buckconfig.entry}
  {param section: 'ocaml' /}
  {param name: 'interop.includes' /}
  {param example_value: '/usr/local/lib/ocaml' /}
  {param description}
    The path to the OCaml standard library directory
    (see <a href="https://caml.inria.fr/pub/docs/manual-ocaml/intfc.html">Interfacing C with OCaml</a>).
  {/param}
{/call}


{call buckconfig.section}
  {param name: 'parser' /}
  {param description}
    This section defines settings for the BUCK parser.
  {/param}
{/call}

{call buckconfig.entry}
  {param section: 'parser' /}
  {param name: 'python_interpreter' /}
  {param example_value: '/usr/bin/python' /}
  {param description}
    The path to the python interpreter to use for parsing. If not specified, the{sp}
    {call buckconfig.python_interpreter /} setting is used.
  {/param}
{/call}

{call buckconfig.entry}
  {param section: 'parser' /}
  {param name: 'python_path' /}
  {param example_value: '/path1:/path2' /}
  {param description}
    The <code>PYTHONPATH</code> environment variable set for the python interpreter{sp}
    used by the parser to use.
    By default, this is unset.
  {/param}
{/call}

{call buckconfig.entry}
  {param section: 'parser' /}
  {param name: 'freeze_globals' /}
  {param example_value: 'false' /}
  {param description}
    Indicates whether globals imported by {call buck.fn_load /} and{sp}
    {call buck.fn_include_defs /} should be "frozen", which means they will be converted into
    their read-only counterparts. This can be used to detect
    accidental attempts to modify global variables causing non-determinism and hard to debug bugs.
    By default, this is not enabled (<code>false</code>).
  {/param}
{/call}

{call buckconfig.entry}
  {param section: 'parser' /}
  {param name: 'polyglot_parsing_enabled' /}
  {param example_value: 'true' /}
  {param description}
    Indicates whether support for experimental polyglot parsing should be enabled. When enabled,
    build file can have a <code># BUILD FILE SYNTAX: </code> marker followed by one of supported
    syntax names that include <code>PYTHON_DSL</code> and an experimental <code>SKYLARK</code>.
    This flag is disabled by default.
  {/param}
{/call}

{call buckconfig.entry}
  {param section: 'parser' /}
  {param name: 'default_build_file_syntax' /}
  {param example_value: 'SKYLARK' /}
  {param description}
    Specifies the default syntax assumed when parsing build files without explicit build syntax
    marker (<code># BUILD FILE SYNTAX: </code>). This flag is only applicable when
    <code>parser.polyglot_parsing_enabled</code> configuration is set to <code>true</code>.
    By default it's value is set to <code>PYTHON_DSL</code>.
  {/param}
{/call}

{call buckconfig.section}
  {param name: 'project' /}
  {param description}
    This section defines project-level settings.
  {/param}
{/call}

{call buckconfig.entry}
  {param section: 'project' /}
  {param name: 'ide' /}
  {param example_value: 'xcode' /}
  {param description}
    Buck attempts to figure out the correct IDE to use based on the type of rule (e.g. for{sp}
    {call buck.apple_library /} it will generate Xcode workspace), but for cross-platform libraries
    (like {call buck.cxx_library /}) it is not possible.  This setting lets you specify the default
    IDE that {call buck.cmd_project /} generates.  Possible values are:
    <ul>
      <li><code>intellij</code></li>
      <li><code>xcode</code></li>
    </ul>
  {/param}
{/call}

{call buckconfig.entry}
  {param section: 'project' /}
  {param name: 'glob_handler' /}
  {param example_value: 'python' /}
  {param description}
    The {call buck.fn_glob /} handler that Buck will use.  The possible values are:
    <ul>
      <li>
        <code>python</code> (default): evaluates globs in the Python interpreter while parsing{sp}
        {call buck.build_file /}s.
      </li>
      <li>
        <code>watchman</code>: evaluates the globs with <a
        href="https://facebook.github.io/watchman/">Watchman</a>, which is generally much faster.
      </li>
    </ul>
  {/param}
{/call}

{call buckconfig.entry}
  {param section: 'project' /}
  {param name: 'allow_symlinks' /}
  {param example_value: 'forbid' /}
  {param description}
    <p>
    If set to <code>forbid</code>, Buck will disallow symbolic links to source and <code>BUCK</code> files.
    This allows Buck to enable a number of performance improvements.  If set to <code>allow</code>, Buck
    will silently ignore symlinks.
    </p>
    <p>
    The default value is <code>warn</code>.
    </p>
  {/param}
{/call}

{call buckconfig.entry}
  {param section: 'project' /}
  {param name: 'build_file_search_method' /}
  {param example_value: 'watchman' /}
  {param description}
    <p>
    If set to <code>watchman</code>, Buck will try to use Watchman (if available) instead of Java filesystem
    crawls to improve the speed when searching for <code>BUCK</code> files. (This is used for commands
    like <code>buck project</code> and <code>buck build {literal}//path/to/...{/literal}</code>.)
    </p>
    <p>
    If set to <code>filesystem_crawl</code>, Buck will never try to use Watchman, and will always use
    Java filesystem crawls (which are much slower than Watchman.
    </p>
    <p>
    If unset, Buck will try to use Watchman if <code>allow_symlinks</code> is set to <code>forbid</code>.
    </p>
  {/param}
{/call}

{call buckconfig.entry}
  {param section: 'project' /}
  {param name: 'watchman_query_timeout_ms' /}
  {param example_value: '60000' /}
  {param description}
    When communicating with <a href="https://facebook.github.io/watchman/">Watchman</a>, Buck will
    wait this long for a response.  The defaut is <code>60000</code> ms.
  {/param}
{/call}

{call buckconfig.entry}
  {param section: 'project' /}
  {param name: 'initial_targets' /}
  {param example_value: '//java/com/facebook/schema:generate_thrift_jar' /}
  {param description}
    A space-separated list of {call buck.build_target /}s to run when {call buck.cmd_project /} is
    executed.  This is often a list of {call buck.genrule /}s whose outputs need to exist in order
    for an IDE to be ale to build a project without the help of Buck.
  {/param}
{/call}

{call buckconfig.entry}
  {param section: 'project' /}
  {param name: 'ignore' /}
  {param example_value: '.git' /}
  {param description}
    A comma-separated list of subtrees within the project root which are ignored in the following
    contexts:
    <ul>
      <li>Buck daemon filesystem monitoring.</li>
      <li>Filesystem traversal when searching for tests and BUCK files</li>
      <li>IntelliJ project indexing</li>
    </ul>
    Buck automatically excludes its own output, e.g. <code>buck-out</code>, <code>.buckd</code>, and
    {sp}<code>.idea</code>, as well as the cache directory (see {call buckconfig.cache_mode /}), but
     it makes no assumptions about source control systems.
  {/param}
{/call}

{call buckconfig.entry}
  {param section: 'project' /}
  {param name: 'pre_process' /}
  {param example_value: 'scripts/pre_process_buck_project.py' /}
  {param description}
     A script that should be executed before the project files are generated. This should only be
    used to do some project-specific actions that are reasonably fast.
    <p/>
    The environment of this script contains the following variables:
    <ul>
      <li><code>BUCK_PROJECT_TARGETS</code> - whitespace-separated list of input targets.</li>
      <li><code>BUCK_PROJECT_TYPE</code> - the type of a project, can be "xcode", "intellij" or
      "intellij-view".</li>
    </ul>
  {/param}
{/call}

{call buckconfig.entry}
  {param section: 'project' /}
  {param name: 'parallel_parsing' /}
  {param example_value: 'false' /}
  {param description}
    When set to <code>true</code>, Buck will parse your {call buck.build_file /}s in parallel.
  {/param}
{/call}

{call buckconfig.entry}
  {param section: 'project' /}
  {param name: 'parsing_threads' /}
  {param example_value: '2' /}
  {param description}
    When {call buckconfig.project_parallel_parsing /} is enabled, this specifies the number of
    threads Buck uses to parse.  By default, this is equal to the number of threads Buck uses to
    build, and will be the minimum of this setting and {call buckconfig.build_threads /}.
  {/param}
{/call}

{call buckconfig.entry}
  {param section: 'project' /}
  {param name: 'build_file_import_whitelist' /}
  {param example_value: 'math, Foo' /}
  {param description}
    A comma-separated list that configures which Python modules can be imported in build files.
  {/param}
{/call}

{call buckconfig.section}
  {param name: 'python' /}
  {param description}
    <p>
      This section may define settings relevant to <code>python_*</code> rules.
    </p>

    <p>
      Adding a section with the header [python#<i>flavor</i>] to the .buckconfig will add
      an alternate python section.  This python section will be used instead of{sp}
      <code>[python]</code> if the compilation flavor is invoked by appending <i>#version</i> to a
      {sp}{call buck.build_target /}.  This can be useful if you have Python 2 and Python 3 code in
      your project and need to differentiate accorindgly (namely by changing the value of{sp}
      {call buckconfig.python_interpreter /}.  On the command line, to build with{sp}
      <code>[python#py3]</code> rather than <code>[python]</code>:
    </p>

    {literal}<pre class="prettyprint">
    $ buck build app#py3
    </pre>{/literal}
  {/param}
{/call}

{call buckconfig.entry}
  {param section: 'python' /}
  {param name: 'interpreter' /}
  {param example_value: '/usr/bin/python' /}
  {param description}
    The path to the python interpreter to use.  By default, Buck will search for this in your{sp}
    <code>PATH</code>.
  {/param}
{/call}

{call buckconfig.entry}
  {param section: 'python' /}
  {param name: 'library' /}
  {param example_value: '//third-party/python:python' /}
  {param description}
    The {call buck.build_rule /}, typically a {call buck.prebuilt_cxx_library /}, wrapping the{sp}
    <code>libpython.so</code> that <code>cpp_python_extension</code> rules should build against.
  {/param}
{/call}

{call buckconfig.entry}
  {param section: 'python' /}
  {param name: 'path_to_pex_executor' /}
  {param example_value: '/bin/sh' /}
  {param description}
    The path to the tool used to run executable Python packages.  For self-executing packages, this
    should just by the shell.
  {/param}
{/call}

{call buckconfig.entry}
  {param section: 'python' /}
  {param name: 'pex_extension' /}
  {param example_value: '.pex' /}
  {param description}
    The extension to use for executable Python packages.
  {/param}
{/call}

{call buckconfig.entry}
  {param section: 'python' /}
  {param name: 'package_style' /}
  {param example_value: 'standalone' /}
  {param description}
    The packaging style to use for {call buck.python_binary /} and {call buck.python_test /}.  Valid
    values are:
    <ul>
        <li>
          <code>inplace</code>: builds exectuables which are only able to run from within the
          repository.  This style of packaging is significantly faster than <code>standalone</code>
          {sp}packages.
        </li>
        <li>
          <code>standalone</code> (default): builds self-contained executable packages that can be
          run outside of the repository.
        </li>
    </ul>
  {/param}
{/call}

{call buckconfig.entry}
  {param section: 'python' /}
  {param name: 'native_link_strategy' /}
  {param example_value: 'separate' /}
  {param description}
    The strategy used for pulling in native dependencies:
    <ul>
        <li>
          <code>merged</code>: Native dependencies which are first-order dependencies of{sp}
          <code>python_*</code> rules are linked as full, separate, shared libraries.  Transitive
          native dependencies are statically linked into a single monolithic shared library.  This
          is preferred to reduce the native code size and shared library count.
        </li>
        <li>
          <code>separate</code> (default): Transitive native dependencies are linked as full,
          separate, shared libraries.  This is prefererred for faster build-time speed.
        </li>
    </ul>
  {/param}
{/call}

{call buckconfig.section}
  {param name: 'resources' /}
  {param description}
    The settings to control how Buck uses resources to schedule the work.
    When resource-aware scheduler is enabled, Buck will create more threads in attempt to
    run resource-independent work in parallel. Number of build threads is still controlled
    by <code>num_threads</code> option. Buck will also create a number of additional
    threads that will be used for tasks that don't require CPU: network fetches,
    disk operations, etc. Total number of threads that Buck will operate is controlled by
    <code>managed_thread_count</code> option, that is, it includes build threads and
    additional threads.
  {/param}
{/call}

{call buckconfig.entry}
  {param section: 'resources' /}
  {param name: 'resource_aware_scheduling_enabled' /}
  {param example_value: 'true' /}
  {param description}
    When set to <code>true</code>, Buck will attempt to use resource-aware scheduler.
  {/param}
{/call}

{call buckconfig.entry}
  {param section: 'resources' /}
  {param name: 'managed_thread_count' /}
  {param example_value: '40' /}
  {param description}
    Buck will use <code>num_threads</code> threads for CPU intensive tasks
    (e.g. local building) and it will use <code>managed_thread_count - num_threads</code>
    for other purposes. Thus, <code>managed_thread_count</code> value must be greater or
    equal to  <code>num_threads</code> value. If you don't specify this value, Buck will
    create built-in number of additional threads which equals to the number of CPU cores
    on the machine. These additional threads will be used for non-CPU work like
    networking, disk I/O and etc. But if one of the <code>num_threads</code> threads is
    free then Buck will probably use it for non-CPU stuff as well.
  {/param}
{/call}

{call buckconfig.entry}
  {param section: 'resources' /}
  {param name: 'default_cpu_amount' /}
  {param example_value: '1' /}
  {param description}
    Amount of CPU resource required by arbitrary job which has no specific setting for its
    resource amounts. By default is 1 - a single CPU is required for the job to be completed.
  {/param}
{/call}

{call buckconfig.entry}
  {param section: 'resources' /}
  {param name: 'default_memory_amount' /}
  {param example_value: '1' /}
  {param description}
    Amount of memory resource required by arbitrary job which has no specific setting for
    its resource amounts. By default is 1 - a single memory resource is required for the
    job to be completed. A single memory resource is an abstract value, currently it
    equals to 100 Mb.
  {/param}
{/call}

{call buckconfig.entry}
  {param section: 'resources' /}
  {param name: 'default_disk_io_amount' /}
  {param example_value: '1' /}
  {param description}
    Amount of disk I/O resource required by arbitrary job which has no specific setting for
    its resource amounts. A single disk resource is an abstract value. Think about it as
    like SSD can handle 50 parallel disk jobs with weight 1, while HDD can handle only
    20. Thus, if job needs to read or write a lot of data, it is better to assign a higher
    value for its disk I/O amount. This will reduce the risk to have several similar jobs
    running concurrently and performing huge disk I/O operations, slowing down build itself
    and system performance.
  {/param}
{/call}

{call buckconfig.entry}
  {param section: 'resources' /}
  {param name: 'default_network_io_amount' /}
  {param example_value: '1' /}
  {param description}
    A single network resource is an abstract value. Think about it as Ethernet can handle
    50 parallel network jobs with weight 1. Slower network interfaces can handle less
    amount of jobs. If job needs to send  or receive a lot of data, it is better to assign
    a higher value for its network I/O amount.
  {/param}
{/call}

{call buckconfig.entry}
  {param section: 'resources' /}
  {param name: 'max_memory_resource' /}
  {param example_value: '30' /}
  {param description}
    Maximum memory resource available to Buck. By default is size of Java heap divided by
    100 Mb. A single memory resource is an abstract value, currently it equals to 100 Mb.
  {/param}
{/call}

{call buckconfig.entry}
  {param section: 'resources' /}
  {param name: 'max_disk_io_resource' /}
  {param example_value: '30' /}
  {param description}
    Maximum disk I/O resource available to Buck. By default the value is 50. Think about
    it as like SSD can handle 50 parallel disk jobs with weight 1, while HDD can handle only
    20. Thus, if job needs to read or write a lot of data, it should require higher disk I/O
    resource.
  {/param}
{/call}

{call buckconfig.entry}
  {param section: 'resources' /}
  {param name: 'max_network_io_resource' /}
  {param example_value: '30' /}
  {param description}
    Maximum disk I/O resource available to Buck. By default the value is 30. Think about it
    as Ethernet can handle 50 parallel network jobs with weight 1.
    Slower network interfaces can handle less amount of jobs. If job needs to send or
    receive a lot of data, it should require higher network I/O resource.
  {/param}
{/call}

{call buckconfig.section}
  {param name: 'resources_per_rule' /}
  {param description}
    <p>
      This section contains required resource amounts for various build rules. If amount for
      some build rule is not specified in this section, then amount of 1 (CPU), 1 (Memory),
      0 (disk i/o) and 0 (network i/o) is used. Amounts are used in local building, so in most
      cases build rule will require 0 for network I/O unless it fetches any data from network.
      Rule's name is constructed by converting the camel-style class name of the <code>BuildRule</code>
      in Buck's source code (e.g. <code>MyBuildRule</code>) into
      lower underscored name (e.g. <code>my_build_rule</code>).
    </p>
    {literal}<pre class="prettyprint lang-ini">
[resources_per_rule]
  cxx_link = 1, 1, 5, 0
  android_binary = 8, 30, 30, 0
     </pre>{/literal}
    <p>
      Buck will use the defined resource amounts during the build process in order to attempt
      to use all available resources.
    </p>
  {/param}
{/call}

{call buckconfig.section}
  {param name: 'rust' /}
  {param description}
    The settings to control how Buck builds <code>rust_*</code> rules.
  {/param}
{/call}

{call buckconfig.entry}
  {param section: 'rust' /}
  {param name: 'compiler' /}
  {param example_value: '/usr/local/bin/rustc' /}
  {param description}
    The path that Buck should use to compile Rust files.  By default, it checks your{sp}
    <code>PATH</code>.
  {/param}
{/call}

{call buckconfig.entry}
  {param section: 'rust' /}
  {param name: 'rustc_flags' /}
  {param example_value: '-g' /}
  {param description}
    Default command-line flags passed to all invocations of the rust compiler.
  {/param}
{/call}

{call buckconfig.entry}
  {param section: 'rust' /}
  {param name: 'rustc_binary_flags' /}
  {param example_value: '-C lto' /}
  {param description}
    Default command-line flags passed to invocations of the rust compiler in{sp}
    <code>rust_binary</code> rules, in addition to options set in <code>rustc_flags</code>.
  {/param}
{/call}

{call buckconfig.entry}
  {param section: 'rust' /}
  {param name: 'rustc_library_flags' /}
  {param example_value: '--cfg=debug' /}
  {param description}
    Default command-line flags passed to invocations of the rust compiler in{sp}
    <code>rust_library</code> rules, in addition to options set in <code>rustc_flags</code>.
  {/param}
{/call}

{call buckconfig.entry}
  {param section: 'rust' /}
  {param name: 'unflavored_binaries' /}
  {param example_value: 'true' /}
  {param description}
    Controls whether the output from <code>rust_binary</code> or <code>rust_test</code> rules
    include a flavor from the platform in the path or not. Even unflavored, the path includes{sp}
    <code>#binary</code>.
  {/param}
{/call}

{call buckconfig.entry}
  {param section: 'rust' /}
  {param name: 'remap_src_paths' /}
  {param example_value: 'no' /}
  {param description}
    Controls whether <code>rustc</code> remaps the source paths in its output. Buck will always
    construct a link tree with the sources required for a given rule, which means the paths passed
    to <code>rustc</code> are not the original source paths. This option will remap those paths
    in compiler output, debug info, <code>file!()</code> and elsewhere to match the original
    source names. The options are "no" (don't remap), "unstable" (remap using the experimental
    version of these options) and "yes" (remap using the stable versions, probably 1.22 onwards).
  {/param}
{/call}

{call buckconfig.section}
  {param name: 'sandbox' /}
  {param description}
    This section controls sandboxing. Sandbox execution provides better guarantees about resources
    accessible to the processes by using system-provided capabilities to restrict certain usages
    (for example, restricting the set of files allowed to be read and write).
  {/param}
{/call}

{call buckconfig.entry}
  {param section: 'sandbox' /}
  {param name: 'darwin_sandbox_enabled' /}
  {param example_value: 'true' /}
  {param description}
    This option specifies whether sandboxing is enabled on OS X or not.
  {/param}
{/call}

{call buckconfig.entry}
  {param section: 'sandbox' /}
  {param name: 'genrule_sandbox_enabled' /}
  {param example_value: 'true' /}
  {param description}
    Enables sandbox in <code>genrule</code>.
  {/param}
{/call}

{call buckconfig.section}
  {param name: 'test' /}
  {param description}
    The settings to control how Buck runs tests.
  {/param}
{/call}

{call buckconfig.entry}
  {param section: 'test' /}
  {param name: 'incl_no_location_classes' /}
  {param example_value: 'true' /}
  {param description}
    This specifies whether jacoco code coverage is enabled on classes without source location.
    The default is false.  Set to true to enable code coverage with robolectric tests.
    Note that setting to true will include dynamically created sources in code coverage, such as
    that created by mocking (e.g. jmockit) or persistence frameworks.
  {/param}
{/call}

{call buckconfig.entry}
  {param section: 'test' /}
  {param name: 'timeout' /}
  {param example_value: '300000' /}
  {param description}
    The number of miliseconds per test to allow before stopping the test and reporting a failure.
    The default is no timeout.  Not all <code>*_test</code> rules utilize this value.  A JUnit test
    can override this via the <code>@Test</code> annotation.
  {/param}
{/call}

{call buckconfig.entry}
  {param section: 'test' /}
  {param name: 'rule_timeout' /}
  {param example_value: '1200000' /}
  {param description}
    The number of milliseconds per <code>*_test</code> rule to allow before stopping it and reporting
    a failure.  The default is no timeout.
  {/param}
{/call}

{call buckconfig.entry}
  {param section: 'test' /}
  {param name: 'external_runner' /}
  {param example_value: 'command args...' /}
  {param description}
    <p>
      This specifies an external test runner comamnd to use instead of Buck's built-in test runner.
      The external test runner is invoked by Buck after it has built all the test rules.  It passes
      the test runner the path to a file which contains a JSON-encoded list of test file infos via
      the <code>--buck-test-info [path]</code> command line option.
    </p>
    <p>
      Additionally, if {call buck.cmd_test /} is invoked with <code>-- [extra-runner-args]</code>,
      these will be passed to the external runner before <code>--buck-test-info</code>.
    </p>
    <p>
      The JSON-encoded test file contains an array of infos.  Those infos have the following fields:
      <ul>
        <li><code>target</code>: The {call buck.build_target /} of the test rule.</li>
        <li><code>type</code>: A string describing the type of the test.</li>
        <li>
          <code>command</code>: An array of command line arguemtns the test runner should invoke to
          run the test.
        </li>
        <li>
          <code>env</code>: A map of environments variables that should be defined by the test
          runner when running the test.
        </li>
        <li><code>labels</code>: An array of labels that are defined on the test rule.</li>
        <li>
          <code>contacts</code>: An array of contacts that are defined on the test rule.  These are
          typically user names or email addresses.
        </li>
      </ul>
    </p>
  {/param}
{/call}

{call buckconfig.entry}
  {param section: 'test' /}
  {param name: 'parallel_external_test_spec_computation_enabled' /}
  {param example_value: 'false' /}
  {param description}
    Whether external test spec computation is allowed to happen in parallel. Enabling this option
    can significantly speed up test execution when many test targets are requested. By default it
    is disabled.
  {/param}
{/call}

{call buckconfig.section}
  {param name: 'thrift' /}
  {param description}
    This section provides settings to locate required thrift components.
  {/param}
{/call}

{call buckconfig.entry}
  {param section: 'thrift' /}
  {param name: 'compiler' /}
  {param example_value: '/usr/local/bin/thrift' /}
  {param description}
    The path or {call buck.build_target /} that builds the <a
    href="https://thrift.apache.org">thrift</a> compiler that Buck should use.
  {/param}
{/call}

{call buckconfig.entry}
  {param section: 'thrift' /}
  {param name: 'compiler2' /}
  {param example_value: '/usr/local/bin/thrift2' /}
  {param description}
    The path or {call buck.build_target /} that builds the <a
    href="https://github.com/facebook/fbthrift">thrift2</a> compiler that Buck should use.  If this
    is unset, it defaults to the value of {call buckconfig.thrift_compiler /}.
  {/param}
{/call}

{call buckconfig.section}
  {param name: 'tools' /}
  {param description}
    This section tells Buck how to find certain tools e.g. how the Java compilation
    occurs and how auxiliary tools are used e.g. the <a
    href="http://proguard.sourceforge.net/">ProGuard</a> Java class file
    optimizer which is used as part of the Android build process.
  {/param}
{/call}

{call buckconfig.entry}
  {param section: 'tools' /}
  {param name: 'javac' /}
  {param description}
    The <code>javac</code> option is a path to a program that acts like Java javac.
    When set, buck uses this program instead of the system Java compiler.
    When neither this nor {call buckconfig.tools_java_jar /} is set, Buck defaults
    to using the system compiler in-memory.
  {/param}
{/call}

{call buckconfig.entry}
  {param section: 'tools' /}
  {param name: 'javac_jar' /}
  {param description}
    When this option is set to a JAR file, Buck loads the referenced compiler in-memory.
    When neither this nor {call buckconfig.tools_javac /} is set, Buck defaults
    to using the system compiler in-memory.
  {/param}
{/call}

{call buckconfig.entry}
  {param section: 'tools' /}
  {param name: 'compiler_class_name' /}
  {param description}
    When javac_jar is set, Buck loads the referenced compiler class name from the jar.
    When it is not set but javac_jar is set, Buck uses the default compiler class.
  {/param}
{/call}

{call buckconfig.entry}
  {param section: 'tools' /}
  {param name: 'proguard' /}
  {param description}
    This option specifies the location of the JAR file to be used
    to invoke ProGuard. This overrides the default ProGuard JAR file that would have been
    picked up from the Android SDK. Here is an example setting:
  {/param}
  {param example_value : 'proguard/proguard-fork.jar' /}
{/call}

{call buckconfig.entry}
  {param section: 'tools' /}
  {param name: 'proguard-max-heap-size' /}
  {param example_value: '4096M' /}
  {param description}
    This option specifies how much memory is used when running proguard.
    Defaults to <code>1024M</code>. You may want to give ProGuard more memory to try and
    improve performance.
  {/param}
{/call}

{call buckconfig.entry}
  {param section: 'tools' /}
  {param name: 'proguard-agentpath' /}
  {param example_value: '/Applications/YourKit_Java_Profiler_2015_build_15084.app/Contents/Resources/bin/mac/libyjpagent.jnilib' /}
  {param description}
    This option allows the specification of a Java profiling agent which
    is set with the <code>-agentpath</code> argument when the ProGuard jar file is executed.
    Typically this would be set in a <code>.buckconfig.local</code> configuration file for when you
    want to profile a build running on your local machine.
    Set this to the actual path of the installed agent on the machine where ProGuard will run.
  {/param}
{/call}

{call buckconfig.section}
  {param name: 'ui' /}
  {param description}
    This section configures the appearance of Buck's command line interface.
  {/param}
{/call}

{call buckconfig.entry}
  {param section: 'ui' /}
  {param name: 'always_sort_threads_by_time' /}
  {param example_value: 'true' /}
  {param description}
    Specifies whether the lines with information about building and testing
    threads should always be sorted by the time spent running the rules they are
    currently executing. When set to false, threads are only sorted if there are
    more threads than available lines (see{sp}
    {call buckconfig.ui_thread_line_limit /} for an option to configure this
    limit). Only effective when the super console is used.
    The default value is false.
  {/param}
{/call}

{call buckconfig.entry}
  {param section: 'ui' /}
  {param name: 'thread_line_limit' /}
  {param example_value: '10' /}
  {param description}
    Specifies how many lines will be used to show the status of running threads
    during building and testing by default. Only effective when the super
    console is used. The value has to be a positive number.
    The default value is 10.
  {/param}
{/call}

{call buckconfig.entry}
  {param section: 'ui' /}
  {param name: 'thread_line_limit_on_warning' /}
  {param example_value: '10' /}
  {param description}
    Specifies how many lines will be used to show the status of running threads
    during building and testing after a warning is reported. Only effective
    when the super console is used. The value has to be a positive number.
    Defaults to the value of {call buckconfig.ui_thread_line_limit /}.
  {/param}
{/call}

{call buckconfig.entry}
  {param section: 'ui' /}
  {param name: 'thread_line_limit_on_error' /}
  {param example_value: '10' /}
  {param description}
    Specifies how many lines will be used to show the status of running threads
    during building and testing after an error is reported. Only effective
    when the super console is used. The value has to be a positive number.
    Defaults to the value of {call buckconfig.ui_thread_line_limit /}.
  {/param}
{/call}

{call buckconfig.entry}
  {param section: 'unknown_flavors_messages' /}
  {param name: 'unknown_flavors_messages' /}
  {param description}
    Specify messages for flavors. The message is used in case of an error with the flavors and
    it can be used to help debugging or provide suggestions for a fix. The name is a common Java
    Regex pattern like <code>android-*</code> and the value is the message that will be shown.
    Messages in <code>.buckconfig</code> have priority over Buck's defaults and suggestions will be
    shown for all the matches.
    <pre class="prettyprint lang-ini">
        [unknown_flavors_messages]{\n}{sp}{sp}
            android-* = Make sure you have Android SDK & NDK installed and set up.
    </pre>
  {/param}
{/call}

{call buckconfig.section}
  {param name: 'worker' /}
  {param description}
    This section configures how Buck's workers (<code>worker_tool</code>s and similar) work.
  {/param}
{/call}

{call buckconfig.entry}
  {param section: 'worker' /}
  {param name: 'persistent' /}
  {param example_value: 'false' /}
  {param description}
    Specifies whether by default workers run in persistent mode (reusing the worker process
    across builds). The <code>persistent</code> option of <code>worker_tool</code>
    {sp}overrides this default.
    The default value is false. Be careful when switching this to true since the workers will
    not shut down after buck commands and will continue consuming system resources.
  {/param}
{/call}

    {/param}
  {/call}

{/template}