gradle-doc 2.10-1 / usr / share / doc / gradle / userguide / plugins.html

This file is indexed.

/usr/share/doc/gradle/userguide/plugins.html is in gradle-doc 2.10-1.

This file is owned by root:root, with mode 0o644.

The actual contents of the file can be viewed below. 

  1
  2
  3
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
<html><head><META http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>Chapter&nbsp;25.&nbsp;Gradle Plugins</title><link xmlns:xslthl="http://xslthl.sf.net" type="text/css" rel="stylesheet" href="base.css"><link xmlns:xslthl="http://xslthl.sf.net" type="text/css" rel="stylesheet" href="docs.css"><link xmlns:xslthl="http://xslthl.sf.net" type="text/css" rel="stylesheet" href="userguide.css"><meta content="DocBook XSL Stylesheets V1.79.1" name="generator"><link rel="home" href="userguide.html" title="Gradle User Guide"><link rel="up" href="pt03.html" title="Part&nbsp;III.&nbsp;Writing Gradle build scripts"><link rel="prev" href="multi_project_builds.html" title="Chapter&nbsp;24.&nbsp;Multi-project Builds"><link rel="next" href="standard_plugins.html" title="Chapter&nbsp;26.&nbsp;Standard Gradle plugins"></head><body><div class="navheader"><div><div class="navbar"><a xmlns:xslthl="http://xslthl.sf.net" href="multi_project_builds.html" title="Chapter&nbsp;24.&nbsp;Multi-project Builds">Previous</a><span>|</span><a xmlns:xslthl="http://xslthl.sf.net" href="userguide.html" title="Gradle User Guide">Contents</a><span>|</span><a xmlns:xslthl="http://xslthl.sf.net" href="standard_plugins.html" title="Chapter&nbsp;26.&nbsp;Standard Gradle plugins">Next</a></div></div></div><div class="chapter"><div class="titlepage"><div><div><h1 xmlns:xslthl="http://xslthl.sf.net"><a name="plugins"></a>Chapter&nbsp;25.&nbsp;Gradle Plugins</h1></div></div></div><p>
        Gradle at its core intentionally provides very little for real world automation. All of the useful
        features, like the ability to compile Java code, are added by <span class="emphasis"><em>plugins</em></span>.
        Plugins add new tasks (e.g. <a class="ulink" href="../dsl/org.gradle.api.tasks.compile.JavaCompile.html" target="_top"><code class="classname">JavaCompile</code></a>), domain objects (e.g.
        <a class="ulink" href="../dsl/org.gradle.api.tasks.SourceSet.html" target="_top"><code class="classname">SourceSet</code></a>), conventions (e.g. Java source is located at
        <code class="literal">src/main/java</code>) as well as extending core objects and objects from other plugins.
    </p><p>
        In this chapter we will discuss how to use plugins and the terminology and concepts surrounding plugins.
    </p><div class="section"><div class="titlepage"><div><div><h2 class="title"><a name="N12D5A"></a>25.1.&nbsp;What plugins do</h2></div></div></div><p>
            Applying a plugin to a project allows the plugin to extend the project's capabilities. It can do things
            such as:
        </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem">Extend the Gradle model (e.g. add new DSL elements that can be configured)</li><li class="listitem">Configure the project according to conventions (e.g. add new tasks or configure sensible defaults)</li><li class="listitem">Apply specific configuration (e.g. add organizational repositories or enforce standards)</li></ul></div><p>
            By applying plugins, rather than adding logic to the project build script, we can reap a number of benefits.  Applying plugins:
        </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem">Promotes reuse and reduces the overhead of maintaining similar logic across multiple projects</li><li class="listitem">Allows a higher degree of modularization, enhancing comprehensibility and organization</li><li class="listitem">Encapsulates imperative logic and allows build scripts to be as declarative as possible</li></ul></div></div><div class="section"><div class="titlepage"><div><div><h2 class="title"><a name="sec:types_of_plugins"></a>25.2.&nbsp;Types of plugins</h2></div></div></div><p>
            There are two general types of plugins in Gradle, <span class="emphasis"><em>script</em></span> plugins and <span class="emphasis"><em>binary</em></span> plugins.
            Script plugins are additional build scripts that further configure the build and usually implement a declarative approach to
            manipulating the build.  They are typically used within a build although they can be externalized and accessed from a remote
            location.  Binary plugins are classes that implement the <a class="ulink" href="../javadoc/org/gradle/api/Plugin.html" target="_top"><code class="classname">Plugin</code></a> interface and adopt a programmatic
            approach to manipulating the build.  Binary plugins can reside within a build script, within the project hierarchy or externally
            in a plugin jar.
        </p></div><div class="section"><div class="titlepage"><div><div><h2 class="title"><a name="sec:using_plugins"></a>25.3.&nbsp;Applying plugins</h2></div></div></div><p>
            Plugins are said to be <span class="emphasis"><em>applied</em></span>, which is done via the <a class="ulink" href="../dsl/org.gradle.api.Project.html#org.gradle.api.Project:apply(java.util.Map)" target="_top"><code class="classname">Project.apply()</code></a> method.
            The application of plugins is <span class="emphasis"><em>idempotent</em></span>. That is, the same plugin can be applied multiple times. If the plugin
            has previously been applied, any further applications are safe and will have no effect.
        </p><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="N12D91"></a>25.3.1.&nbsp;Script plugins</h3></div></div></div><div class="example"><a name="configureProjectUsingScript"></a><p class="title"><b>Example&nbsp;25.1.&nbsp;Applying a script plugin</b></p><div class="example-contents"><p><code class="filename">build.gradle</code></p><pre class="programlisting">apply from: <span xmlns:xslthl="http://xslthl.sf.net" class="hl-string">'other.gradle'</span>
