profile
These are the flags/commands under buck2 profile and their --help output:
Run starlark profiler
Usage: buck2-release profile [OPTIONS] <COMMAND>
Commands:
analysis Profile analysis
loading Profile `BUCK` file evaluation
bxl Profile BXL script
help Print this message or the help of the given subcommand(s)
Options:
-h, --help
Print help (see a summary with '-h')
Universal Options:
-v, --verbose <VERBOSITY>
How verbose buck should be while logging.
Values: 0 = Quiet, errors only; 1 = Show status. Default; 2 = more info about errors; 3 =
more info about everything; 4 = more info about everything + stderr;
It can be combined with specific log items (stderr, full_failed_command, commands,
actions, status, stats, success) to fine-tune the verbosity of the log. Example usage
"-v=1,stderr"
[default: 1]
--oncall <ONCALL>
The oncall executing this command
--client-metadata <CLIENT_METADATA>
Metadata key-value pairs to inject into Buck2's logging. Client metadata must be of the
form `key=value`, where `key` is a snake_case identifier, and will be sent to backend
datasets
Profile analysis
Usage: buck2-release profile analysis [OPTIONS] --output <PATH> --mode <MODE> [TARGET_PATTERNS]...
Arguments:
[TARGET_PATTERNS]...
Options:
-r, --recursive
In analysis profiling, capture the profile of the target and its dependencies, and output
the merged profile
-o, --output <PATH>
Output file path for profile data.
File will be created if it does not exist, and overwritten if it does.
--mode <MODE>
Profile mode.
Memory profiling modes have suffixes either `-allocated` or `-retained`.
`-retained` means memory kept in frozen starlark heap after analysis complete. `-retained`
does not work when profiling loading, because no memory is retained after loading and
frozen heap is not even created. This is probably what you want when profiling analysis.
`-allocated` means allocated memory, including memory which is later garbage collected.
[possible values: time-flame, heap-allocated, heap-retained, heap-flame-allocated,
heap-flame-retained, heap-summary-allocated, heap-summary-retained, statement, bytecode,
bytecode-pairs, typecheck, coverage, none]
-h, --help
Print help (see a summary with '-h')
Target Configuration Options:
-u, --target-universe <TARGET_UNIVERSE>
Comma separated list of targets to construct a configured target universe.
When the option is specified, command targets are be resolved in this universe.
Additionally, `--target-platforms=` and `--modifier=` flags are be used to configure the
universe targets, not the command targets.
This argument is particularly recommended on most non-trivial cqueries. In the absence of
this argument, buck2 will use the target literals in your cquery expression as the value
for this argument, which may not be what you want.
--target-platforms <PLATFORM>
Configuration target (one) to use to configure targets
-m, --modifier <VALUE>
A configuration modifier to configure all targets on the command line. This may be a
constraint value target.
Buckconfig Options:
-c, --config <SECTION.OPTION=VALUE>
List of config options
--config-file <PATH>
List of config file paths
--fake-host <HOST>
[possible values: default, linux, macos, windows]
--fake-arch <ARCH>
[possible values: default, aarch64, x8664]
--fake-xcode-version <VERSION-BUILD>
Value must be formatted as: version-build (e.g., 14.3.0-14C18 or 14.1-14B47b)
--reuse-current-config
Re-uses any `--config` values (inline or via modefiles) if there's a previous command,
otherwise the flag is ignored.
If there is a previous command and `--reuse-current-config` is set, then the old config is
used, ignoring any overrides.
If there is no previous command but the flag was set, then the flag is ignored, the
command behaves as if the flag was not set at all.
--exit-when-different-state
Used for exiting a concurrent command when a different state is detected
--preemptible <PREEMPTIBLE>
Used to configure when this command could be preempted by another command for the same
isolation dir.
Normally, when you run two commands - from different terminals, say - buck2 will attempt
to run them in parallel. However, if the two commands are based on different state, that
is they either have different configs or different filesystem states, buck2 cannot run
them in parallel. The default behavior in this case is to block the second command until
the first completes.
Possible values:
- never: (default) When another command starts that cannot run in parallel with
this one, block that command
- always: When another command starts, interrupt this command, *even if they
could run in parallel*. There is no good reason to use this other than that it provides
slightly nicer superconsole output
- ondifferentstate: When another command starts that cannot run in parallel with this one,
interrupt this command
Starlark Options:
--disable-starlark-types
Disable runtime type checking in Starlark interpreter.
This option is not stable, and can be used only locally to diagnose evaluation performance
problems.
--stack
Record or show target call stacks.
Starlark call stacks will be included in duplicate targets error.
If a command outputs targets (like `targets` command), starlark call stacks will be
printed after the targets.
Console Options:
--console <super|simple|...>
Which console to use for this command
[env: BUCK_CONSOLE=]
[default: auto]
[possible values: auto, none, simple, simplenotty, simpletty, super]
--ui <UI>...
Configure additional superconsole ui components.
Accepts a comma-separated list of superconsole components to add. Possible values are:
dice - shows information about evaluated dice nodes debugevents - shows information about
the flow of events from buckd
These components can be turned on/off interactively. Press 'h' for help when superconsole
is active.
Possible values:
- dice
- debugevents
- io: I/O panel
- re: RE panel
--no-interactive-console
Disable console interactions
[env: BUCK_NO_INTERACTIVE_CONSOLE=]
Event Log Options:
--event-log <PATH>
Write events to this log file
--write-build-id <PATH>
Write command invocation id into this file
--unstable-write-invocation-record <PATH>
Write the invocation record (as JSON) to this path. No guarantees whatsoever are made
regarding the stability of the format
--command-report-path <PATH>
Write the command report to this path. A command report is always written to
`buck-out/v2/<uuid>/command_report` even without this flag
Universal Options:
-v, --verbose <VERBOSITY>
How verbose buck should be while logging.
Values: 0 = Quiet, errors only; 1 = Show status. Default; 2 = more info about errors; 3 =
more info about everything; 4 = more info about everything + stderr;
It can be combined with specific log items (stderr, full_failed_command, commands,
actions, status, stats, success) to fine-tune the verbosity of the log. Example usage
"-v=1,stderr"
[default: 1]
--oncall <ONCALL>
The oncall executing this command
--client-metadata <CLIENT_METADATA>
Metadata key-value pairs to inject into Buck2's logging. Client metadata must be of the
form `key=value`, where `key` is a snake_case identifier, and will be sent to backend
datasets
Profile `BUCK` file evaluation
Usage: buck2-release profile loading [OPTIONS] --output <PATH> --mode <MODE> [TARGET_PATTERNS]...
Arguments:
[TARGET_PATTERNS]...
Options:
-r, --recursive
In analysis profiling, capture the profile of the target and its dependencies, and output
the merged profile
-o, --output <PATH>
Output file path for profile data.
File will be created if it does not exist, and overwritten if it does.
--mode <MODE>
Profile mode.
Memory profiling modes have suffixes either `-allocated` or `-retained`.
`-retained` means memory kept in frozen starlark heap after analysis complete. `-retained`
does not work when profiling loading, because no memory is retained after loading and
frozen heap is not even created. This is probably what you want when profiling analysis.
`-allocated` means allocated memory, including memory which is later garbage collected.
[possible values: time-flame, heap-allocated, heap-retained, heap-flame-allocated,
heap-flame-retained, heap-summary-allocated, heap-summary-retained, statement, bytecode,
bytecode-pairs, typecheck, coverage, none]
-h, --help
Print help (see a summary with '-h')
Target Configuration Options:
-u, --target-universe <TARGET_UNIVERSE>
Comma separated list of targets to construct a configured target universe.
When the option is specified, command targets are be resolved in this universe.
Additionally, `--target-platforms=` and `--modifier=` flags are be used to configure the
universe targets, not the command targets.
This argument is particularly recommended on most non-trivial cqueries. In the absence of
this argument, buck2 will use the target literals in your cquery expression as the value
for this argument, which may not be what you want.
--target-platforms <PLATFORM>
Configuration target (one) to use to configure targets
-m, --modifier <VALUE>
A configuration modifier to configure all targets on the command line. This may be a
constraint value target.
Buckconfig Options:
-c, --config <SECTION.OPTION=VALUE>
List of config options
--config-file <PATH>
List of config file paths
--fake-host <HOST>
[possible values: default, linux, macos, windows]
--fake-arch <ARCH>
[possible values: default, aarch64, x8664]
--fake-xcode-version <VERSION-BUILD>
Value must be formatted as: version-build (e.g., 14.3.0-14C18 or 14.1-14B47b)
--reuse-current-config
Re-uses any `--config` values (inline or via modefiles) if there's a previous command,
otherwise the flag is ignored.
If there is a previous command and `--reuse-current-config` is set, then the old config is
used, ignoring any overrides.
If there is no previous command but the flag was set, then the flag is ignored, the
command behaves as if the flag was not set at all.
--exit-when-different-state
Used for exiting a concurrent command when a different state is detected
--preemptible <PREEMPTIBLE>
Used to configure when this command could be preempted by another command for the same
isolation dir.
Normally, when you run two commands - from different terminals, say - buck2 will attempt
to run them in parallel. However, if the two commands are based on different state, that
is they either have different configs or different filesystem states, buck2 cannot run
them in parallel. The default behavior in this case is to block the second command until
the first completes.
Possible values:
- never: (default) When another command starts that cannot run in parallel with
this one, block that command
- always: When another command starts, interrupt this command, *even if they
could run in parallel*. There is no good reason to use this other than that it provides
slightly nicer superconsole output
- ondifferentstate: When another command starts that cannot run in parallel with this one,
interrupt this command
Starlark Options:
--disable-starlark-types
Disable runtime type checking in Starlark interpreter.
This option is not stable, and can be used only locally to diagnose evaluation performance
problems.
--stack
Record or show target call stacks.
Starlark call stacks will be included in duplicate targets error.
If a command outputs targets (like `targets` command), starlark call stacks will be
printed after the targets.
Console Options:
--console <super|simple|...>
Which console to use for this command
[env: BUCK_CONSOLE=]
[default: auto]
[possible values: auto, none, simple, simplenotty, simpletty, super]
--ui <UI>...
Configure additional superconsole ui components.
Accepts a comma-separated list of superconsole components to add. Possible values are:
dice - shows information about evaluated dice nodes debugevents - shows information about
the flow of events from buckd
These components can be turned on/off interactively. Press 'h' for help when superconsole
is active.
Possible values:
- dice
- debugevents
- io: I/O panel
- re: RE panel
--no-interactive-console
Disable console interactions
[env: BUCK_NO_INTERACTIVE_CONSOLE=]
Event Log Options:
--event-log <PATH>
Write events to this log file
--write-build-id <PATH>
Write command invocation id into this file
--unstable-write-invocation-record <PATH>
Write the invocation record (as JSON) to this path. No guarantees whatsoever are made
regarding the stability of the format
--command-report-path <PATH>
Write the command report to this path. A command report is always written to
`buck-out/v2/<uuid>/command_report` even without this flag
Universal Options:
-v, --verbose <VERBOSITY>
How verbose buck should be while logging.
Values: 0 = Quiet, errors only; 1 = Show status. Default; 2 = more info about errors; 3 =
more info about everything; 4 = more info about everything + stderr;
It can be combined with specific log items (stderr, full_failed_command, commands,
actions, status, stats, success) to fine-tune the verbosity of the log. Example usage
"-v=1,stderr"
[default: 1]
--oncall <ONCALL>
The oncall executing this command
--client-metadata <CLIENT_METADATA>
Metadata key-value pairs to inject into Buck2's logging. Client metadata must be of the
form `key=value`, where `key` is a snake_case identifier, and will be sent to backend
datasets
Profile BXL script
Usage: buck2-release profile bxl [OPTIONS] --output <PATH> --mode <MODE> <BXL label> [-- <BXL INPUT ARGS>...]
Arguments:
<BXL label>
The bxl function to execute as defined by the label of form
`<cell>//path/file.bxl:<function>`
[BXL INPUT ARGS]...
Arguments passed to the bxl script
Options:
-M, --materializations <MATERIALIZATIONS>
Materialize (or skip) the final artifacts, bypassing buckconfig.
[possible values: all, none]
--upload-final-artifacts <UPLOAD_FINAL_ARTIFACTS>
Upload (or skip) the final artifacts.
[possible values: always, never]
--user-event-log <PATH>
Write user events to this log file. Both user and internal events are written to main
event log. If this flag is specified, user events are additionally written to user event
log. Log format is JSONL, uncompressed if no known extensions are detected, or you can
explicitly specify the compression via the file extension (ex: `.json-lines.gz` would be
gzip compressed, `.json-lines.zst` would be zstd compressed). Resulting log is is
compatible with `buck2 log show-user`
--build-report <PATH>
Print a build report
`--build-report=-` will print the build report to stdout `--build-report=<filepath>` will
write the build report to the file
--enable-optional-validations <VALIDATION_NAMES>
Comma separated list of validation names to run that are marked optional.
By default, validations marked as optional are skipped. This option overrides the
behaviour and executes those validations.
--build-report-options <BUILD_REPORT_OPTIONS>
Comma separated list of build report options.
The following options are supported:
`fill-out-failures`: fill out failures the same way Buck1 would.
`package-project-relative-paths`: emit the project-relative path of packages for the
targets that were built.
-j, --num-threads <THREADS>
Number of threads to use during execution (default is # cores)
--local-only
Enable only local execution. Will reject actions that cannot execute locally
[env: BUCK_OFFLINE_BUILD=]
--remote-only
Enable only remote execution. Will reject actions that cannot execute remotely
--prefer-local
Enable hybrid execution. Will prefer executing actions that can execute locally on the
local host
--prefer-remote
Enable hybrid execution. Will prefer executing actions that can execute remotely on RE and
will avoid racing local and remote execution
--unstable-no-execution
Experimental: Disable all execution
--no-remote-cache
Do not perform remote cache queries or cache writes. If remote execution is enabled, the
RE service might still deduplicate actions, so for e.g. benchmarking, using a random
isolation dir is preferred
[env: BUCK_OFFLINE_BUILD=]
--write-to-cache-anyway
Could be used to enable the action cache writes on the RE worker when no_remote_cache is
specified
--eager-dep-files
Process dep files when they are generated (i.e. after running a command that produces dep
files), rather than when they are used (i.e. before re-running a command that previously
produced dep files). Use this when debugging commands that produce dep files. Note that
commands that previously produced dep files will not re-run: only dep files produced
during this command will be eagerly loaded
--upload-all-actions
Uploads every action to the RE service, regardless of whether the action needs to execute
on RE.
This is useful when debugging builds and trying to inspect actions which executed
remotely. It's possible that the action result is cached but the action itself has
expired. In this case, downloading the action itself would fail. Enabling this option
would unconditionally upload all actions, thus you will not hit any expiration issues.
--fail-fast
If Buck hits an error, do as little work as possible before exiting.
To illustrate the effect of this flag, consider an invocation of `build :foo :bar`. The
default behavior of buck is to do enough work to get a result for the builds of each of
`:foo` and `:bar`, and no more. This means that buck will continue to complete the build
of `:bar` after the build of `:foo` has failed; however, once one dependency of `:foo` has
failed, other dependencies will be cancelled unless they are needed by `:bar`.
This flag changes the behavior of buck to not wait on `:bar` to complete once `:foo` has
failed. Generally, this flag only has an effect on builds that specify multiple targets.
`--keep-going` changes the behavior of buck to not only wait on `:bar` once one dependency
of `:foo` has failed, but to additionally attempt to build other dependencies of `:foo` if
possible.
--keep-going
If Buck hits an error, continue doing as much work as possible before exiting.
See `--fail-fast` for more details.
--skip-missing-targets
If target is missing, then skip building instead of throwing error
--skip-incompatible-targets
If target is incompatible with the specified configuration, skip building instead of
throwing error. This does not apply to targets specified with glob patterns `/...` or `:`
which are skipped unconditionally
--materialize-failed-inputs
Materializes inputs for failed actions which ran on RE
--materialize-failed-outputs
Materializes outputs (if present) for failed actions which ran on RE
-o, --output <PATH>
Output file path for profile data.
File will be created if it does not exist, and overwritten if it does.
--mode <MODE>
Profile mode.
Memory profiling modes have suffixes either `-allocated` or `-retained`.
`-retained` means memory kept in frozen starlark heap after analysis complete. `-retained`
does not work when profiling loading, because no memory is retained after loading and
frozen heap is not even created. This is probably what you want when profiling analysis.
`-allocated` means allocated memory, including memory which is later garbage collected.
[possible values: time-flame, heap-allocated, heap-retained, heap-flame-allocated,
heap-flame-retained, heap-summary-allocated, heap-summary-retained, statement, bytecode,
bytecode-pairs, typecheck, coverage, none]
-h, --help
Print help (see a summary with '-h')
Target Configuration Options:
-u, --target-universe <TARGET_UNIVERSE>
Comma separated list of targets to construct a configured target universe.
When the option is specified, command targets are be resolved in this universe.
Additionally, `--target-platforms=` and `--modifier=` flags are be used to configure the
universe targets, not the command targets.
This argument is particularly recommended on most non-trivial cqueries. In the absence of
this argument, buck2 will use the target literals in your cquery expression as the value
for this argument, which may not be what you want.
--target-platforms <PLATFORM>
Configuration target (one) to use to configure targets
-m, --modifier <VALUE>
A configuration modifier to configure all targets on the command line. This may be a
constraint value target.
Buckconfig Options:
-c, --config <SECTION.OPTION=VALUE>
List of config options
--config-file <PATH>
List of config file paths
--fake-host <HOST>
[possible values: default, linux, macos, windows]
--fake-arch <ARCH>
[possible values: default, aarch64, x8664]
--fake-xcode-version <VERSION-BUILD>
Value must be formatted as: version-build (e.g., 14.3.0-14C18 or 14.1-14B47b)
--reuse-current-config
Re-uses any `--config` values (inline or via modefiles) if there's a previous command,
otherwise the flag is ignored.
If there is a previous command and `--reuse-current-config` is set, then the old config is
used, ignoring any overrides.
If there is no previous command but the flag was set, then the flag is ignored, the
command behaves as if the flag was not set at all.
--exit-when-different-state
Used for exiting a concurrent command when a different state is detected
--preemptible <PREEMPTIBLE>
Used to configure when this command could be preempted by another command for the same
isolation dir.
Normally, when you run two commands - from different terminals, say - buck2 will attempt
to run them in parallel. However, if the two commands are based on different state, that
is they either have different configs or different filesystem states, buck2 cannot run
them in parallel. The default behavior in this case is to block the second command until
the first completes.
Possible values:
- never: (default) When another command starts that cannot run in parallel with
this one, block that command
- always: When another command starts, interrupt this command, *even if they
could run in parallel*. There is no good reason to use this other than that it provides
slightly nicer superconsole output
- ondifferentstate: When another command starts that cannot run in parallel with this one,
interrupt this command
Starlark Options:
--disable-starlark-types
Disable runtime type checking in Starlark interpreter.
This option is not stable, and can be used only locally to diagnose evaluation performance
problems.
--stack
Record or show target call stacks.
Starlark call stacks will be included in duplicate targets error.
If a command outputs targets (like `targets` command), starlark call stacks will be
printed after the targets.
Console Options:
--console <super|simple|...>
Which console to use for this command
[env: BUCK_CONSOLE=]
[default: auto]
[possible values: auto, none, simple, simplenotty, simpletty, super]
--ui <UI>...
Configure additional superconsole ui components.
Accepts a comma-separated list of superconsole components to add. Possible values are:
dice - shows information about evaluated dice nodes debugevents - shows information about
the flow of events from buckd
These components can be turned on/off interactively. Press 'h' for help when superconsole
is active.
Possible values:
- dice
- debugevents
- io: I/O panel
- re: RE panel
--no-interactive-console
Disable console interactions
[env: BUCK_NO_INTERACTIVE_CONSOLE=]
Event Log Options:
--event-log <PATH>
Write events to this log file
--write-build-id <PATH>
Write command invocation id into this file
--unstable-write-invocation-record <PATH>
Write the invocation record (as JSON) to this path. No guarantees whatsoever are made
regarding the stability of the format
--command-report-path <PATH>
Write the command report to this path. A command report is always written to
`buck-out/v2/<uuid>/command_report` even without this flag
Universal Options:
-v, --verbose <VERBOSITY>
How verbose buck should be while logging.
Values: 0 = Quiet, errors only; 1 = Show status. Default; 2 = more info about errors; 3 =
more info about everything; 4 = more info about everything + stderr;
It can be combined with specific log items (stderr, full_failed_command, commands,
actions, status, stats, success) to fine-tune the verbosity of the log. Example usage
"-v=1,stderr"
[default: 1]
--oncall <ONCALL>
The oncall executing this command
--client-metadata <CLIENT_METADATA>
Metadata key-value pairs to inject into Buck2's logging. Client metadata must be of the
form `key=value`, where `key` is a snake_case identifier, and will be sent to backend
datasets