docs/concept/buckconfig.soy

{namespace buck.buckconfig}

/***/
{template .soyweb}
  {call buck.page}
    {param title: '.buckconfig' /}
    {param content}

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).

<h2>[alias]</h2>

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

{literal}<pre>
[alias]
  app     = //apps/myapp:app
  apptest = //apps/myapp:test
</pre>{/literal}

This facilitates command-line use:

{literal}<pre>
buck build app
buck test apptest
</pre>{/literal}

<h2>[buildfile]</h2>

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>
[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.

<h2>[cache]</h2>

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 following
example configures buck to use directory-based caching, in which case the
Cassandra-related settings are ignored.

{literal}<pre>
[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.
    #
    # The default set is empty.
    mode = dir, cassandra

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

    # 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
</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>


<h2>[color]</h2>

Specify the following to disable colorized output:

{literal}<pre>
[color]
  ui = false
</pre>{/literal}


<h2>[java]</h2>

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>
[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.


<h2>[project]</h2>

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>
[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>
[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>
[project]
  ignore = .git
</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>
[project]
  post_process = ./scripts/post_process_buck_project.sh
</pre>{/literal}

    {/param}
  {/call}
{/template}