Buck: Common Parameters

Common Parameters

Some command-line parameters affect the operation of Buck itself, regardless of which subcommand is being run.

Parameters

  • --verbose

    Set the verbosity level of the console output. The verbosity level is a single numeric value between 1 and 8inclusive. For example:

    buck targets --verbose 8
    

    Higher verbosity levels include all the output for lower levels.

    The output that Buck produces is affected by factors in addition to the verbosity level. Such factors include, for example, the subcommand (build, install, test, etc), the types of rules being built, and the degree to which artifacts from previous builds have been cached.

    Buck has not yet implemented differences between all levels. For example, there are currently no differences in verbosity between levels 5 and 7 inclusive.

    Numeric levelBooleanDescription
    1shouldPrintStandardInformation()Print warnings from build steps and summary information for tests.
    2shouldPrintBinaryRunInformation()Print additional output for generated binaries or tests.
    3shouldPrintCommand()Print commands that Buck runs during the build process.
    4shouldPrintSelectCommandOutput()Print output for selected commands that Buck runs.
    5 - 7shouldPrintOutput()Print output for all commands that Buck runs.
    8shouldUseVerbosityFlagIfAvailable()Print all available diagnostic/logging information.

    For more precise information about how a particular verbosity level affects output, you can search the Buck source code for the corresponding boolean function. For example:

    grep --recursive "getVerbosity().shouldPrintOutput()" ~/local/buck/src 
    

  • --no-cache

    Disable the build artifact caches. If this parameter is specified, Buck ignores any artifacts in any of the caches specified in the [cache] section of .buckconfig. These include the filesystem cache (dir), remote cache (http), and SQLite cache (sqlite).

    The contents of the caches are unaffected, but Buck does not use them for the specified command.

    Note that if there is an output file in the buck-out directory for a previously-built and unchanged rule, Buck will still use that output file in your build—even if --no-cache is specified. If you don't want to use these existing and valid artifacts, run the buck clean command to delete them from buck-out.

  • --config

    Specify configuration settings or override existing settings in .buckconfig. For example:

    buck build --config cache.mode=dir ...
    

    The --config parameter can be specified multiple times on the same command line. Note, however, that if the same configuration option is specified more than once, Buck uses the last value specified ("last write wins"). For example, the following invocation of buck build builds the //:prod target, rather than the //:dev target, which was specified earlier on the command line.

    #
    # Build for development? 
    #
    # No, build for production.
    #
    buck build --config 'alias.main=//:dev' --config 'alias.main=//:prod' main
    

    The preferred method of overriding values in .buckconfig is by using a .buckconfig.local file. Overriding values of .buckconfig from the command line makes reproducing builds difficult.

  • --config-file

    Specify build-configuration settings in a file that uses the same syntax as .buckconfig.

    buck build --config-file debug.buckconfig
    

    The --config-file parameter provides functionality similar to --flagfile, but with .buckconfig syntax rather than command-line parameter syntax.

    Any values specified using --config-file override values specified in .buckconfig and .buckconfig.local.

    You can specify the path to the configuration file in one of three ways.

    Use a path that is relative to the directory that contains the current cell's .buckconfig.

    --config-file relative/path/to/file.buckconfig
    

    Use a path that is relative to the directory that contains a specified cell's .buckconfig.

    --config-file cell//path/to/file.buckconfig
    

    Use an absolute path from the root of your file system.

    --config-file /absolute/path/to/file.buckconfig
    

    You can also specify a particular cell to which to apply the configuration. By default, the settings in the configuration file apply to all cells in the current build.

    Apply the configuration only to the current cell.

    --config-file //=<path-to-config-file>
    

    Apply the configuration only to a specified target cell.

    --config-file <target-cell>=<path-to-config-file>
    

    If you specify * as the target cell, the configuration is applied to all the cells in the build. This is the default, but this syntax enables you to be explicit.

  • --num-threads

    The number of threads that buck should use when executing jobs. This defaults to 1.25 times the number of processors in the system; on systems with hyperthreading, this means that each core is counted twice. The number of threads to use for building can also be set by adding a "threads" key to the "build" section of the .buckconfig file.

    The order of precedence for setting the number of build threads (from highest to lowest) is:

    1. command-line option
    2. .buckconfig setting
    3. default value

    The number of active threads may not always be equal to this argument.

  • --flagfile /path/to/commandline-args or @/path/to/commandline-args

    Specify additional command-line arguments in external files (flag files), one argument per line. The arguments in these files can themselves be --flagfile or @ arguments, which would then include a second file's contents as arguments.

    # File config/common
    --verbose
    

    # File config/gcc
    @config/common
    --config
    cxx.cxx=/usr/bin/g++
    ...
    

    # File config/clang
    @config/common
    --config
    cxx.cxx=/usr/bin/clang++
    ...
    

    buck build @config/gcc foo/bar:
    buck build @config/clang foo/bar:
    

    Lines in flag files must not have any leading or trailing white space.

    The equals sign (=) separates the specified property and value. There should be no white space between the property and equals sign, nor between the equals sign and the value.

    We recommend that you use --flagfile rather than the @ symbol as it is more self-describing.

    This --config-file parameter provides functionality similar to --flagfile, but with .buckconfig syntax rather than command-line parameter syntax.

    If Buck is regularly invoked with different sets of arguments, we recommend that you use config files or flag files, as they can be stored in source control, making builds more reproducible.