{namespace buck.buckconfig}

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

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

The root of your project may 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>.

<p>

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>

The following sections are recognized by Buck:

<p>

{foreach $name in [
    'adb',
    'alias',
    'android',
    'buildfile',
    'cache',
    'color',
    'cxx',
    'java',
    'httpserver',
    'log',
    'ndk',
    'project',
    'test',
    'tools',
    ]}
  <a href="#{$name}"><code>[{$name}]</code></a><br>
{/foreach}

{call .section}{param title: 'adb' /}{/call}

This section controls adb restart behavior on errors.

{literal}<pre class="prettyprint lang-ini">
[adb]
  # This specifies a whether to restart adb on failure or not.
  adb_restart_on_failure = true
</pre>{/literal}


{call .section}{param title: 'alias' /}{/call}

As demonstrated in the <a href="{ROOT}setup/quick_start.html">Quick Start</a>{sp}
instructions, aliases for build targets can be defined in
{sp}<code>.buckconfig</code>:

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

<p>

This facilitates command-line use:

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

{call .section}{param title: 'android' /}{/call}

Specify the version of the Android SDK that all Android code
in the project should be built against as follows:

{literal}<pre class="prettyprint lang-ini">
[alias]
  target = Google Inc.:Google APIs:21
</pre>{/literal}

<p>

If the SDK version is not specified in your <code>.buckconfig</code> file,
the version of the SDK that Buck has chosen will be printed to the console.

<p>

You can find the list of valid values on your system by running{sp}
<code>android list targets --compact</code>.

{call .section}{param title: 'buildfile' /}{/call}

This section may define an <code>includes</code> property that can specify a
path to a file of macros and constants that will automatically be included in
every build file. Therefore, defining the following:

{literal}<pre class="prettyprint lang-ini">
[buildfile]
  includes = //core/DEFS
</pre>{/literal}

is the equivalent of manually invoking <code>include_defs('//core/DEFS')</code>
{sp}at the start of every build file. See
{sp}<a href="{ROOT}function/include_defs.html"><code>include_defs()</code></a>
{sp}for more details.

{call .section}{param title: 'cache' /}{/call}

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 <code>mode</code> property determines which
other properties, if any, are relevant to caching configuration; the irrelevant
properties are ignored. The following example configures Buck to use both
directory-based and Cassandra caching.

{literal}<pre class="prettyprint lang-ini">
[cache]
    # Build artifact caching configuration.
    #
    # mode is a comma-separated set of caching mechanisms to use:
    #   dir       : Use a directory-based cache.
    #   cassandra : Use a distributed Cassandra cache.
    #   http      : Use an http cache.
    #
    # The default set is empty.
    mode = dir, cassandra

    # Directory path used for directory-based caching. The default directory
    # is buck-cache.
    dir = buck-cache

    # The maximum cache size for directory-based caching. The default size
    # is unlimited.
    dir_max_size = 10GB

    # Comma-separated set of known Cassandra cache nodes, for example:
    #
    #   hosts = artifactcache1.example.com, artifactcache2.example.com
    #
    # The default set is empty.
    hosts = localhost

    # Port on which to connect to Cassandra cache nodes. The default port is
    # 9160.
    port = 9160

    # Treat the Cassandra cache as readonly or readwrite.  The default mode
    # is readwrite.
    cassandra_mode = readwrite

    # Host for http cache. The default is localhost.
    http_host = localhost

    # Port on which to connect to the http cache. The default is 8080.
    http_port = 8080

    # Whether the http cache is readonly or readwrite. The default is
    # readwrite.
    http_mode = readwrite

    # Timeout for http requests.
    http_timeout_seconds = 10
</pre>{/literal}

Initial Cassandra setup is generally straightforward, and warrants no special
instructions beyond the following:
<ul>
  <li>The <code>thrift_framed_transport_size_in_mb</code> and
      {sp}<code>thrift_max_message_length_in_mb</code> defaults may be too low,
      depending on maximum artifact size. If these settings are left too low,
      then larger artifacts will not be cached and throughput may suffer due to
      network transport error recovery.
  <li>The <code>scripts/init_cassandra_node.cql</code> script must be run once
      in order to create the <code>ArtifactCache</code> keyspace that Buck
      uses.
</ul>

Buck communicates with the http cache using a
{sp}<a href="{ROOT}concept/http_cache_api.html">simple API</a>.


{call .section}{param title: 'color' /}{/call}

Specify the following to disable colorized output:

{literal}<pre class="prettyprint lang-ini">
[color]
  ui = false
