Skip to main content

docs

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

buck2 docs​

Print documentation of specified symbols

Usage: buck2 docs <COMMAND>

Subcommands:​

  • starlark: Print documentation of user-defined starlark symbols
  • starlark-builtins: Generate documentation for starlark builtins
  • uquery: Print documentation for query/uquery
  • cquery: Print documentation for cquery
  • aquery: Print documentation for aquery
  • markdown-help-doc: Print out the buck2 subcommand markdown docs

Common Options:​

Common options are documented on the Common Options page.

buck2 docs starlark​

Print documentation of user-defined starlark symbols

Usage: buck2 docs starlark [OPTIONS] [SYMBOL_PATTERNS]...

Arguments:​

  • <SYMBOL_PATTERNS> Patterns to interpret. //foo:bar.bzl is 'every symbol in //foo:bar.bzl', //foo:bar.bzl:baz only returns the documentation for the symbol 'baz' in //foo:bar.bzl

Common Options:​

Common options are documented on the Common Options page.

Options:​

  • --output-dir <OUTPUT_DIR> Directory to write markdown files to. Required if format is markdown_files.

  • --format <FORMAT> how to format the returned documentation

    • Default value: json
    • Possible values:
      • json
      • markdown_files

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

  • --profile-patterns <PROFILE_PATTERNS> Enables profiling for all evaluations whose evaluation identifier matches one of the provided patterns.

    Some examples identifiers: analysis/cell//buck2/app/buck2_action_impl:buck2_action_impl (cfg:linux-x86_64#27ac5723e0c99706) load/cell//build_defs/json.bzl load/prelude//playground/test.bxl load/cell//build_defs/json.bzl@other_cell load_buildfile/fbcode//third-party-buck/platform010/build/ncurses load_packagefile/fbcode//cli/rust/cli_delegate anon_analysis/anon//:_anon_link_rule (anon: 766183dc9b6f680a) (fbcode//buck2/platform/execution:linux-x86_64#08961b14cfb182aa) bxl/prelude//playground/test.bxl:playground

    You can pass --profile-patterns=.* to enable no-op profiling for everything (additionally pass --profile-patterns-mode=none to use no-op profiling to just get a list of all the identifiers).

    The profile results will be written to individual .profile files in <ROOT_OUTPUT>/<data+time>-<uuid>/ where ROOT_OUTPUT comes from the --profile-patterns-output flag. In that directory there will also be a file listing all the identifiers that were profiled.

    Enabling/disabling profiling of an evaluation will invalidate the results of that evaluation and it will be recomputed. In some cases, this will cause other work to also need to be redone (for example, invalidating the result of loading PACKAGE files causes all consumers to be recomputed). But if you keep profiling options consistent between commands, only the work that is otherwise invalidated will be redone (and only for those would profiling results be created).

    You must also pass --profile-patterns-mode and --profile-patterns-output.

  • --profile-patterns-output <PATH>

  • --profile-patterns-mode <PROFILE_PATTERNS_MODE> Profile mode.

    Memory profiling modes have suffixes either -allocated or -retained.

    -retained means memory kept in frozen starlark heaps after analysis completes. -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

buck2 docs starlark-builtins​

Generate documentation for starlark builtins.

This command is designed to support buck2's doc generation and does not have stable output.

Usage: buck2 docs starlark-builtins [OPTIONS] --output-dir <OUTPUT_DIR>

Common Options:​

Common options are documented on the Common Options page.

Options:​

  • --output-dir <OUTPUT_DIR> The directory to output files to

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

  • --profile-patterns <PROFILE_PATTERNS> Enables profiling for all evaluations whose evaluation identifier matches one of the provided patterns.

    Some examples identifiers: analysis/cell//buck2/app/buck2_action_impl:buck2_action_impl (cfg:linux-x86_64#27ac5723e0c99706) load/cell//build_defs/json.bzl load/prelude//playground/test.bxl load/cell//build_defs/json.bzl@other_cell load_buildfile/fbcode//third-party-buck/platform010/build/ncurses load_packagefile/fbcode//cli/rust/cli_delegate anon_analysis/anon//:_anon_link_rule (anon: 766183dc9b6f680a) (fbcode//buck2/platform/execution:linux-x86_64#08961b14cfb182aa) bxl/prelude//playground/test.bxl:playground

    You can pass --profile-patterns=.* to enable no-op profiling for everything (additionally pass --profile-patterns-mode=none to use no-op profiling to just get a list of all the identifiers).

    The profile results will be written to individual .profile files in <ROOT_OUTPUT>/<data+time>-<uuid>/ where ROOT_OUTPUT comes from the --profile-patterns-output flag. In that directory there will also be a file listing all the identifiers that were profiled.

    Enabling/disabling profiling of an evaluation will invalidate the results of that evaluation and it will be recomputed. In some cases, this will cause other work to also need to be redone (for example, invalidating the result of loading PACKAGE files causes all consumers to be recomputed). But if you keep profiling options consistent between commands, only the work that is otherwise invalidated will be redone (and only for those would profiling results be created).

    You must also pass --profile-patterns-mode and --profile-patterns-output.

  • --profile-patterns-output <PATH>

  • --profile-patterns-mode <PROFILE_PATTERNS_MODE> Profile mode.

    Memory profiling modes have suffixes either -allocated or -retained.

    -retained means memory kept in frozen starlark heaps after analysis completes. -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

buck2 docs uquery​

Print documentation for query/uquery

Usage: buck2 docs uquery [OPTIONS]

Common Options:​

Common options are documented on the Common Options page.

Options:​

  • --format <FORMAT> How to format the documentation

    • Default value: rendered
    • Possible values:
      • markdown
      • rendered

buck2 docs cquery​

Print documentation for cquery

Usage: buck2 docs cquery [OPTIONS]

Common Options:​

Common options are documented on the Common Options page.

Options:​

  • --format <FORMAT> How to format the documentation

    • Default value: rendered
    • Possible values:
      • markdown
      • rendered

buck2 docs aquery​

Print documentation for aquery

Usage: buck2 docs aquery [OPTIONS]

Common Options:​

Common options are documented on the Common Options page.

Options:​

  • --format <FORMAT> How to format the documentation

    • Default value: rendered
    • Possible values:
      • markdown
      • rendered

buck2 docs markdown-help-doc​

Print out the buck2 subcommand markdown docs

Usage: buck2 docs markdown-help-doc <SUB_COMMAND>

Arguments:​

  • <SUB_COMMAND> The buck2 sub command we want to generate the markdown doc

Common Options:​

Common options are documented on the Common Options page.