</pre></div></div><br class="example-break"><p>
                Script plugins can be applied from a script on the local filesystem or at a remote location.  Filesystem
                locations are relative to the project directory, while remote script locations are specified with an HTTP URL.
                Multiple script plugins (of either form) can be applied to a given build.
            </p></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="sec:applying_binary_plugins"></a>25.3.2.&nbsp;Binary plugins</h3></div></div></div><div class="example"><a name="useJavaPlugin"></a><p class="title"><b>Example&nbsp;25.2.&nbsp;Applying a binary plugin</b></p><div class="example-contents"><p><code class="filename">build.gradle</code></p><pre class="programlisting">apply plugin: <span xmlns:xslthl="http://xslthl.sf.net" class="hl-string">'java'</span>
</pre></div></div><br class="example-break"><p>
                Plugins can be applied using a <span class="emphasis"><em>plugin id</em></span>.  The plugin id serves as a unique identifier
                for a given plugin.  Core plugins register a short name that can be used as the plugin id. In the above case, we are
                using the short name &lsquo;<code class="literal">java</code>&rsquo; to apply the <a class="ulink" href="../javadoc/org/gradle/api/plugins/JavaPlugin.html" target="_top"><code class="classname">JavaPlugin</code></a>.
                Community plugins, on the other hand, use a fully qualified form for the plugin id (e.g. <code class="literal">com.github.foo.bar</code>),
                although some legacy plugins may still utilize a short, unqualified form.
            </p><p>
                Rather than using a plugin id, plugins can also be applied by simply specifying the class of the plugin:
            </p><div class="example"><a name="pluginIntro"></a><p class="title"><b>Example&nbsp;25.3.&nbsp;Applying a binary plugin by type</b></p><div class="example-contents"><p><code class="filename">build.gradle</code></p><pre class="programlisting">apply plugin: JavaPlugin
