From d68eb60563ef4d34b6b3e4750467d8c96297bfdf Mon Sep 17 00:00:00 2001 From: "Worker Pants (Pantsbuild GitHub Automation Bot)" Date: Thu, 8 Aug 2024 18:32:30 +0000 Subject: [PATCH] Update docs site for version 2.23.0.dev6 --- .../overview/enabling-javascript-support.mdx | 5 + docs/docs/python/integrations/aws-lambda.mdx | 53 +- .../integrations/google-cloud-functions.mdx | 50 +- docs/docs/terraform/index.mdx | 12 +- docs/docs/using-pants/environments.mdx | 1 + .../using-pants/key-concepts/backends.mdx | 3 + .../plugin-upgrade-guide.mdx | 66 + docs/reference/global-options.mdx | 6 +- docs/reference/goals/experimental-bsp.mdx | 2 +- docs/reference/goals/export.mdx | 36 +- .../goals/java-dump-source-analysis.mdx | 1 + .../goals/kotlin-dump-source-analysis.mdx | 1 + .../goals/scala-dump-source-analysis.mdx | 1 + docs/reference/help-all.json | 4860 ++++++++++++----- docs/reference/subsystems/coursier.mdx | 2 +- .../subsystems/download-terraform.mdx | 18 + .../subsystems/google-java-format.mdx | 2 +- docs/reference/subsystems/jar_tool.mdx | 104 + docs/reference/subsystems/jarjar.mdx | 2 +- docs/reference/subsystems/java-avro.mdx | 2 +- docs/reference/subsystems/java-parser.mdx | 104 + docs/reference/subsystems/junit.mdx | 4 +- docs/reference/subsystems/jvm.mdx | 2 +- docs/reference/subsystems/kotlin-parser.mdx | 104 + docs/reference/subsystems/ktlint.mdx | 2 +- docs/reference/subsystems/nodejs-infer.mdx | 19 + .../subsystems/openapi-generator.mdx | 2 +- .../subsystems/protobuf-java-grpc.mdx | 2 +- docs/reference/subsystems/python-infer.mdx | 4 +- docs/reference/subsystems/scala-parser.mdx | 104 + docs/reference/subsystems/scalafix.mdx | 2 +- docs/reference/subsystems/scalafmt.mdx | 2 +- docs/reference/subsystems/scalapb.mdx | 2 +- docs/reference/subsystems/scalatest.mdx | 2 +- docs/reference/subsystems/scrooge.mdx | 2 +- docs/reference/subsystems/strip-jar.mdx | 104 + docs/reference/targets/java_source.mdx | 2 +- docs/reference/targets/java_sources.mdx | 2 +- docs/reference/targets/jsx_source.mdx | 77 + docs/reference/targets/jsx_sources.mdx | 109 + docs/reference/targets/jsx_test.mdx | 129 + docs/reference/targets/jsx_tests.mdx | 161 + docs/reference/targets/junit_test.mdx | 2 +- docs/reference/targets/junit_tests.mdx | 2 +- docs/reference/targets/jvm_artifact.mdx | 2 +- docs/reference/targets/pants_requirements.mdx | 2 +- .../targets/python_aws_lambda_function.mdx | 11 + .../targets/python_aws_lambda_layer.mdx | 11 + docs/reference/targets/python_requirement.mdx | 4 +- docs/reference/targets/scala_artifact.mdx | 4 +- docs/reference/targets/scala_junit_test.mdx | 2 +- docs/reference/targets/scala_junit_tests.mdx | 2 +- docs/reference/targets/scala_source.mdx | 2 +- docs/reference/targets/scala_sources.mdx | 2 +- docs/reference/targets/scalac_plugin.mdx | 2 +- docs/reference/targets/scalatest_test.mdx | 2 +- docs/reference/targets/scalatest_tests.mdx | 2 +- 57 files changed, 4932 insertions(+), 1288 deletions(-) create mode 100644 docs/reference/subsystems/jar_tool.mdx create mode 100644 docs/reference/subsystems/java-parser.mdx create mode 100644 docs/reference/subsystems/kotlin-parser.mdx create mode 100644 docs/reference/subsystems/scala-parser.mdx create mode 100644 docs/reference/subsystems/strip-jar.mdx create mode 100644 docs/reference/targets/jsx_source.mdx create mode 100644 docs/reference/targets/jsx_sources.mdx create mode 100644 docs/reference/targets/jsx_test.mdx create mode 100644 docs/reference/targets/jsx_tests.mdx diff --git a/docs/docs/javascript/overview/enabling-javascript-support.mdx b/docs/docs/javascript/overview/enabling-javascript-support.mdx index c90076a2c..d4a1518ae 100644 --- a/docs/docs/javascript/overview/enabling-javascript-support.mdx +++ b/docs/docs/javascript/overview/enabling-javascript-support.mdx @@ -38,6 +38,11 @@ Created project/BUILD: - Add javascript_tests target tests ``` +:::tip Improved inference and introspection for bundled projects +For [dependency inference](../../introduction/how-does-pants-work.mdx#dependency-inference), Pants reads both your +projects' `package.json` sections and additionally +supports [`jsconfig.json`](https://code.visualstudio.com/docs/languages/jsconfig), if one is present. +::: ### Setting up node Pants will by default download a distribution of `node` according to the diff --git a/docs/docs/python/integrations/aws-lambda.mdx b/docs/docs/python/integrations/aws-lambda.mdx index e415944af..a309a2e61 100644 --- a/docs/docs/python/integrations/aws-lambda.mdx +++ b/docs/docs/python/integrations/aws-lambda.mdx @@ -33,7 +33,7 @@ First, add your lambda function in a Python file like you would [normally do wit Then, in your BUILD file, make sure that you have a `python_source` or `python_sources` target with the handler file included in the `sources` field. You can use [`pants tailor ::`](../../getting-started/initial-configuration.mdx#5-generate-build-files) to automate this. -Add a `python_aws_lambda_function` target and define the `runtime` and `handler` fields. The `runtime` should be one of the values from [https://docs.aws.amazon.com/lambda/latest/dg/lambda-python.html](https://docs.aws.amazon.com/lambda/latest/dg/lambda-python.html). The `handler` has the form `handler_file.py:handler_func`, which Pants will convert into a well-formed entry point. Alternatively, you can set `handler` to the format `path.to.module:handler_func`. +Add a `python_aws_lambda_function` target and define the `handler` fields. The `handler` has the form `handler_file.py:handler_func`, which Pants will convert into a well-formed entry point. Alternatively, you can set `handler` to the format `path.to.module:handler_func`. For example: @@ -43,7 +43,6 @@ python_sources(name="lib") python_aws_lambda_function( name="lambda", - runtime="python3.8", # Pants will convert this to `project.lambda_example:example_handler`. handler="lambda_example.py:example_handler", ) @@ -66,6 +65,49 @@ Use [layout](../../../reference/targets/python_aws_lambda_function.mdx#layout) t `file` / `files` targets will not be included in the built AWS Lambda artifacts because filesystem APIs like `open()` would not load them as expected. Instead, use the `resource` and `resources` target. See [Assets and archives](../../using-pants/assets-and-archives.mdx) for further explanation. ::: +### Specifying a runtime explicitly + +When building an Lambda artifact, Pants and the underlying Pex tool need to know details about target runtime to be able to choose appropriate artifacts for third-party dependencies that have native code. These details can be inferred or provided in three ways, from highest precedence to lowest precedence: + +1. An explicit value for [the `complete_platforms` field](../../../reference/targets/python_aws_lambda_function.mdx#complete_platforms). The "complete platforms" are the underlying source of truth. + ```python title="BUILD" + file(name="lambda-platform", source="lambda-platform.json") + + python_aws_lambda_function( + name="lambda", + handler="lambda_example.py:example_handler", + # Explicit complete platforms: + complete_platforms=[":lambda-platform"], + ) + ``` +2. An explicit value for [the `runtime` field](../../../reference/targets/python_aws_lambda_function.mdx#runtime) and, optionally, [the `architecture` field](../../../reference/targets/python_aws_lambda_function.mdx#architecture): Pants uses these to pick an appropriate "complete platforms" value, from options that Pants has pre-packaged. These are static exports from docker images provided by AWS, relying on the environment being relatively stable. (If Pants doesn't have an appropriate "complete platforms" default built-in, you will be prompted to use option 1 above.) + ```python title="BUILD" + python_aws_lambda_function( + name="lambda", + handler="lambda_example.py:example_handler", + # Explicit runtime, `complete_platforms` taken from Pants' built-in defaults: + runtime="python3.12", + # Override the default x86_64 architecture: + architecture="arm64", + ) + ``` +3. Inferred from [the relevant interpreter constraints](../overview/interpreter-compatibility.mdx): the interpreter constraints may unambiguously imply a value for the `runtime` and thus `complete_platforms` fields. For example, `interpreter_constaints = ["==3.12.*"]` implies `runtime="python3.12"`. This only works with interpreter constraints that cover all patch versions of a given minor release series: `>=3.11,<3.13` is too wide (it covers both 3.11 and 3.12), while `==3.12.0` is too specific (AWS's `python3.12` runtime may not use that exact patch version). As with option 2, the architecture is `x86_64` by default, but can changed using the `architecture` field. + + ```toml tab={"label":"pants.toml"} + [python] + interpreter_constraints = ["==3.12.*"] + ``` + ```python tab={"label":"project/BUILD"} + python_aws_lambda_function( + name="lambda", + handler="lambda_example.py:example_handler", + # `runtime` inferred and `complete_platforms` from built-in defaults, + # `architecture` defaults to x86_64, but can be overridden + ) + ``` + +This guide is written using the last option, with the default `x86_64` architecture, but you can add `runtime`, `complete_platforms` and/or `architecture` to any examples using the `python_aws_lambda_function` or `python_aws_lambda_layer` targets. + ## Step 3: Run `package` Now run `pants package` on your `python_aws_lambda_function` target to create a zipped file. @@ -118,7 +160,6 @@ python_sources() python_aws_lambda_function( name="lambda", - runtime="python3.8", handler="main.py:lambda_handler" ) @@ -148,7 +189,6 @@ python_sources(name="lib") python_aws_lambda_function( name="function", - runtime="python3.8", handler="lambda_example.py:example_handler", # only include the sources, the boto3 requirement is packaged in `:layer` include_requirements=False, @@ -156,7 +196,6 @@ python_aws_lambda_function( python_aws_lambda_layer( name="layer", - runtime="python3.8" # specify the handler file, and pants will automatically find its transitive dependencies dependencies=["./lambda_example.py"], # only include the boto3 requirement, any sources are packaged in `:function` @@ -198,8 +237,8 @@ python_sources() pex_binary( name="lambda", entry_point="lambda_example.py", - # specify an appropriate platform(s) for the targeted Lambda runtime (complete_platforms works too) - platforms=["linux_x86_64-cp39-cp39"], + # specify an appropriate platform for the targeted Lambda runtime: + complete_platforms=["path/to:platform-json-target"], ) ``` diff --git a/docs/docs/python/integrations/google-cloud-functions.mdx b/docs/docs/python/integrations/google-cloud-functions.mdx index 4605f6fc4..6eccb1cf5 100644 --- a/docs/docs/python/integrations/google-cloud-functions.mdx +++ b/docs/docs/python/integrations/google-cloud-functions.mdx @@ -33,7 +33,7 @@ First, add your Cloud function in a Python file like you would [normally do with Then, in your BUILD file, make sure that you have a `python_source` or `python_sources` target with the handler file included in the `sources` field. You can use [`pants tailor ::`](../../getting-started/initial-configuration.mdx#5-generate-build-files) to automate this. -Add a `python_google_cloud_function` target and define the `runtime`, `handler`, and `type` fields. The `type` should be either `"event"` or `"http"`. The `runtime` should be one of the values from [https://cloud.google.com/functions/docs/concepts/python-runtime](https://cloud.google.com/functions/docs/concepts/python-runtime). The `handler` has the form `handler_file.py:handler_func`, which Pants will convert into a well-formed entry point. Alternatively, you can set `handler` to the format `path.to.module:handler_func`. +Add a `python_google_cloud_function` target and define `handler` and `type` fields. The `type` should be either `"event"` or `"http"`. The `handler` has the form `handler_file.py:handler_func`, which Pants will convert into a well-formed entry point. Alternatively, you can set `handler` to the format `path.to.module:handler_func`. For example: @@ -43,7 +43,6 @@ python_sources(name="lib") python_google_cloud_function( name="cloud_function", - runtime="python38", # Pants will convert this to `project.google_cloud_function_example:example_handler`. handler="google_cloud_function_example.py:example_handler", type="event", @@ -67,6 +66,49 @@ Use [layout](../../../reference/targets/python_google_cloud_function.mdx#layout) `file` / `files` targets will not be included in the built Cloud Function because filesystem APIs like `open()` would not load them as expected. Instead, use the `resource` / `resources` target. See [Assets and archives](../../using-pants/assets-and-archives.mdx) for further explanation. ::: +### Specifying a runtime explicitly + +When building an Cloud function artifact, Pants and the underlying Pex tool need to know details about target runtime to be able to choose appropriate artifacts for third-party dependencies that have native code. These details can be inferred or provided in three ways, from highest precedence to lowest precedence: + +1. An explicit value for [the `complete_platforms` field](../../../reference/targets/python_google_cloud_function.mdx#complete_platforms). The "complete platforms" are the underlying source of truth. + ```python title="BUILD" + file(name="gcf-platform", source="gcf-platform.json") + + python_google_cloud_function( + name="cloud_function", + handler="google_cloud_function_example.py:example_handler", + type="event", + # Explicit complete platforms: + complete_platforms=[":gcf-platform"], + ) + ``` +2. An explicit value for [the `runtime` field](../../../reference/targets/python_google_cloud_function.mdx#runtime): Pants uses this to pick an appropriate "complete platforms" value, from options that Pants has pre-packaged. These are static exports from docker images provided by GCP, relying on the environment being relatively stable. (If Pants doesn't have an appropriate "complete platforms" default built-in, you will be prompted to use option 1 above.) + ```python title="BUILD" + python_google_cloud_function( + name="cloud_function", + handler="google_cloud_function_example.py:example_handler", + type="event", + # Explicit runtime, `complete_platforms` taken from Pants' built-in defaults: + runtime="python312", + ) + ``` +3. Inferred from [the relevant interpreter constraints](../overview/interpreter-compatibility.mdx): the interpreter constraints may unambiguously imply a value for the `runtime` and thus `complete_platforms` fields. For example, `interpreter_constaints = ["==3.12.*"]` implies `runtime="python312"`. This only works with interpreter constraints that cover all patch versions of a given minor release series: `>=3.11,<3.13` is too wide (it covers both 3.11 and 3.12), while `==3.12.0` is too specific (GCF's `python312` runtime may not use that exact patch version). + + ```toml tab={"label":"pants.toml"} + [python] + interpreter_constraints = ["==3.12.*"] + ``` + ```python tab={"label":"project/BUILD"} + python_google_cloud_function( + name="cloud_function", + handler="google_cloud_function_example.py:example_handler", + type="event", + # `runtime` inferred and `complete_platforms` from built-in defaults + ) + ``` + +This guide is written using the last option, but you can add `runtime` or `complete_platforms` to any examples using the `python_google_cloud_function` target. + ## Step 3: Run `package` Now run `pants package` on your `python_google_cloud_function` target to create a zipped file. @@ -119,8 +161,8 @@ python_sources() pex_binary( name="gcf", entry_point="gcf_example.py", - # specify an appropriate platform(s) for the targeted GCF runtime (complete_platforms works too) - platforms=["linux_x86_64-cp39-cp39"], + # specify an appropriate platform for the targeted GCF runtime: + complete_platforms=["path/to:platform-json-target"], ) ``` diff --git a/docs/docs/terraform/index.mdx b/docs/docs/terraform/index.mdx index 37f271e37..6f69c2fff 100644 --- a/docs/docs/terraform/index.mdx +++ b/docs/docs/terraform/index.mdx @@ -8,7 +8,8 @@ :::caution Terraform support is in alpha stage Pants is currently building support for developing and deploying Terraform. Simple use cases might be supported, but many options are missing. -Please share feedback for what you need to use Pants with your Terraform modules and deployments by either [opening a GitHub issue](https://github.com/pantsbuild/pants/issues/new/choose) or [joining our Slack](/community/getting-help)! +Terraform release progress is tracked in the [stability for release issue](https://github.com/pantsbuild/pants/issues/21119). +Please share feedback for what you need to use Pants with your Terraform modules and deployments by commenting on that issue, [opening a new GitHub issue](https://github.com/pantsbuild/pants/issues/new/choose) or [joining our Slack](/community/getting-help)! ::: ## Initial setup @@ -83,6 +84,8 @@ terraform_deployment(name="test", root_module=":root", dependencies=["test_backe Lockfiles will be loaded from the directory of the root module of a deployment, just like with the `terraform` command. Pants will automatically generate targets for them if they exist. +Pants can generate and update lockfiles with the `generate-lockfiles` command. Use the target of the `terraform_module`'s address as the resolve name. For example, `pants generate-lockfiles --resolve=tf:infrastructure`. + ```python tab={"label":"prod/BUILD"} terraform_deployment(name="prod", root_module="//tf:infrastructure") ``` @@ -119,7 +122,12 @@ provider "registry.terraform.io/hashicorp/null" { } ``` -Pants can generate and update lockfiles with the `generate-lockfiles` command. Use the target of the `terraform_module`'s address as the resolve name. For example, `pants generate-lockfiles --resolve=tf:infrastructure`. +Pants can generate multi-platform lockfiles for Terraform. The setting `[download-terraform].platforms` uses the same values as [Terraform's multi-platform implementation](https://developer.hashicorp.com/terraform/cli/commands/providers/lock#specifying-target-platforms). + +```toml title=pants.toml +[download_terraform] +platforms = ["windows_amd64", "darwin_amd64", "linux_amd64"] +``` ### Basic Operations diff --git a/docs/docs/using-pants/environments.mdx b/docs/docs/using-pants/environments.mdx index f08abe9c8..67a64a305 100644 --- a/docs/docs/using-pants/environments.mdx +++ b/docs/docs/using-pants/environments.mdx @@ -266,3 +266,4 @@ The special environment name `__local_workspace__` can be used to select a match There is no `fallback_environment=` atribute on `workspace_enviroment` targets because in-workspace execution differs significantly from the other environemnts due to the lack of an execution sandbox. +Also, workspace environments change how the `output_files` and `output_directories` fields are interpreted for the `adhoc_tool` and `shell_command` target types. For most invoked processes, Pants will interpret `output_files` and `output_directories` as relative paths relative to the configured working directory from the `workdir` field. This is fine for most executions because they run in a sandbox environment and the base for capturing outputs is exactly the same as the working directory for the invoked process. For in-workspace execution executions, however, this interpretation is not correct because the base for capturing outputs for in-workspace executions is _not_ the same as the working directory for the invoked process. Specifically, in-workspace executions capture from the root of the temporary sandbox directory used during execution and not from the working directory in the workspace. diff --git a/docs/docs/using-pants/key-concepts/backends.mdx b/docs/docs/using-pants/key-concepts/backends.mdx index 829fa8146..4895770fa 100644 --- a/docs/docs/using-pants/key-concepts/backends.mdx +++ b/docs/docs/using-pants/key-concepts/backends.mdx @@ -65,6 +65,7 @@ The list of all backends (both stable and experimental) is also available via `p | Backend | What it does | Docs | | :----------------------------------------------------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------- | :---------------------------------------------------------------------------------------------------- | | `pants.backend.experimental.adhoc` | Enables support for executing arbitrary runnable targets. | [Integrating new tools without plugins](../../ad-hoc-tools/integrating-new-tools-without-plugins.mdx) | +| `pants.backend.experimental.bsp` | Enables core Build Server Protocol ("BSP") support. | | | `pants.backend.experimental.cc` | Enables core C and C++ support. | | | `pants.backend.experimental.cc.lint.clangformat` | Enables clang-format, a C and C++ autoformatter: [https://clang.llvm.org/docs/ClangFormat.html](https://clang.llvm.org/docs/ClangFormat.html) | | | `pants.backend.experimental.codegen.avro.java` | Enables generating Java from Avro | | @@ -83,6 +84,7 @@ The list of all backends (both stable and experimental) is also available via `p | `pants.backend.experimental.helm` | Enables core Helm support: [https://helm.sh](https://helm.sh) | [Helm overview](../../helm/index.mdx) | | `pants.backend.experimental.helm.check.kubeconfirm` | Enables Kubeconform, a fast Kubernetes manifest validator: [https://github.com/yannh/kubeconform](https://github.com/yannh/kubeconform) | [Helm overview](../../helm/index.mdx) | | `pants.backend.experimental.java` | Enables core Java support. | [Java & Scala overview](../../jvm/java-and-scala.mdx) | +| `pants.backend.experimental.java.bsp` | Enable Java-specific support for Build Server Protocol | [Java & Scala overview](../../jvm/java-and-scala.mdx) | | `pants.backend.experimental.java.debug_goals` | Enable additional goals for introspecting Java targets | [Java & Scala overview](../../jvm/java-and-scala.mdx) | | `pants.backend.experimental.java.lint.google_java_format` | Enables Google Java Format. | [Java & Scala overview](../../jvm/java-and-scala.mdx) | | `pants.backend.experimental.javascript` | Enables core JavaScript support. | | @@ -105,6 +107,7 @@ The list of all backends (both stable and experimental) is also available via `p | `pants.backend.experimental.python.typecheck.pytype` | Enables Pytype, a Python type checker: [https://google.github.io/pytype/](https://google.github.io/pytype/) | | | `pants.backend.experimental.rust` | Enables core Rust support. | | | `pants.backend.experimental.scala` | Enables core Scala support. | [Java & Scala overview](../../jvm/java-and-scala.mdx) | +| `pants.backend.experimental.scala.bsp` | Enables Scala-specific support for Build Server Protocol | [Java & Scala overview](../../jvm/java-and-scala.mdx) | | `pants.backend.experimental.scala.debug_goals` | Enables additional goals for introspecting Scala targets | [Java & Scala overview](../../jvm/java-and-scala.mdx) | | `pants.backend.experimental.scala.lint.scalafmt` | Enables the Scalafmt formatter. | [Java & Scala overview](../../jvm/java-and-scala.mdx) | | `pants.backend.experimental.swift` | Enables core Swift support. | | diff --git a/docs/docs/writing-plugins/common-plugin-tasks/plugin-upgrade-guide.mdx b/docs/docs/writing-plugins/common-plugin-tasks/plugin-upgrade-guide.mdx index ef7db260c..bbafe2e00 100644 --- a/docs/docs/writing-plugins/common-plugin-tasks/plugin-upgrade-guide.mdx +++ b/docs/docs/writing-plugins/common-plugin-tasks/plugin-upgrade-guide.mdx @@ -7,6 +7,72 @@ How to adjust for changes made to the Plugin API. --- +## 2.23 + +### Deprecated GenerateToolLockfileSentinel + +`GenerateToolLockfileSentinel` was used to generate lockfiles. It is deprecated in favour of `ExportableTool`. + +```python title=Before +class JarJar(JvmToolBase): + ... + +class JarJarGeneratorLockfileSentinel(GenerateToolLockfileSentinel): + resolve_name = JarJar.options_scope + + +@rule +async def generate_jarjar_lockfile_request( + _: JarJarGeneratorLockfileSentinel, jarjar: JarJar +) -> GenerateJvmLockfileFromTool: + return GenerateJvmLockfileFromTool.create(jarjar) + + +def rules(): + return [..., UnionRule(GenerateToolLockfileSentinel, JarJarGeneratorLockfileSentinel)] +``` + +```python title=After +class JarJar(JvmToolBase): + ... + +def rules(): + return [..., UnionRule(ExportableTool, JarJar)] +``` + +#### JVM: Deprecated Get(GenerateJvmLockfileFromTool, GenerateToolLockfileSentinel) for lockfiles + +As part of the deprecation, `GenerateJvmLockfileFromTool` can be invoked directly on your tool, without a Get. You may need to request your `JvmToolBase` + +```python title=Before +@rule +async def shade_jar(request: ShadeJarRequest, jdk: InternalJdk, jarjar: JarJar) -> ShadedJar: + ... + lockfile_request = await Get(GenerateJvmLockfileFromTool, JarJarGeneratorLockfileSentinel()) + + tool_classpath = await Get(ToolClasspath, ToolClasspathRequest(lockfile=lockfile_request)) +``` + +```python title=After +@rule +async def shade_jar(request: ShadeJarRequest, jdk: InternalJdk, jarjar: JarJar) -> ShadedJar: + ... + await Get( + ToolClasspath, ToolClasspathRequest(lockfile=GenerateJvmLockfileFromTool.create(jarjar)) + ) +``` + +### JVM: Migrating from GenerateJvmLockfileFromTool to JvmToolBase + +`JvmToolBase` is the preferred way to define JVM-based tools. + +1. set the `options_scope`, usually to the `resolve_name` +2. set the `help` +3. `default_artifacts` is the `artifact_inputs` converted to a tuple. A version can be replaced by `{version}` and moved to the `default_version` field +4. `default_lockfile_resource` is the same + +A `GenerateJvmLockfileFromTool` is created from a `JvmToolBase` with `GenerateJvmLockfileFromTool.create` + ## 2.17 ### Deprecated some `Request` types in favor of `Get` with only one arg diff --git a/docs/reference/global-options.mdx b/docs/reference/global-options.mdx index f988112fc..be4036ce6 100644 --- a/docs/reference/global-options.mdx +++ b/docs/reference/global-options.mdx @@ -154,7 +154,11 @@ Pants is switching its option parsing system from a legacy parser written in Pyt The results of parsing a given option by each system should be identical. However during a transition period we will run both parsers and compare their results. This option controls how to report discrepancies that arise. -- `error`: Discrepancies will cause Pants to exit. - `warning`: Discrepancies will be logged but Pants will continue. - `ignore`: A last resort to turn off this check entirely. +- `error`: Discrepancies will cause Pants to exit. + +- `warning`: Discrepancies will be logged but Pants will continue. + +- `ignore`: A last resort to turn off this check entirely. If you encounter discrepancies that are not easily resolvable, please reach out to us on Slack or file an issue: https://www.pantsbuild.org/community/getting-help. diff --git a/docs/reference/goals/experimental-bsp.mdx b/docs/reference/goals/experimental-bsp.mdx index 2defb2d96..8ab9ad971 100644 --- a/docs/reference/goals/experimental-bsp.mdx +++ b/docs/reference/goals/experimental-bsp.mdx @@ -15,7 +15,7 @@ pants experimental-bsp [args] Setup repository for Build Server Protocol (https://build-server-protocol.github.io/). -Backend: `pants.goal` +Backend: `pants.backend.experimental.bsp` Config section: `[experimental-bsp]` diff --git a/docs/reference/goals/export.mdx b/docs/reference/goals/export.mdx index 43e23b25f..4a40104b2 100644 --- a/docs/reference/goals/export.mdx +++ b/docs/reference/goals/export.mdx @@ -29,24 +29,6 @@ Config section: `[export]` ## Basic options -### `py_generated_sources_in_resolve` - - - ### `py_resolve_format` + ### `py_non_hermetic_scripts_in_resolve` +### `platforms` + + + ### `tailor` +### `unowned_dependency_behavior` + + + ## Advanced options None diff --git a/docs/reference/subsystems/openapi-generator.mdx b/docs/reference/subsystems/openapi-generator.mdx index db464bc0f..41c78cae1 100644 --- a/docs/reference/subsystems/openapi-generator.mdx +++ b/docs/reference/subsystems/openapi-generator.mdx @@ -73,7 +73,7 @@ lockfile = `} Path to a lockfile used for installing the tool. -Set to the string `` to use a lockfile provided by Pants, so long as you have not changed the `--version` option. See https://github.com/pantsbuild/pants/blob/release_2.23.0.dev5/src/python/pants/backend/openapi/subsystems/openapi_generator.default.lockfile.txt for the default lockfile contents. +Set to the string `` to use a lockfile provided by Pants, so long as you have not changed the `--version` option. See https://github.com/pantsbuild/pants/blob/release_2.23.0.dev6/src/python/pants/backend/openapi/subsystems/openapi_generator.default.lockfile.txt for the default lockfile contents. To use a custom lockfile, set this option to a file path relative to the build root, then run `pants jvm-generate-lockfiles --resolve=openapi-generator`. diff --git a/docs/reference/subsystems/protobuf-java-grpc.mdx b/docs/reference/subsystems/protobuf-java-grpc.mdx index b9263d2c4..21af040d0 100644 --- a/docs/reference/subsystems/protobuf-java-grpc.mdx +++ b/docs/reference/subsystems/protobuf-java-grpc.mdx @@ -73,7 +73,7 @@ lockfile = `} Path to a lockfile used for installing the tool. -Set to the string `` to use a lockfile provided by Pants, so long as you have not changed the `--version` option. See https://github.com/pantsbuild/pants/blob/release_2.23.0.dev5/src/python/pants/backend/codegen/protobuf/java/grpc-java.default.lockfile.txt for the default lockfile contents. +Set to the string `` to use a lockfile provided by Pants, so long as you have not changed the `--version` option. See https://github.com/pantsbuild/pants/blob/release_2.23.0.dev6/src/python/pants/backend/codegen/protobuf/java/grpc-java.default.lockfile.txt for the default lockfile contents. To use a custom lockfile, set this option to a file path relative to the build root, then run `pants jvm-generate-lockfiles --resolve=protobuf-java-grpc`. diff --git a/docs/reference/subsystems/python-infer.mdx b/docs/reference/subsystems/python-infer.mdx index 096cb7b70..59a47976c 100644 --- a/docs/reference/subsystems/python-infer.mdx +++ b/docs/reference/subsystems/python-infer.mdx @@ -207,7 +207,9 @@ How to handle imports that don't have an inferrable owner. Usually when an import cannot be inferred, it represents an issue like Pants not being properly configured, e.g. targets not set up. Often, missing dependencies will result in confusing runtime errors like `ModuleNotFoundError`, so this option can be helpful to error more eagerly. -To ignore any false positives, either add `# pants: no-infer-dep` to the line of the import or put the import inside a `try: except ImportError:` block. +To ignore any false positives, +either add `# pants: no-infer-dep` to the line of the +import or put the import inside a `try: except ImportError:` block. diff --git a/docs/reference/subsystems/scala-parser.mdx b/docs/reference/subsystems/scala-parser.mdx new file mode 100644 index 000000000..219a742ab --- /dev/null +++ b/docs/reference/subsystems/scala-parser.mdx @@ -0,0 +1,104 @@ +--- +title: scala-parser +description: | + Internal tool for parsing Scala sources to identify dependencies +--- + +import Option from "@site/src/components/reference/Option"; +import styles from "@site/src/components/reference/styles.module.css"; + +--- + +Internal tool for parsing Scala sources to identify dependencies + +Backend: `pants.backend.experimental.scala` + +Config section: `[scala-parser]` + + + +## Basic options + +None + +## Advanced options + +### `artifacts` + + + +### `jvm_options` + + + +### `lockfile` + + + +### `version` + + + +## Deprecated options + +None + +## Related subsystems + +None + + diff --git a/docs/reference/subsystems/scalafix.mdx b/docs/reference/subsystems/scalafix.mdx index 1178ce578..7c1554b1d 100644 --- a/docs/reference/subsystems/scalafix.mdx +++ b/docs/reference/subsystems/scalafix.mdx @@ -99,7 +99,7 @@ lockfile = `} Path to a lockfile used for installing the tool. -Set to the string `` to use a lockfile provided by Pants, so long as you have not changed the `--version` option. See https://github.com/pantsbuild/pants/blob/release_2.23.0.dev5/src/python/pants/backend/scala/lint/scalafix/scalafix.default.lockfile.txt for the default lockfile contents. +Set to the string `` to use a lockfile provided by Pants, so long as you have not changed the `--version` option. See https://github.com/pantsbuild/pants/blob/release_2.23.0.dev6/src/python/pants/backend/scala/lint/scalafix/scalafix.default.lockfile.txt for the default lockfile contents. To use a custom lockfile, set this option to a file path relative to the build root, then run `pants jvm-generate-lockfiles --resolve=scalafix`. diff --git a/docs/reference/subsystems/scalafmt.mdx b/docs/reference/subsystems/scalafmt.mdx index 00986d5ee..98722595c 100644 --- a/docs/reference/subsystems/scalafmt.mdx +++ b/docs/reference/subsystems/scalafmt.mdx @@ -99,7 +99,7 @@ lockfile = `} Path to a lockfile used for installing the tool. -Set to the string `` to use a lockfile provided by Pants, so long as you have not changed the `--version` option. See https://github.com/pantsbuild/pants/blob/release_2.23.0.dev5/src/python/pants/backend/scala/lint/scalafmt/scalafmt.default.lockfile.txt for the default lockfile contents. +Set to the string `` to use a lockfile provided by Pants, so long as you have not changed the `--version` option. See https://github.com/pantsbuild/pants/blob/release_2.23.0.dev6/src/python/pants/backend/scala/lint/scalafmt/scalafmt.default.lockfile.txt for the default lockfile contents. To use a custom lockfile, set this option to a file path relative to the build root, then run `pants jvm-generate-lockfiles --resolve=scalafmt`. diff --git a/docs/reference/subsystems/scalapb.mdx b/docs/reference/subsystems/scalapb.mdx index 5e95b9e67..eadf09987 100644 --- a/docs/reference/subsystems/scalapb.mdx +++ b/docs/reference/subsystems/scalapb.mdx @@ -91,7 +91,7 @@ lockfile = `} Path to a lockfile used for installing the tool. -Set to the string `` to use a lockfile provided by Pants, so long as you have not changed the `--version` option. See https://github.com/pantsbuild/pants/blob/release_2.23.0.dev5/src/python/pants/backend/codegen/protobuf/scala/scalapbc.default.lockfile.txt for the default lockfile contents. +Set to the string `` to use a lockfile provided by Pants, so long as you have not changed the `--version` option. See https://github.com/pantsbuild/pants/blob/release_2.23.0.dev6/src/python/pants/backend/codegen/protobuf/scala/scalapbc.default.lockfile.txt for the default lockfile contents. To use a custom lockfile, set this option to a file path relative to the build root, then run `pants jvm-generate-lockfiles --resolve=scalapb`. diff --git a/docs/reference/subsystems/scalatest.mdx b/docs/reference/subsystems/scalatest.mdx index b9eb1f51d..44bbadd2e 100644 --- a/docs/reference/subsystems/scalatest.mdx +++ b/docs/reference/subsystems/scalatest.mdx @@ -105,7 +105,7 @@ lockfile = `} Path to a lockfile used for installing the tool. -Set to the string `` to use a lockfile provided by Pants, so long as you have not changed the `--version` option. See https://github.com/pantsbuild/pants/blob/release_2.23.0.dev5/src/python/pants/backend/scala/subsystems/scalatest.default.lockfile.txt for the default lockfile contents. +Set to the string `` to use a lockfile provided by Pants, so long as you have not changed the `--version` option. See https://github.com/pantsbuild/pants/blob/release_2.23.0.dev6/src/python/pants/backend/scala/subsystems/scalatest.default.lockfile.txt for the default lockfile contents. To use a custom lockfile, set this option to a file path relative to the build root, then run `pants jvm-generate-lockfiles --resolve=scalatest`. diff --git a/docs/reference/subsystems/scrooge.mdx b/docs/reference/subsystems/scrooge.mdx index 7f2b1caf5..34ff8aced 100644 --- a/docs/reference/subsystems/scrooge.mdx +++ b/docs/reference/subsystems/scrooge.mdx @@ -73,7 +73,7 @@ lockfile = `} Path to a lockfile used for installing the tool. -Set to the string `` to use a lockfile provided by Pants, so long as you have not changed the `--version` option. See https://github.com/pantsbuild/pants/blob/release_2.23.0.dev5/src/python/pants/backend/codegen/thrift/scrooge/scrooge.default.lockfile.txt for the default lockfile contents. +Set to the string `` to use a lockfile provided by Pants, so long as you have not changed the `--version` option. See https://github.com/pantsbuild/pants/blob/release_2.23.0.dev6/src/python/pants/backend/codegen/thrift/scrooge/scrooge.default.lockfile.txt for the default lockfile contents. To use a custom lockfile, set this option to a file path relative to the build root, then run `pants jvm-generate-lockfiles --resolve=scrooge`. diff --git a/docs/reference/subsystems/strip-jar.mdx b/docs/reference/subsystems/strip-jar.mdx new file mode 100644 index 000000000..998bf4a63 --- /dev/null +++ b/docs/reference/subsystems/strip-jar.mdx @@ -0,0 +1,104 @@ +--- +title: strip-jar +description: | + Reproducible Build Maven Plugin +--- + +import Option from "@site/src/components/reference/Option"; +import styles from "@site/src/components/reference/styles.module.css"; + +--- + +Reproducible Build Maven Plugin + +Backend: `pants.backend.experimental.scala` + +Config section: `[strip-jar]` + + + +## Basic options + +None + +## Advanced options + +### `artifacts` + + + +### `jvm_options` + + + +### `lockfile` + + + +### `version` + + + +## Deprecated options + +None + +## Related subsystems + +None + + diff --git a/docs/reference/targets/java_source.mdx b/docs/reference/targets/java_source.mdx index 5684f617e..48a550acd 100644 --- a/docs/reference/targets/java_source.mdx +++ b/docs/reference/targets/java_source.mdx @@ -11,7 +11,7 @@ import styles from "@site/src/components/reference/styles.module.css"; A single Java source file containing application or library code. -Backend: `pants.backend.experimental.java` +Backend: `pants.backend.experimental.java.bsp` --- diff --git a/docs/reference/targets/java_sources.mdx b/docs/reference/targets/java_sources.mdx index d898b14d5..9c6152f2d 100644 --- a/docs/reference/targets/java_sources.mdx +++ b/docs/reference/targets/java_sources.mdx @@ -11,7 +11,7 @@ import styles from "@site/src/components/reference/styles.module.css"; Generate a `java_source` target for each file in the `sources` field. -Backend: `pants.backend.experimental.java` +Backend: `pants.backend.experimental.java.bsp` --- diff --git a/docs/reference/targets/jsx_source.mdx b/docs/reference/targets/jsx_source.mdx new file mode 100644 index 000000000..c843c1ced --- /dev/null +++ b/docs/reference/targets/jsx_source.mdx @@ -0,0 +1,77 @@ +--- +title: jsx_source +description: | + A single JSX source file. +--- + +import Field from "@site/src/components/reference/Field"; +import styles from "@site/src/components/reference/styles.module.css"; + +--- + +A single JSX source file. + +Backend: `pants.backend.experimental.javascript` + +--- + + + +## `source` + + + +A single file that belongs to this target. + +Path is relative to the BUILD file's directory, e.g. `source='example.ext'`. + + + +## `dependencies` + + + +Addresses to other targets that this target depends on, e.g. `['helloworld/subdir:lib', 'helloworld/main.py:lib', '3rdparty:reqs#django']`. + +This augments any dependencies inferred by Pants, such as by analyzing your imports. Use `pants dependencies` or `pants peek` on this target to get the final result. + +See https://www.pantsbuild.org/2.23/docs/using-pants/key-concepts/targets-and-build-files for more about how addresses are formed, including for generated targets. You can also run `pants list ::` to find all addresses in your project, or `pants list dir` to find all addresses defined in that directory. + +If the target is in the same BUILD file, you can leave off the BUILD file path, e.g. `:tgt` instead of `helloworld/subdir:tgt`. For generated first-party addresses, use `./` for the file path, e.g. `./main.py:tgt`; for all other generated targets, use `:tgt#generated_name`. + +You may exclude dependencies by prefixing with `!`, e.g. `['!helloworld/subdir:lib', '!./sibling.txt']`. Ignores are intended for false positives with dependency inference; otherwise, simply leave off the dependency from the BUILD file. + + + +## `description` + + + +A human-readable description of the target. + +Use `pants list --documented ::` to see all targets with descriptions. + + + +## `tags` + + + +Arbitrary strings to describe a target. + +For example, you may tag some test targets with 'integration_test' so that you could run `pants --tag='integration_test' test ::` to only run on targets with that tag. + + + + diff --git a/docs/reference/targets/jsx_sources.mdx b/docs/reference/targets/jsx_sources.mdx new file mode 100644 index 000000000..10b1159cd --- /dev/null +++ b/docs/reference/targets/jsx_sources.mdx @@ -0,0 +1,109 @@ +--- +title: jsx_sources +description: | + Generate a `jsx_source` target for each file in the `sources` field. +--- + +import Field from "@site/src/components/reference/Field"; +import styles from "@site/src/components/reference/styles.module.css"; + +--- + +Generate a `jsx_source` target for each file in the `sources` field. + +Backend: `pants.backend.experimental.javascript` + +--- + + + +## `dependencies` + + + +Addresses to other targets that this target depends on, e.g. `['helloworld/subdir:lib', 'helloworld/main.py:lib', '3rdparty:reqs#django']`. + +This augments any dependencies inferred by Pants, such as by analyzing your imports. Use `pants dependencies` or `pants peek` on this target to get the final result. + +See https://www.pantsbuild.org/2.23/docs/using-pants/key-concepts/targets-and-build-files for more about how addresses are formed, including for generated targets. You can also run `pants list ::` to find all addresses in your project, or `pants list dir` to find all addresses defined in that directory. + +If the target is in the same BUILD file, you can leave off the BUILD file path, e.g. `:tgt` instead of `helloworld/subdir:tgt`. For generated first-party addresses, use `./` for the file path, e.g. `./main.py:tgt`; for all other generated targets, use `:tgt#generated_name`. + +You may exclude dependencies by prefixing with `!`, e.g. `['!helloworld/subdir:lib', '!./sibling.txt']`. Ignores are intended for false positives with dependency inference; otherwise, simply leave off the dependency from the BUILD file. + + + +## `description` + + + +A human-readable description of the target. + +Use `pants list --documented ::` to see all targets with descriptions. + + + +## `overrides` + + + +Override the field values for generated `jsx_source` targets. + +Expects a dictionary of relative file paths and globs to a dictionary for the overrides. You may either use a string for a single path / glob, or a string tuple for multiple paths / globs. Each override is a dictionary of field names to the overridden value. + +For example: + +``` +overrides={ + "foo.jsx": {"skip_prettier": True}, + "bar.jsx": {"skip_prettier": True}, + ("foo.jsx", "bar.jsx"): {"tags": ["no_lint"]}, +} +``` + +File paths and globs are relative to the BUILD file's directory. Every overridden file is validated to belong to this target's `sources` field. + +If you'd like to override a field's value for every `jsx_source` target generated by this target, change the field directly on this target rather than using the `overrides` field. + +You can specify the same file name in multiple keys, so long as you don't override the same field more than one time for the file. + + + +## `sources` + + + +A list of files and globs that belong to this target. + +Paths are relative to the BUILD file's directory. You can ignore files/globs by prefixing them with `!`. + +Example: `sources=['utils.jsx', 'subdir/*.jsx', '!ignore_me.jsx']` + + + +## `tags` + + + +Arbitrary strings to describe a target. + +For example, you may tag some test targets with 'integration_test' so that you could run `pants --tag='integration_test' test ::` to only run on targets with that tag. + + + + diff --git a/docs/reference/targets/jsx_test.mdx b/docs/reference/targets/jsx_test.mdx new file mode 100644 index 000000000..a01d20e74 --- /dev/null +++ b/docs/reference/targets/jsx_test.mdx @@ -0,0 +1,129 @@ +--- +title: jsx_test +description: | + A single JSX test file. +--- + +import Field from "@site/src/components/reference/Field"; +import styles from "@site/src/components/reference/styles.module.css"; + +--- + +A single JSX test file. + +Backend: `pants.backend.experimental.javascript` + +--- + + + +## `source` + + + +A single file that belongs to this target. + +Path is relative to the BUILD file's directory, e.g. `source='example.ext'`. + + + +## `batch_compatibility_tag` + + + +An arbitrary value used to mark the test files belonging to this target as valid for batched execution. + +It's _sometimes_ safe to run multiple `jsx_test`s within a single test runner process, and doing so can give significant wins by allowing reuse of expensive test setup / teardown logic. To opt into this behavior, set this field to an arbitrary non-empty string on all the `jsx_test` targets that are safe/compatible to run in the same process. + +If this field is left unset on a target, the target is assumed to be incompatible with all others and will run in a dedicated `nodejs test runner` process. + +If this field is set on a target, and its value is different from the value on some other test `jsx_test`, then the two targets are explicitly incompatible and are guaranteed to not run in the same `nodejs test runner` process. + +If this field is set on a target, and its value is the same as the value on some other `jsx_test`, then the two targets are explicitly compatible and _may_ run in the same test runner process. Compatible tests may not end up in the same test runner batch if: + +- There are "too many" compatible tests in a partition, as determined by the `[test].batch_size` config parameter, or +- Compatible tests have some incompatibility in Pants metadata (i.e. different `resolve`s or `extra_env_vars`). + +When tests with the same `batch_compatibility_tag` have incompatibilities in some other Pants metadata, they will be automatically split into separate batches. This way you can set a high-level `batch_compatibility_tag` using `__defaults__` and then have tests continue to work as you tweak BUILD metadata on specific targets. + + + +## `dependencies` + + + +Addresses to other targets that this target depends on, e.g. `['helloworld/subdir:lib', 'helloworld/main.py:lib', '3rdparty:reqs#django']`. + +This augments any dependencies inferred by Pants, such as by analyzing your imports. Use `pants dependencies` or `pants peek` on this target to get the final result. + +See https://www.pantsbuild.org/2.23/docs/using-pants/key-concepts/targets-and-build-files for more about how addresses are formed, including for generated targets. You can also run `pants list ::` to find all addresses in your project, or `pants list dir` to find all addresses defined in that directory. + +If the target is in the same BUILD file, you can leave off the BUILD file path, e.g. `:tgt` instead of `helloworld/subdir:tgt`. For generated first-party addresses, use `./` for the file path, e.g. `./main.py:tgt`; for all other generated targets, use `:tgt#generated_name`. + +You may exclude dependencies by prefixing with `!`, e.g. `['!helloworld/subdir:lib', '!./sibling.txt']`. Ignores are intended for false positives with dependency inference; otherwise, simply leave off the dependency from the BUILD file. + + + +## `description` + + + +A human-readable description of the target. + +Use `pants list --documented ::` to see all targets with descriptions. + + + +## `extra_env_vars` + + + +Additional environment variables to include in test processes. + +Entries are strings in the form `ENV_VAR=value` to use explicitly; or just `ENV_VAR` to copy the value of a variable in Pants's own environment. + +This will be merged with and override values from `[test].extra_env_vars`. + + + +## `tags` + + + +Arbitrary strings to describe a target. + +For example, you may tag some test targets with 'integration_test' so that you could run `pants --tag='integration_test' test ::` to only run on targets with that tag. + + + +## `timeout` + + + +A timeout (in seconds) used by each test file belonging to this target. + +If unset, will default to `[test].timeout_default`; if that option is also unset, then the test will never time out. Will never exceed `[test].timeout_maximum`. Only applies if the option `--test-timeouts` is set to true (the default). + + + + diff --git a/docs/reference/targets/jsx_tests.mdx b/docs/reference/targets/jsx_tests.mdx new file mode 100644 index 000000000..c29fe2eba --- /dev/null +++ b/docs/reference/targets/jsx_tests.mdx @@ -0,0 +1,161 @@ +--- +title: jsx_tests +description: | + Generate a `jsx_test` target for each file in the `sources` field. +--- + +import Field from "@site/src/components/reference/Field"; +import styles from "@site/src/components/reference/styles.module.css"; + +--- + +Generate a `jsx_test` target for each file in the `sources` field. + +Backend: `pants.backend.experimental.javascript` + +--- + + + +## `batch_compatibility_tag` + + + +An arbitrary value used to mark the test files belonging to this target as valid for batched execution. + +It's _sometimes_ safe to run multiple `jsx_test`s within a single test runner process, and doing so can give significant wins by allowing reuse of expensive test setup / teardown logic. To opt into this behavior, set this field to an arbitrary non-empty string on all the `jsx_test` targets that are safe/compatible to run in the same process. + +If this field is left unset on a target, the target is assumed to be incompatible with all others and will run in a dedicated `nodejs test runner` process. + +If this field is set on a target, and its value is different from the value on some other test `jsx_test`, then the two targets are explicitly incompatible and are guaranteed to not run in the same `nodejs test runner` process. + +If this field is set on a target, and its value is the same as the value on some other `jsx_test`, then the two targets are explicitly compatible and _may_ run in the same test runner process. Compatible tests may not end up in the same test runner batch if: + +- There are "too many" compatible tests in a partition, as determined by the `[test].batch_size` config parameter, or +- Compatible tests have some incompatibility in Pants metadata (i.e. different `resolve`s or `extra_env_vars`). + +When tests with the same `batch_compatibility_tag` have incompatibilities in some other Pants metadata, they will be automatically split into separate batches. This way you can set a high-level `batch_compatibility_tag` using `__defaults__` and then have tests continue to work as you tweak BUILD metadata on specific targets. + + + +## `dependencies` + + + +Addresses to other targets that this target depends on, e.g. `['helloworld/subdir:lib', 'helloworld/main.py:lib', '3rdparty:reqs#django']`. + +This augments any dependencies inferred by Pants, such as by analyzing your imports. Use `pants dependencies` or `pants peek` on this target to get the final result. + +See https://www.pantsbuild.org/2.23/docs/using-pants/key-concepts/targets-and-build-files for more about how addresses are formed, including for generated targets. You can also run `pants list ::` to find all addresses in your project, or `pants list dir` to find all addresses defined in that directory. + +If the target is in the same BUILD file, you can leave off the BUILD file path, e.g. `:tgt` instead of `helloworld/subdir:tgt`. For generated first-party addresses, use `./` for the file path, e.g. `./main.py:tgt`; for all other generated targets, use `:tgt#generated_name`. + +You may exclude dependencies by prefixing with `!`, e.g. `['!helloworld/subdir:lib', '!./sibling.txt']`. Ignores are intended for false positives with dependency inference; otherwise, simply leave off the dependency from the BUILD file. + + + +## `description` + + + +A human-readable description of the target. + +Use `pants list --documented ::` to see all targets with descriptions. + + + +## `extra_env_vars` + + + +Additional environment variables to include in test processes. + +Entries are strings in the form `ENV_VAR=value` to use explicitly; or just `ENV_VAR` to copy the value of a variable in Pants's own environment. + +This will be merged with and override values from `[test].extra_env_vars`. + + + +## `overrides` + + + +Override the field values for generated `jsx_test` targets. + +Expects a dictionary of relative file paths and globs to a dictionary for the overrides. You may either use a string for a single path / glob, or a string tuple for multiple paths / globs. Each override is a dictionary of field names to the overridden value. + +For example: + +``` +overrides={ + "foo.test.jsx": {"timeout": 120}, + "bar.test.jsx": {"timeout": 200}, + ("foo.test.jsx", "bar.test.jsx"): {"tags": ["slow_tests"]}, +} +``` + +File paths and globs are relative to the BUILD file's directory. Every overridden file is validated to belong to this target's `sources` field. + +If you'd like to override a field's value for every `jsx_test` target generated by this target, change the field directly on this target rather than using the `overrides` field. + +You can specify the same file name in multiple keys, so long as you don't override the same field more than one time for the file. + + + +## `sources` + + + +A list of files and globs that belong to this target. + +Paths are relative to the BUILD file's directory. You can ignore files/globs by prefixing them with `!`. + +Example: `sources=['utils.test.jsx', 'subdir/*.test.jsx', '!ignore_me.test.jsx']` + + + +## `tags` + + + +Arbitrary strings to describe a target. + +For example, you may tag some test targets with 'integration_test' so that you could run `pants --tag='integration_test' test ::` to only run on targets with that tag. + + + +## `timeout` + + + +A timeout (in seconds) used by each test file belonging to this target. + +If unset, will default to `[test].timeout_default`; if that option is also unset, then the test will never time out. Will never exceed `[test].timeout_maximum`. Only applies if the option `--test-timeouts` is set to true (the default). + + + + diff --git a/docs/reference/targets/junit_test.mdx b/docs/reference/targets/junit_test.mdx index ee0a12eab..8bde9b04c 100644 --- a/docs/reference/targets/junit_test.mdx +++ b/docs/reference/targets/junit_test.mdx @@ -11,7 +11,7 @@ import styles from "@site/src/components/reference/styles.module.css"; A single Java test, run with JUnit. -Backend: `pants.backend.experimental.java` +Backend: `pants.backend.experimental.java.bsp` --- diff --git a/docs/reference/targets/junit_tests.mdx b/docs/reference/targets/junit_tests.mdx index 3c7c122dc..b43d5d3f8 100644 --- a/docs/reference/targets/junit_tests.mdx +++ b/docs/reference/targets/junit_tests.mdx @@ -11,7 +11,7 @@ import styles from "@site/src/components/reference/styles.module.css"; Generate a `junit_test` target for each file in the `sources` field. -Backend: `pants.backend.experimental.java` +Backend: `pants.backend.experimental.java.bsp` --- diff --git a/docs/reference/targets/jvm_artifact.mdx b/docs/reference/targets/jvm_artifact.mdx index 64ba74c4f..6dc7c67e9 100644 --- a/docs/reference/targets/jvm_artifact.mdx +++ b/docs/reference/targets/jvm_artifact.mdx @@ -148,7 +148,7 @@ The JVM packages this artifact provides for the purposes of dependency inference For example, the JVM artifact `junit:junit` might provide `["org.junit.**"]`. -Usually you can leave this field off. If unspecified, Pants will fall back to the `[java-infer].third_party_import_mapping`, then to a built in mapping (https://github.com/pantsbuild/pants/blob/release_2.23.0.dev5/src/python/pants/jvm/dependency_inference/jvm_artifact_mappings.py), and then finally it will default to the normalized `group` of the artifact. For example, in the absence of any other mapping the artifact `io.confluent:common-config` would default to providing `["io.confluent.**"]`. +Usually you can leave this field off. If unspecified, Pants will fall back to the `[java-infer].third_party_import_mapping`, then to a built in mapping (https://github.com/pantsbuild/pants/blob/release_2.23.0.dev6/src/python/pants/jvm/dependency_inference/jvm_artifact_mappings.py), and then finally it will default to the normalized `group` of the artifact. For example, in the absence of any other mapping the artifact `io.confluent:common-config` would default to providing `["io.confluent.**"]`. The package path may be made recursive to match symbols in subpackages by adding `.**` to the end of the package path. For example, specify `["org.junit.**"]` to infer a dependency on the artifact for any file importing a symbol from `org.junit` or its subpackages. diff --git a/docs/reference/targets/pants_requirements.mdx b/docs/reference/targets/pants_requirements.mdx index 1b3bb8c75..6b580dca8 100644 --- a/docs/reference/targets/pants_requirements.mdx +++ b/docs/reference/targets/pants_requirements.mdx @@ -79,7 +79,7 @@ If true, include `pantsbuild.pants.testutil` to write tests for your plugin. The PEP 440 version specifier version of Pants to target. E.g. `== 2.15.*`, or `>= 2.16.0, < 2.17.0` diff --git a/docs/reference/targets/python_aws_lambda_function.mdx b/docs/reference/targets/python_aws_lambda_function.mdx index f1e06eb28..012520682 100644 --- a/docs/reference/targets/python_aws_lambda_function.mdx +++ b/docs/reference/targets/python_aws_lambda_function.mdx @@ -33,6 +33,17 @@ This is re-exported at `lambda_function.handler` in the resulting package to be +## `architecture` + + + +The architecture of the AWS Lambda runtime to target (x86_64 or arm64). See https://docs.aws.amazon.com/lambda/latest/dg/lambda-runtimes.html. + + + ## `complete_platforms` +## `architecture` + + + +The architecture of the AWS Lambda runtime to target (x86_64 or arm64). See https://docs.aws.amazon.com/lambda/latest/dg/lambda-runtimes.html. + + + ## `complete_platforms` `pants.backend.experimental.scala` +Backend: `pants.backend.experimental.scala.bsp` --- @@ -151,7 +151,7 @@ The JVM packages this artifact provides for the purposes of dependency inference For example, the JVM artifact `junit:junit` might provide `["org.junit.**"]`. -Usually you can leave this field off. If unspecified, Pants will fall back to the `[java-infer].third_party_import_mapping`, then to a built in mapping (https://github.com/pantsbuild/pants/blob/release_2.23.0.dev5/src/python/pants/jvm/dependency_inference/jvm_artifact_mappings.py), and then finally it will default to the normalized `group` of the artifact. For example, in the absence of any other mapping the artifact `io.confluent:common-config` would default to providing `["io.confluent.**"]`. +Usually you can leave this field off. If unspecified, Pants will fall back to the `[java-infer].third_party_import_mapping`, then to a built in mapping (https://github.com/pantsbuild/pants/blob/release_2.23.0.dev6/src/python/pants/jvm/dependency_inference/jvm_artifact_mappings.py), and then finally it will default to the normalized `group` of the artifact. For example, in the absence of any other mapping the artifact `io.confluent:common-config` would default to providing `["io.confluent.**"]`. The package path may be made recursive to match symbols in subpackages by adding `.**` to the end of the package path. For example, specify `["org.junit.**"]` to infer a dependency on the artifact for any file importing a symbol from `org.junit` or its subpackages. diff --git a/docs/reference/targets/scala_junit_test.mdx b/docs/reference/targets/scala_junit_test.mdx index 8fb7802f5..a3fa393ec 100644 --- a/docs/reference/targets/scala_junit_test.mdx +++ b/docs/reference/targets/scala_junit_test.mdx @@ -11,7 +11,7 @@ import styles from "@site/src/components/reference/styles.module.css"; A single Scala test, run with JUnit. -Backend: `pants.backend.experimental.scala` +Backend: `pants.backend.experimental.scala.bsp` --- diff --git a/docs/reference/targets/scala_junit_tests.mdx b/docs/reference/targets/scala_junit_tests.mdx index b2df87d22..63586fb6f 100644 --- a/docs/reference/targets/scala_junit_tests.mdx +++ b/docs/reference/targets/scala_junit_tests.mdx @@ -11,7 +11,7 @@ import styles from "@site/src/components/reference/styles.module.css"; Generate a `scala_junit_test` target for each file in the `sources` field. -Backend: `pants.backend.experimental.scala` +Backend: `pants.backend.experimental.scala.bsp` --- diff --git a/docs/reference/targets/scala_source.mdx b/docs/reference/targets/scala_source.mdx index 397b95975..09bf575ae 100644 --- a/docs/reference/targets/scala_source.mdx +++ b/docs/reference/targets/scala_source.mdx @@ -11,7 +11,7 @@ import styles from "@site/src/components/reference/styles.module.css"; A single Scala source file containing application or library code. -Backend: `pants.backend.experimental.scala` +Backend: `pants.backend.experimental.scala.bsp` --- diff --git a/docs/reference/targets/scala_sources.mdx b/docs/reference/targets/scala_sources.mdx index 3320a441f..d7d978fa4 100644 --- a/docs/reference/targets/scala_sources.mdx +++ b/docs/reference/targets/scala_sources.mdx @@ -11,7 +11,7 @@ import styles from "@site/src/components/reference/styles.module.css"; Generate a `scala_source` target for each file in the `sources` field. -Backend: `pants.backend.experimental.scala` +Backend: `pants.backend.experimental.scala.bsp` --- diff --git a/docs/reference/targets/scalac_plugin.mdx b/docs/reference/targets/scalac_plugin.mdx index 4562c41b5..99b8c8ab7 100644 --- a/docs/reference/targets/scalac_plugin.mdx +++ b/docs/reference/targets/scalac_plugin.mdx @@ -15,7 +15,7 @@ Currently only thirdparty plugins are supported. To enable a plugin, define this If the `scalac`-loaded name of the plugin does not match the target's name, additionally set the `plugin_name=` field. -Backend: `pants.backend.experimental.scala` +Backend: `pants.backend.experimental.scala.bsp` --- diff --git a/docs/reference/targets/scalatest_test.mdx b/docs/reference/targets/scalatest_test.mdx index d165e6cbb..096011280 100644 --- a/docs/reference/targets/scalatest_test.mdx +++ b/docs/reference/targets/scalatest_test.mdx @@ -11,7 +11,7 @@ import styles from "@site/src/components/reference/styles.module.css"; A single Scala test, run with Scalatest. -Backend: `pants.backend.experimental.scala` +Backend: `pants.backend.experimental.scala.bsp` --- diff --git a/docs/reference/targets/scalatest_tests.mdx b/docs/reference/targets/scalatest_tests.mdx index fb5d005a3..35650200d 100644 --- a/docs/reference/targets/scalatest_tests.mdx +++ b/docs/reference/targets/scalatest_tests.mdx @@ -11,7 +11,7 @@ import styles from "@site/src/components/reference/styles.module.css"; Generate a `scalatest_test` target for each file in the `sources` field (defaults to all files in the directory matching `('*Spec.scala', '*Suite.scala')`). -Backend: `pants.backend.experimental.scala` +Backend: `pants.backend.experimental.scala.bsp` ---