| {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} |