</pre></div></div><br class="example-break"><p>
                The <code class="literal">JavaPlugin</code> symbol in the above sample refers to the the <a class="ulink" href="../javadoc/org/gradle/api/plugins/JavaPlugin.html" target="_top"><code class="classname">JavaPlugin</code></a>.
                This class does not strictly need to be imported as the <code class="literal">org.gradle.api.plugins</code> package is automatically imported in all build scripts
                (see <a class="xref" href="writing_build_scripts.html#script-default-imports">Section&nbsp;16.8, &ldquo;Default imports&rdquo;</a>). Furthermore, it is not necessary to append <code class="literal">.class</code> to identify a class literal in Groovy as it is in Java.
            </p><div class="section"><div class="titlepage"><div><div><h4 class="title"><a name="N12DDD"></a>25.3.2.1.&nbsp;Locations of binary plugins</h4></div></div></div><p>
                    A plugin is simply any class that implements the <a class="ulink" href="../javadoc/org/gradle/api/Plugin.html" target="_top"><code class="classname">Plugin</code></a> interface. Gradle provides
                    the core plugins as part of its distribution so simply applying the plugin as above is all you need to do.
                    However, non-core binary plugins need to be available to the build classpath before they can be applied.  This can
                    be achieved in a number of ways, including:
                </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem">Defining the plugin as an inline class declaration inside a build script.</li><li class="listitem">Defining the plugin as a source file under the buildSrc directory in the project (see <a class="xref" href="organizing_build_logic.html#sec:build_sources">Section&nbsp;41.4, &ldquo;Build sources in the <code class="filename">buildSrc</code> project&rdquo;</a>).</li><li class="listitem">Including the plugin from an external jar defined as a buildscript dependency (see <a class="xref" href="plugins.html#sec:applying_plugins_buildscript">Section&nbsp;25.4, &ldquo;Applying plugins with the buildscript block&rdquo;</a>).</li><li class="listitem">Including the plugin from the plugin portal using the plugins DSL (see <a class="xref" href="plugins.html#sec:plugins_block">Section&nbsp;25.5, &ldquo;Applying plugins with the plugins DSL&rdquo;</a>).</li></ul></div><p>
                    For more on defining your own plugins, see <a class="xref" href="custom_plugins.html">Chapter&nbsp;39, <i>Writing Custom Plugins</i></a>.
                </p></div></div></div><div class="section"><div class="titlepage"><div><div><h2 class="title"><a name="sec:applying_plugins_buildscript"></a>25.4.&nbsp;Applying plugins with the buildscript block</h2></div></div></div><p>
            Binary plugins that have been published as external jar files can be added to a project by adding the plugin to the
            build script classpath and then applying the plugin.  External jars can be added to the build script classpath
            using the <code class="code">buildscript {}</code> block as described in <a class="xref" href="organizing_build_logic.html#sec:external_dependencies">Section&nbsp;41.6, &ldquo;External dependencies for the build script&rdquo;</a>.
        </p><div class="example"><a name="applyPluginBuildscript"></a><p class="title"><b>Example&nbsp;25.4.&nbsp;Applying a plugin with the buildscript block</b></p><div class="example-contents"><p><code class="filename">build.gradle</code></p><pre class="programlisting">buildscript {
    repositories {
        jcenter()
    }
    dependencies {
        classpath <span xmlns:xslthl="http://xslthl.sf.net" class="hl-string">"com.jfrog.bintray.gradle:gradle-bintray-plugin:0.4.1"</span>
    }
}

apply plugin: <span xmlns:xslthl="http://xslthl.sf.net" class="hl-string">"com.jfrog.bintray"</span>
</pre></div></div><br class="example-break"></div><div class="section"><div class="titlepage"><div><div><h2 class="title"><a name="sec:plugins_block"></a>25.5.&nbsp;Applying plugins with the plugins DSL</h2></div></div></div><div class="note"><p>
                The plugins DSL is currently <a class="link" href="feature_lifecycle.html">incubating</a>.
                Please be aware that the DSL and other configuration may change in later Gradle versions.
            </p></div><p>
            The new plugins DSL provides a more succinct and convenient way to declare plugin dependencies.  It works with the
            new <a class="ulink" href="http://plugins.gradle.org" target="_top">Gradle plugin portal</a> to provide easy access to both core and community
            plugins.  The plugins script block configures an instance of <a class="ulink" href="../dsl/org.gradle.plugin.use.PluginDependenciesSpec.html" target="_top"><code class="classname">PluginDependenciesSpec</code></a>.
        </p><p>
            To apply a core plugin, the short name can be used:
        </p><div class="example"><a name="useJavaPluginDSL"></a><p class="title"><b>Example&nbsp;25.5.&nbsp;Applying a core plugin</b></p><div class="example-contents"><p><code class="filename">build.gradle</code></p><pre class="programlisting">plugins {
    id <span xmlns:xslthl="http://xslthl.sf.net" class="hl-string">'java'</span>
}
</pre></div></div><br class="example-break"><p>
            To apply a community plugin from the portal, the fully qualified plugin id must be used:
        </p><div class="example"><a name="useCommunityPluginDSL"></a><p class="title"><b>Example&nbsp;25.6.&nbsp;Applying a community plugin</b></p><div class="example-contents"><p><code class="filename">build.gradle</code></p><pre class="programlisting">plugins {
    id <span xmlns:xslthl="http://xslthl.sf.net" class="hl-string">"com.jfrog.bintray"</span> version <span xmlns:xslthl="http://xslthl.sf.net" class="hl-string">"0.4.1"</span>
}
</pre></div></div><br class="example-break"><p>
            No further configuration is necessary.  Specifically, there is no need to configure the buildscript classpath.
            Gradle will resolve the plugin in the plugin portal, locate it, and make it available to the build.
        </p><p>
            See <a class="ulink" href="../dsl/org.gradle.plugin.use.PluginDependenciesSpec.html" target="_top"><code class="classname">PluginDependenciesSpec</code></a> for more information on using the Plugin DSL.
        </p><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="plugins_dsl_limitations"></a>25.5.1.&nbsp;Limitations of the plugins DSL</h3></div></div></div><p>
                The new way to add plugins to a project is much more than a more convenient syntax. The new DSL is processed very
                differently to the old one. The new mechanism allows Gradle to determine the plugins in use very early and very
                quickly. This allows Gradle to do smart things such as:
            </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem">Optimize the loading and reuse of plugin classes.</li><li class="listitem">Allow different plugins to use different versions of dependencies.</li><li class="listitem">Provide editors detailed information about the potential properties and values in the buildscript for
                editing assistance.</li></ul></div><p>
                This requires that plugins be specified in a way that Gradle can easily and quickly extract, before executing the
                rest of the build script. It also requires that the definition of plugins to use be somewhat static.
            </p><p>
                There are some key differences between the new plugin mechanism and the &ldquo;traditional&rdquo; <code class="code">apply()</code> method
                mechanism. There are also some constraints, some of which are temporary limitations while the mechanism is still
                being developed and some are inherent to the new approach.
            </p><div class="section"><div class="titlepage"><div><div><h4 class="title"><a name="N12E5F"></a>25.5.1.1.&nbsp;Constrained Syntax</h4></div></div></div><p>
                    The new <code class="code">plugins {}</code> block does not support arbitrary Groovy code. It is constrained, in order to be idempotent
                    (produce the same result every time) and side effect free (safe for Gradle to execute at any time).
                </p><p>
                    The form is:
                </p><pre class="programlisting">
