Skip to content

Commit

Permalink
Fix link in bxl developers doc
Browse files Browse the repository at this point in the history
Summary:
The links in bxl developers docs don't work.
I tried to update the `redirects.ts`, but it seems not work. So I just update the link directly.

Reviewed By: JakobDegen

Differential Revision: D65217980

fbshipit-source-id: 3c941169b665459d73de39135c73c418bae1aa57
  • Loading branch information
Nero5023 authored and facebook-github-bot committed Oct 30, 2024
1 parent cf67212 commit 6bdfbc6
Show file tree
Hide file tree
Showing 3 changed files with 31 additions and 35 deletions.
46 changes: 21 additions & 25 deletions docs/developers/bxl_basics.md
Original file line number Diff line number Diff line change
Expand Up @@ -13,16 +13,16 @@ in BXL may be challenging without much prior knowledge of Buck2 building blocks
### Build

You can build targets within BXL with
[`ctx.build()`](../../api/bxl/bxl/Context/#bxl_ctxbuild). The result is a
[`bxl.BuildResult`](../../api/bxl/bxl/BuildResult), which has `artifacts()` and
[`ctx.build()`](../../api/bxl/Context/#contextbuild). The result is a
[`bxl.BuildResult`](../../api/bxl/BuildResult), which has `artifacts()` and
`failures()` functions that provide iterators to the artifacts or failures,
respectively. You can pass in a single target or target pattern to build.

### Analysis

You can run analysis on targets within BXL via
[`ctx.analysis()`](../../api/bxl/bxl/Context/#bxl_ctxanalysis). Analysis means
to evaluate the underlying rule implementation for the inputted targets, and
[`ctx.analysis()`](../../api/bxl/Context/#contextanalysis). Analysis means to
evaluate the underlying rule implementation for the inputted targets, and
produce the providers that the rule defined for the target. A common workflow is
to inspect the resulting providers, and perhaps ensure parts of these providers
or run actions using information from the providers (see [Actions](#actions)
Expand All @@ -34,12 +34,9 @@ Buck2 supports a couple different query types: querying the unconfigured graph
(`buck2 uquery`), the configured graph (`buck2 cquery`), or the action graph
(`buck2 aquery`). These queries are all available in BXL as well:

- `ctx.uquery()` returns a
[`bxl.UqueryContext`](../../api/bxl/bxl/UqueryContext)
- `ctx.cquery()` returns a
[`bxl.CqueryContext`](../../api/bxl/bxl/CqueryContext)
- `ctx.aquery()` returns a
[`bxl.AqueryContext`](../../api/bxl/bxl/AqueryContext)
- `ctx.uquery()` returns a [`bxl.UqueryContext`](../../api/bxl/UqueryContext)
- `ctx.cquery()` returns a [`bxl.CqueryContext`](../../api/bxl/CqueryContext)
- `ctx.aquery()` returns a [`bxl.AqueryContext`](../../api/bxl/AqueryContext)

You can read more about the individual queries in the API docs. There are many
queries that are common between uquery, cquery, and aquery, but cquery and
Expand All @@ -50,13 +47,13 @@ query that takes in the entire query as a string literal. A common use for
entire query string directly into `eval()`.

The query results are target sets (iterable container) of
[`bxl.UnconfiguredTargetNode`s](../../api/bxl/bxl/UnconfiguredTargetNode) for
uquery, [`bxl.ConfiguredTargetNode`s](../../api/bxl/bxl/ConfiguredTargetNode)
for cquery, and [`bxl.ActionQueryNode`s](../../api/bxl/bxl/ActionQueryNode) for
aquery. Each of these node types have accessors on their attributes. A common
workflow is to run some query in BXL, and iterate through the resulting nodes to
inspect their attributes, and use those attributes to inform further
computations in BXL.
[`bxl.UnconfiguredTargetNode`s](../../api/bxl/UnconfiguredTargetNode) for
uquery, [`bxl.ConfiguredTargetNode`s](../../api/bxl/ConfiguredTargetNode) for
cquery, and [`bxl.ActionQueryNode`s](../../api/bxl/ActionQueryNode) for aquery.
Each of these node types have accessors on their attributes. A common workflow
is to run some query in BXL, and iterate through the resulting nodes to inspect
their attributes, and use those attributes to inform further computations in
BXL.

#### Uquery

Expand Down Expand Up @@ -84,8 +81,7 @@ You can create actions directly within the BXL API. The available action APIs
are equivalent to the ones found on the
[`AnalysisActions`](../../api/build/AnalysisActions) type for normal rules, with
the caveat that [dynamic actions](./bxl_dynamic_output.md) use the
[`bxl.Context`](../../api/bxl/bxl/Context) (which provides richer
functionalities).
[`bxl.Context`](../../api/bxl/Context) (which provides richer functionalities).

A common workflow would be to run analysis on a target, and use some interesting
bits found in the analysis result to construct an augmented
Expand All @@ -98,13 +94,13 @@ output (see below for ensuring). Also see
Ensuring an artifact means that you want the artifact to be materialized
(meaning, downloaded to your machine) at the end of the BXL execution. There are
two APIs for ensuring: `ctx.output.ensure()` and `ctx.output.ensure_multiple()`
(see [`bxl.OutputStream`](../../api/bxl/bxl/OutputStream)). As the naming
indicates, the former is for ensuring a single artifact, and the latter is for
ensuring multiple artifact-like inputs. Artifact-like inputs include
(see [`bxl.OutputStream`](../../api/bxl/OutputStream)). As the naming indicates,
the former is for ensuring a single artifact, and the latter is for ensuring
multiple artifact-like inputs. Artifact-like inputs include
[`cmd_args`](../../api/build#cmd_args) (can be found when inspecting providers),
[`bxl.BuildResult`](../../api/bxl/bxl/BuildResult) (produced when building
something in BXL), or [`artifact`](../../api/build/artifact) (can be found when
inspecting providers, or creating your own actions).
[`bxl.BuildResult`](../../api/bxl/BuildResult) (produced when building something
in BXL), or [`artifact`](../../api/build/artifact) (can be found when inspecting
providers, or creating your own actions).

A common workflow is to ensure an artifact that you created via some custom
actions defined in your script, or ensuring some artifacts found in the
Expand Down
4 changes: 2 additions & 2 deletions docs/developers/bxl_common_how_tos.md
Original file line number Diff line number Diff line change
Expand Up @@ -249,12 +249,12 @@ computations, that would also result in errors.

However, if you are not making any assumptions about the existence of these
artifacts, you can use use
[`get_path_without_materialization()`](../../api/bxl/bxl#get_path_without_materialization),
[`get_path_without_materialization()`](../../api/bxl#get_path_without_materialization),
which accepts source, declared, or build aritfacts. It does _not_ accept ensured
artifacts (also see
[What do I need to know about ensured artifacts](./bxl_faq.md#what-do-i-need-to-know-about-ensured-artifacts)).

For getting paths of `cmd_args()` inputs, you can use
[`get_paths_without_materialization()`](../../api/bxl/bxl#get_paths_without_materialization),
[`get_paths_without_materialization()`](../../api/bxl#get_paths_without_materialization),
but note this is risky because the inputs could contain tsets, which, when
expanded, could be very large. Use these methods at your own risk.
16 changes: 8 additions & 8 deletions docs/developers/bxl_getting_started.md
Original file line number Diff line number Diff line change
Expand Up @@ -8,9 +8,9 @@ If you are mostly unfamiliar with Buck2, take a look at

## Navigating the docs

All BXL APIs can be found [here](../../api/bxl/bxl). A good place to start would
be the [`bxl.Context`](../../api/bxl/bxl/Context), which contains all available
BXL functionalities.
All BXL APIs can be found [here](../../api/bxl). A good place to start would be
the [`bxl.Context`](../../api/bxl/Context), which contains all available BXL
functionalities.

The [Build APIs](../../api/build) available and often useful in BXL as well.

Expand Down Expand Up @@ -67,14 +67,14 @@ your_function_name = bxl_main(
```

The implementation function takes a single context as parameter (see the
documentation for [`bxl.Context`](../../api/bxl/bxl/Context)). Using it, you'll
be able to access functions that enable you to perform queries, analysis,
builds, and even create your own actions within BXL to build artifacts as part
of a BXL function.
documentation for [`bxl.Context`](../../api/bxl/Context)). Using it, you'll be
able to access functions that enable you to perform queries, analysis, builds,
and even create your own actions within BXL to build artifacts as part of a BXL
function.

The primary method to return information from BXL is to either print them, or
build some artifact (for details, see the
[`bxl.OutputStream`](../../api/bxl/bxl/OutputStream) documentation, available as
[`bxl.OutputStream`](../../api/bxl/OutputStream) documentation, available as
part of `ctx.output`). At high level, `ctx.output.print(..)` prints results to
stdout, and `ctx.output.ensure(artifact)` marks artifacts as to be materialized
into buck-out by the end of the BXL function, returning an object that lets you
Expand Down

0 comments on commit 6bdfbc6

Please sign in to comment.