</pre>{/literal}


{call .section}{param title: 'cxx' /}{param status: 'UNFROZEN' /}{/call}

This section configures the paths to the C++ toolchain's binaries.

{literal}<pre class="prettyprint lang-ini">
[cxx]
  # Path to the C preprocessor
  cpp = /usr/bin/gcc

  # Path to the C compiler
  cc = /usr/bin/gcc

  # Path to the C linker
  ld = /usr/bin/ld

  # Path to the C++ preprocessor
  cxxpp = /usr/bin/g++

  # Path to the C++ compiler
  cxx = /usr/bin/g++

  # Path to the c++ linker
  cxxld = /usr/bin/g++

  # Path to the assembly preprocessor
  aspp = /usr/bin/gcc

  # Path to the assembler
  as = /usr/bin/as

  # Path to the archiver
  ar = /usr/bin/ar

  # Path to the lexer
  lex = /usr/bin/flex

  # Path to the compiler compiler
  yacc = /usr/bin/bison
</pre>{/literal}

It also configures configures the default flags to pass to all invocations of said binaries.

{literal}<pre class="prettyprint lang-ini">
[cxx]
  # Flags to pass to the C preprocessor
  cppflags =

  # Flags to pass to the C compiler
  ccflags =

  # Flags to pass to the C linker
  ldflags =

  # Flags to pass to the C++ preprocessor
  cxxppflags =

  # Flags to pass to the C++ compiler
  cxxflags =

  # Flags to pass to the c++ linker
  cxxldflags =

  # Flags to pass to the assembly preprocessor
  asppflags =

  # Flags to pass to the assembler
  asflags =

  # Flags to pass to the archiver
  arflags =

  # Flags to pass to the lexer
  lexflags =

  # Flags to pass to the compiler compiler
  yaccflags =
</pre>{/literal}

{call .section}{param title: 'java' /}{/call}

This section may define a <code>src_roots</code> property that specifies
file 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. All other paths can match a folder
anywhere in the tree. For example:
{literal}<pre class="prettyprint lang-ini">
[java]
  src_roots = src, /java/, /javatests/
</pre>{/literal}
Will match the <code>java</code> and <code>javatests</code> folders in the
root of the project, as well as any folder named <code>src</code> in the
project.
<p>
<strong>Note:</strong> This is primarily used as a hack to help determine
where resources from a <code>java_library()</code> should be placed within the
generated JAR file. Hopefully <code>src_roots</code> will be removed at some
point.
<p>
This section may also contain an "extra_arguments" property, which provides
a comma-separated list of options to give to the Java compiler.
<p>
"source_level" and "target_level" specify the version of Java for source files
and generated code, respectively.  Both default to "7".

{call .section}{param title: 'httpserver' /}{/call}

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.

<p>
Specifying the port is sufficient to enable the web server:

{literal}<pre class="prettyprint lang-ini">
[httpserver]
  # The web server will be available at http://localhost:8080/.
  port = 8080
</pre>{/literal}

<p>

If you want Buck to find a free port and use that (i.e., an <em>ephemeral port</em>), then
specify a value of <code>0</code>:

{literal}<pre class="prettyprint lang-ini">
[httpserver]
  # The web server will be available at http://localhost:XXXX/.
  # Buck will print out the value of XXXX that it chose when the build
  # is complete. This value will be valid so long as the daemon is
  # kept alive.
  #
  # It is common for `port = 0` to be used in a shared .buckconfig file
  # for a project. Then individuals may override this value in
  # .buckconfig.local for each checkout of the repository so that the
  # port is predictable and guaranteed not to overlap with a port from
  # another checkout of the same project.
  port = 0
</pre>{/literal}

<p>

If you want to disable the web server, specify a value of <code>-1</code> for the port:

{literal}<pre class="prettyprint lang-ini">
[httpserver]
  # This will disable the web server. This often happens when
  # a nonnegative port is specified in .buckconfig, but the user
  # wants to override this behavior in .buckconfig.local.
  port = -1
</pre>{/literal}


{call .section}{param title: 'log' /}{/call}

This section controls how Buck will log information about builds for later
inspection.

{literal}<pre class="prettyprint lang-ini">
[log]
  max_traces = 25
</pre>{/literal}

Will limit Buck to creating, at most, 25{sp}
<a href="{ROOT}about/performance_tuning.html">Chrome Traces</a>.


{call .section}{param title: 'ndk' /}{/call}