plugins {
    id &laquo;plugin id&raquo; version &laquo;plugin version&raquo;
}
                </pre><p>
                    Where <code class="literal">&laquo;plugin version&raquo;</code> and <code class="literal">&laquo;plugin id&raquo;</code> must be constant, literal, strings.
                    No other statements are allowed; their presence will cause a compilation error.
                </p><p>
                    The <code class="code">plugins {}</code> block must also be a top level statement in the buildscript. It cannot be nested inside
                    another construct (e.g. an if-statement or for-loop).
                </p></div><div class="section"><div class="titlepage"><div><div><h4 class="title"><a name="N12E78"></a>25.5.1.2.&nbsp;Can only be used in build scripts</h4></div></div></div><p>
                    The <code class="code">plugins {}</code> block can currently only be used in a project's build script. It cannot be used in
                    script plugins, the settings.gradle file or init scripts.
                </p><p>
                    <span class="emphasis"><em>Future versions of Gradle will remove this restriction.</em></span>
                </p></div><div class="section"><div class="titlepage"><div><div><h4 class="title"><a name="N12E85"></a>25.5.1.3.&nbsp;Cannot be used in conjunction with subprojects {}, allprojects {}, etc</h4></div></div></div><p>
                    It is not possible to use the familiar pattern of applying a plugin to multiple projects at once using <code class="code">subprojects {}</code>,
                    etc at the moment. There is currently no mechanism for applying a plugin to multiple projects at once. At the moment, each
                    project that requires a plugin must declare so in the <code class="code">plugins {}</code> block in its buildscript.
                </p><p>
                    <span class="emphasis"><em>Future versions of Gradle will remove this restriction.</em></span>
                </p></div><p>
                If the restrictions of the new syntax are prohibitive, the recommended approach is to apply plugins using the
                <a class="link" href="plugins.html#sec:applying_plugins_buildscript">buildscript {} block</a>.
            </p></div></div><div class="section"><div class="titlepage"><div><div><h2 class="title"><a name="N12E9B"></a>25.6.&nbsp;Finding community plugins</h2></div></div></div><p>
            Gradle has a vibrant community of plugin developers who contribute plugins for a wide variety of capabilities.
            The Gradle <a class="ulink" href="http://plugins.gradle.org" target="_top">plugin portal</a> provides an interface for searching and
            exploring community plugins.
        </p></div><div class="section"><div class="titlepage"><div><div><h2 class="title"><a name="N12EA4"></a>25.7.&nbsp;More on plugins</h2></div></div></div><p>
            This chapter aims to serve as an introduction to plugins and Gradle and the role they play. For more information on the inner workings
            of plugins, see <a class="xref" href="custom_plugins.html">Chapter&nbsp;39, <i>Writing Custom Plugins</i></a>.
        </p></div></div><div class="navfooter"><div><div class="navbar"><a xmlns:xslthl="http://xslthl.sf.net" href="multi_project_builds.html" title="Chapter&nbsp;24.&nbsp;Multi-project Builds">Previous</a><span>|</span><a xmlns:xslthl="http://xslthl.sf.net" href="userguide.html" title="Gradle User Guide">Contents</a><span>|</span><a xmlns:xslthl="http://xslthl.sf.net" href="standard_plugins.html" title="Chapter&nbsp;26.&nbsp;Standard Gradle plugins">Next</a></div></div></div></body></html>

APT Browse - Built by Thomas Orozco.