Package org.gradle.plugin.use

## Interface PluginDependenciesSpec

-     public interface PluginDependenciesSpec

  The DSL for declaring plugins to use in a script.

  In a build script, the `plugins {}` script block API is of this type. That is, you can use this API in the body of the plugins script block to declare plugins to be used for the script.

  ### Relationship with the apply() method

  The `plugins {}` block serves a similar purpose to the `PluginAware.apply(java.util.Map)` method that can be used to apply a plugin directly to a `Project` object or similar. A key difference is that plugins applied via the `plugins {}` block are conceptually applied to the script, and by extension the script target. At this time there is no observable practical difference between the two approaches with regard to the end result.

  ### Strict Syntax

  When used in a build script, the `plugins {}` block only allows a strict subset of the full build script programming language. Only the API of this type can be used, and values must be literal (e.g. constant strings, not variables). Interpolated strings are permitted for `PluginDependencySpec.version(String)`, however replacement values must be sourced from Gradle properties. Moreover, the `plugins {}` block must be the first code of a build script. There is one exception to this, in that the `buildscript {}` block (used for declaring script dependencies) must precede it.

  This implies the following constraints:

  - Only `id(String)`, `alias(Provider)`, and `alias(ProviderConvertible)` method calls may be top level statements
  - `id(String)` calls may only be followed by a `PluginDependencySpec.version(String)` and/or `PluginDependencySpec.apply(boolean)` method call on the returned object
  - `id(String)`, `PluginDependencySpec.version(String)` and `PluginDependencySpec.apply(boolean)` methods must be called with a literal argument (i.e. not a variable)
  - The `plugins {}` script block must follow any `buildscript {}` script block, but must precede all other logic in the script

  ### Available Plugins

  #### Core Plugins

  Core Gradle plugins are able to be applied using the `plugins {}` block. Core plugins must be specified without a version number, and can have a qualified or unqualified id. That is, the `java` plugin can be used via:

       plugins {
         id 'java'
       }

  Or via:

       plugins {
         id 'org.gradle.java'
       }

  Core Gradle plugins use the `org.gradle` namespace.

  For the list of available core plugins for a particular Gradle version, please consult the user manual.

  #### Community Plugins

  Non-core plugins are available from the Gradle Plugin Portal. These plugins are contributed by users of Gradle to extend Gradle's functionality. Visit plugins.gradle.org to browse the available plugins and versions.

  To use a community plugin, the fully qualified id must be specified along with a version.

  ### Settings Script Usage

  When used in a settings script, this API sets the default version of a plugin, allowing build scripts to reference a plugin id without an associated version.

  Within a settings script, the "Strict Syntax" rules outlined above do not apply. The `plugins` block may contain arbitrary code, and version Strings may contain property replacements. It is an error to call the `apply` method with a value other than `false` (the default).

- - ### Method Summary

    All Methods Instance Methods Abstract Methods Default Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `default PluginDependencySpec` | `alias​(Provider<PluginDependency> notation)` | Adds a plugin dependency using a notation coming from a version catalog.
    `default PluginDependencySpec` | `alias​(ProviderConvertible<PluginDependency> notation)` | Adds a plugin dependency using a notation coming from a version catalog.
    `PluginDependencySpec` | `id​(java.lang.String id)` | Add a dependency on the plugin with the given id.

- - ### Method Detail

    - #### id

          PluginDependencySpec id​(java.lang.String id)

      Add a dependency on the plugin with the given id.

           plugins {
               id "org.company.myplugin"
           }

      Further constraints (e.g. version number) can be specified by the methods of the return value.

           plugins {
               id "org.company.myplugin" version "1.3"
           }

      Plugins are automatically applied to the current script by default. This can be disabled using the `apply false` option:

           plugins {
               id "org.company.myplugin" version "1.3" apply false
           }

      This is useful to reuse task classes from a plugin or to apply it to some other target than the current script.
      Parameters:
        `id` - the id of the plugin to depend on
      Returns:
        a mutable plugin dependency specification that can be used to further refine the dependency

    - #### alias

          default PluginDependencySpec alias​(Provider<PluginDependency> notation)

      Adds a plugin dependency using a notation coming from a version catalog. The resulting dependency spec can be refined with a version overriding what the version catalog provides.
      Parameters:
        `notation` - the plugin reference
      Returns:
        a mutable plugin dependency specification that can be used to further refine the dependency
      Since:
        7.2

    - #### alias

          default PluginDependencySpec alias​(ProviderConvertible<PluginDependency> notation)

      Adds a plugin dependency using a notation coming from a version catalog. The resulting dependency spec can be refined with a version overriding what the version catalog provides.
      Parameters:
        `notation` - the plugin reference
      Returns:
        a mutable plugin dependency specification that can be used to further refine the dependency
      Since:
        7.3