This section may define both <code>min_version</code> and{sp}
<code>max_version</code> properties to enable Buck to check before building an{sp}
{call buck.ndk_library /} that the project supports the configured NDK. Both
properties must be specified to enable this check. For example, to support
only versions r7 through r8d:
{literal}<pre class="prettyprint lang-ini">
[ndk]
  min_version = r7
  max_version = r8d
</pre>{/literal}


{call .section}{param title: 'project' /}{/call}

This section may define a <code>default_android_manifest</code> property
to identify the <code>AndroidManifest.xml</code> that should be used when
the <code>src_target</code> of a
{sp}<a href="{ROOT}rule/project_config.html"><code>project_config()</code>
</a> rule is an Android rule (e.g.,
{sp}<a href="{ROOT}rule/android_library.html"><code>android_library()</code>
</a>), but there is no <code>AndroidManifest.xml</code> file in the same
directory as the build file. Because an IDE configuration for an Android
project needs an <code>AndroidManifest.xml</code>, this provides a convenient
fallback, preventing the need to litter your project with boilerplate
{sp}<code>AndroidManifest.xml</code> files.

{literal}<pre class="prettyprint lang-ini">
[project]
  default_android_manifest = //shared/AndroidManifest.xml
</pre>{/literal}

This section may also define an <code>initial_targets</code> property,
which is a space-delimited list of build targets to run when
{sp}<code>buck project</code> is executed. Frequently, this is a list of
{sp}<code>genrule</code>s whose outputs need to exist in order for an IDE
to be able to build a project natively (i.e., without the help of Buck).
<p>
For example, if you had a <code>genrule()</code> for generating a JAR from
a <a href="http://thrift.apache.org/">Thrift definition file</a>, and you had
a <code>java_library()</code> rule that depended on that JAR, then you would
want to be sure that <code>genrule()</code> was built before importing the
project into IntelliJ because IntelliJ does not know how to build
your <code>genrule()</code> as part of its built-in build process:

{literal}<pre class="prettyprint lang-ini">
[project]
  initial_targets = //java/com/facebook/schema:generate_thrift_jar
</pre>{/literal}

This section may also define an <code>ignore</code> property that specifies a
comma-separated list of subtrees within the project root which are ignored in
the following contexts:
<ul>
  <li>Buck daemon filesystem monitoring
  <li>Filesystem traversal when searching for tests and BUCK files
  <li>IntelliJ project indexing
</ul>
Buck automatically excludes its own output, e.g. <code>buck-out</code>,
{sp}<code>.buckd</code>, and <code>.idea</code>, as well as the cache directory
(see the "dir" setting of the "cache" section), but it makes no assumptions
about source control systems.

{literal}<pre class="prettyprint lang-ini">
[project]
  ignore = .git
</pre>{/literal}

This section may also define a <code>temp_files</code> property that
specifies a comma-separated list of <code>java.util.regex.Pattern</code> regular
expressions which match temporary and backup files which should be ignored by Buck
daemon filesystem monitoring. Setting this property to match any temporary files
created by your IDE or editor will avoid unnecessary cache invalidation when using
the Buck daemon.

{literal}<pre class="prettyprint lang-ini">
[project]
  temp_files = ^#.*#$, .*~$, .*\.swp$
</pre>{/literal}

A <code>post_process</code> property can reference a script that should be
executed after the project files are generated. Because <code>buck project</code> is
currently based on heuristics, the IntelliJ project that it generates may not be
exactly what you want if you are using a non-traditional project structure.
In these cases, you may want to let <code>buck project</code> do the bulk of the
heavy-lifting, and then let your <code>post_process</code> script do some cleanup
on the generated files.

{literal}<pre class="prettyprint lang-ini">
[project]
  post_process = ./scripts/post_process_buck_project.sh
</pre>{/literal}


{call .section}{param title: 'test' /}{/call}

This section may define a <code>timeout</code> for each test that Buck runs.
The value given is in milliseconds.

{literal}<pre class="prettyprint lang-ini">
[test]
  # This specifies a maximum timeout of 5 minutes (300000
  # milliseconds) per test. A JUnit test can override this
  # via its `@Test` annotation.
  timeout = 300000
</pre>{/literal}

{call .section}{param title: 'tools' /}{/call}
This section tells Buck how to find certain tools.
<p>

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.
<p>
The <code>javac_jar</code> option is like <code>javac</code>, except that it points to a JAR
containing a javac-like compiler.
<p>
When <code>javac_jar</code> is set, Buck loads the referenced compiler in-memory.
When neither option is set, Buck defaults to using the system compiler
in-memory.

    {/param}
  {/call}

{/template}