Skip to main content

subscribe

This document provides an overview of the commands and options available under buck2 subscribe.

buck2 subscribe​

Open a subscription channel to the Buck2 daemon. This allows you to interact with the Buck2 daemon via the stdin and stdout of this command: you send requests to the daemon by writing to stdin, and you get responses via stdout.

The protocol used by this command is length-prefixed protobuf. This format is a repeated series of a varint followed by a record of the length indicated by said varint.

The protobuf spec for those records is described in buck2_subscription_proto/subscription.proto. The client writes SubscriptionRequest and reads SubscriptionResponse. See the documentation in subscription.proto to discover available APIs.

This API does not (currently) allow invalid requests and will error out when one is sent.

Usage: buck2 subscribe [OPTIONS]

Options:​

  • --active-commands Whether to request command snapshots

  • --unstable-json Whether to get output as JSON. The JSON format is deemed unstable so this should only be used for debugging

  • -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

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

  • --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/&lt;uuid&gt;/command_report even without this flag