Skip to content

Commit

Permalink
Update docs site for version 2.19.0rc5 (#131)
Browse files Browse the repository at this point in the history
  • Loading branch information
WorkerPants authored Jan 17, 2024
1 parent 2fef10a commit b351922
Show file tree
Hide file tree
Showing 87 changed files with 90,181 additions and 53,405 deletions.
30 changes: 13 additions & 17 deletions versioned_docs/version-2.19/docs/docker/index.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -182,38 +182,32 @@ Secrets should not be checked into version control. Use absolute paths to refere
See the example for the [`secrets`](../../reference/targets/docker_image.mdx#secrets) field.
:::

### External cache storage backends
### Buildx Support

BuildKit supports exporting build cache to an external location, making it possible to import in future builds. Cache backends can be configured using the [`cache_to`](../../reference/targets/docker_image.mdx#cache_to) and [`cache_from`](../../reference/targets/docker_image.mdx#cache_from) fields.
Buildx (using BuildKit) supports exporting build cache to an external location, making it possible to import in future builds. Cache backends can be configured using the [`cache_to`](../../reference/targets/docker_image.mdx#cache_to) and [`cache_from`](../../reference/targets/docker_image.mdx#cache_from) fields.

Create a builder using a [build driver](https://docs.docker.com/build/drivers/) that is compatible with the cache backend:

```
❯ docker buildx create --name container --driver=docker-container container
```

Use the builder:

```
❯ export BUILDX_BUILDER=container
To use BuildKit with Pants, enable the [Containerd Image Store](https://docs.docker.com/desktop/containerd/), either via [Docker Desktop settings](https://docs.docker.com/storage/containerd/) or by [setting daemon config](https://docs.docker.com/storage/containerd/#enable-containerd-image-store-on-docker-engine):
```json
{
"features": {
"containerd-snapshotter": true
}
}
```

Optionally, validate a build with the Docker CLI directly:
Optionally, run a build with the Docker CLI directly to validate buildx support on your system:

```
❯ docker buildx build -t pants-cache-test:latest \
--cache-to type=local,dest=/tmp/docker/pants-test-cache \
--cache-from type=local,src=/tmp/docker/pants-test-cache .
```

Configure Pants to use buildx and pass the BUILDX_BUILDER environment variable:
Configure Pants to use buildx:

```toml tab={"label":"pants.toml"}
[docker]
use_buildx = true
env_vars = [
"BUILDX_BUILDER"
]
```

```python tab={"label":"example/BUILD"}
Expand All @@ -230,6 +224,8 @@ docker_image(
)
```

For working examples, including multi-platform builds with Github Actions, refer to the [example-docker](https://github.com/pantsbuild/example-docker) repository.

### Build Docker image example

This example copies both a `file` and `pex_binary`. The file is specified as an explicit dependency in the `BUILD` file, whereas the `pex_binary` dependency is inferred from the path in the `Dockerfile`.
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -9,7 +9,7 @@ Creating the configuration necessary to run Pants.

To get started in a new repository, follow these steps, and then visit one of the language-specific overview pages.

1. # Create `pants.toml`
## 1. Create `pants.toml`

Pants configuration lives in a file called `pants.toml` in the root of the repo. This file uses the [TOML](https://github.com/toml-lang/toml) format.

Expand All @@ -22,7 +22,7 @@ pants_version = "$PANTS_VERSION"

where `$PANTS_VERSION` is the version of Pants that you want to pin your repo to. When you'd like to upgrade Pants, edit `pants_version` and the `pants` script will self-update on the next run.

2. # Configure source roots
## 2. Configure source roots

Many languages organize code in a package hierarchy, so that the relative location of a source file on the filesystem corresponds to a logical package name. The directories that correspond to the roots of the language's package hierarchy are referred to as [source roots](../using-pants/key-concepts/source-roots.mdx). These are the filesystem locations from which import paths are computed.

Expand All @@ -38,7 +38,7 @@ If your project has a different structure, see [Source roots](../using-pants/key
Golang projects already use `go.mod` to indicate source roots.
:::

3. # Enable backends
## 3. Enable backends

Most Pants functionality is provided via pluggable [_backends_](../using-pants/key-concepts/backends.mdx), which are activated by adding to the `[GLOBAL].backend_packages` option like this:

Expand All @@ -54,7 +54,7 @@ backend_packages = [

See [here](../using-pants/key-concepts/backends.mdx) for a list of available backends.

4. # Update `.gitignore`
## 4. Update `.gitignore`

If you use Git, we recommend adding these lines to your top-level `.gitignore` file:

Expand All @@ -68,7 +68,7 @@ If you use Git, we recommend adding these lines to your top-level `.gitignore` f
The `pants_ignore` option tells Pants which files to avoid looking at, but it additionally ignores all `.gitignore`d files by default. Occasionally, you will want to ignore something with Git, but still want Pants to work on the file. See [Troubleshooting / common issues](../using-pants/troubleshooting-common-issues.mdx) for how to do this.
:::

5. # Generate BUILD files
## 5. Generate BUILD files

Once you have enabled the backends for the language(s) you'd like to use, run [`pants tailor ::`](./initial-configuration.mdx#5-generate-build-files) to generate an initial set of [BUILD](../using-pants/key-concepts/targets-and-build-files.mdx) files.

Expand Down Expand Up @@ -106,6 +106,6 @@ To fix `tailor` failures, run `pants tailor`.

:::

6. # Visit a language specific overview
## 6. Visit a language specific overview

You're almost ready to go! Next up is visiting one of the language-specific overviews listed below.
Original file line number Diff line number Diff line change
@@ -0,0 +1,41 @@
---
title: go-dump-import-path-mapping
description: |
Dump import paths mapped to package addresses.
---

import Option from "@site/src/components/reference/Option";
import styles from "@site/src/components/reference/styles.module.css";

---

```
pants go-dump-import-path-mapping [args]
```

Dump import paths mapped to package addresses.

Backend: <span className="color--primary">`pants.backend.experimental.go.debug_goals`</span>

Config section: <span className="color--primary">`[go-dump-import-path-mapping]`</span>

<span className={styles.options}>

## Basic options

None

## Advanced options

None

## Deprecated options

None

## Related subsystems

- [environments-preview](../subsystems/environments-preview.mdx)
- [filter](../subsystems/filter.mdx)

</span>
Original file line number Diff line number Diff line change
@@ -0,0 +1,44 @@
---
title: go-export-cgo-codegen
description: |
Export files generated by Cgo.
---

import Option from "@site/src/components/reference/Option";
import styles from "@site/src/components/reference/styles.module.css";

---

```
pants go-export-cgo-codegen [args]
```

Export files generated by Cgo.

Backend: <span className="color--primary">`pants.backend.experimental.go.debug_goals`</span>

Config section: <span className="color--primary">`[go-export-cgo-codegen]`</span>

<span className={styles.options}>

## Basic options

None

## Advanced options

None

## Deprecated options

None

## Related subsystems

- [environments-preview](../subsystems/environments-preview.mdx)
- [filter](../subsystems/filter.mdx)
- [go-test](../subsystems/go-test.mdx)
- [golang](../subsystems/golang.mdx)
- [system-binaries](../subsystems/system-binaries.mdx)

</span>
Original file line number Diff line number Diff line change
@@ -0,0 +1,44 @@
---
title: go-show-package-analysis
description: |
Show the package analysis for Go package targets.
---

import Option from "@site/src/components/reference/Option";
import styles from "@site/src/components/reference/styles.module.css";

---

```
pants go-show-package-analysis [args]
```

Show the package analysis for Go package targets.

Backend: <span className="color--primary">`pants.backend.experimental.go.debug_goals`</span>

Config section: <span className="color--primary">`[go-show-package-analysis]`</span>

<span className={styles.options}>

## Basic options

None

## Advanced options

None

## Deprecated options

None

## Related subsystems

- [environments-preview](../subsystems/environments-preview.mdx)
- [filter](../subsystems/filter.mdx)
- [go-test](../subsystems/go-test.mdx)
- [golang](../subsystems/golang.mdx)
- [system-binaries](../subsystems/system-binaries.mdx)

</span>
Original file line number Diff line number Diff line change
@@ -0,0 +1,45 @@
---
title: java-dump-source-analysis
description: |
Dump source analysis for java_source[s] targets.
---

import Option from "@site/src/components/reference/Option";
import styles from "@site/src/components/reference/styles.module.css";

---

```
pants java-dump-source-analysis [args]
```

Dump source analysis for java_source[s] targets.

Backend: <span className="color--primary">`pants.backend.experimental.java.debug_goals`</span>

Config section: <span className="color--primary">`[java-dump-source-analysis]`</span>

<span className={styles.options}>

## Basic options

None

## Advanced options

None

## Deprecated options

None

## Related subsystems

- [coursier](../subsystems/coursier.mdx)
- [environments-preview](../subsystems/environments-preview.mdx)
- [filter](../subsystems/filter.mdx)
- [jvm](../subsystems/jvm.mdx)
- [python-bootstrap](../subsystems/python-bootstrap.mdx)
- [system-binaries](../subsystems/system-binaries.mdx)

</span>
43 changes: 43 additions & 0 deletions versioned_docs/version-2.19/reference/goals/jvm-symbol-map.mdx
Original file line number Diff line number Diff line change
@@ -0,0 +1,43 @@
---
title: jvm-symbol-map
description: |
Dump the JVM dependency inference symbol mapping.
---

import Option from "@site/src/components/reference/Option";
import styles from "@site/src/components/reference/styles.module.css";

---

```
pants jvm-symbol-map [args]
```

Dump the JVM dependency inference symbol mapping.

Backend: <span className="color--primary">`pants.backend.experimental.java.debug_goals`</span>

Config section: <span className="color--primary">`[jvm-symbol-map]`</span>

<span className={styles.options}>

## Basic options

None

## Advanced options

None

## Deprecated options

None

## Related subsystems

- [environments-preview](../subsystems/environments-preview.mdx)
- [filter](../subsystems/filter.mdx)
- [java-infer](../subsystems/java-infer.mdx)
- [jvm](../subsystems/jvm.mdx)

</span>
Original file line number Diff line number Diff line change
@@ -0,0 +1,45 @@
---
title: kotlin-dump-source-analysis
description: |
Dump source analysis for kotlin_source targets.
---

import Option from "@site/src/components/reference/Option";
import styles from "@site/src/components/reference/styles.module.css";

---

```
pants kotlin-dump-source-analysis [args]
```

Dump source analysis for kotlin_source targets.

Backend: <span className="color--primary">`pants.backend.experimental.kotlin.debug_goals`</span>

Config section: <span className="color--primary">`[kotlin-dump-source-analysis]`</span>

<span className={styles.options}>

## Basic options

None

## Advanced options

None

## Deprecated options

None

## Related subsystems

- [coursier](../subsystems/coursier.mdx)
- [environments-preview](../subsystems/environments-preview.mdx)
- [filter](../subsystems/filter.mdx)
- [jvm](../subsystems/jvm.mdx)
- [python-bootstrap](../subsystems/python-bootstrap.mdx)
- [system-binaries](../subsystems/system-binaries.mdx)

</span>
Loading

0 comments on commit b351922

Please sign in to comment.