/usr/share/doc/gradle/userguide/embedding.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 | <html><head><META http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>Chapter 13. Embedding Gradle</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="pt02.html" title="Part II. Working with existing builds"><link rel="prev" href="troubleshooting.html" title="Chapter 12. Troubleshooting"><link rel="next" href="pt03.html" title="Part III. Writing Gradle build scripts"></head><body><div class="navheader"><div><div class="navbar"><a xmlns:xslthl="http://xslthl.sf.net" href="troubleshooting.html" title="Chapter 12. Troubleshooting">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="pt03.html" title="Part III. Writing Gradle build scripts">Next</a></div></div></div><div class="chapter"><div class="titlepage"><div><div><h1 xmlns:xslthl="http://xslthl.sf.net"><a name="embedding"></a>Chapter 13. Embedding Gradle</h1></div></div></div><div class="section"><div class="titlepage"><div><div><h2 class="title"><a name="sec:embedding_introduction"></a>13.1. Introduction to the Tooling API</h2></div></div></div><p>The 1.0 milestone 3 release brought a new API called the tooling API,
which you can use for embedding Gradle into your own custom software. This API allows you to execute and monitor builds,
and to query Gradle about the details of a build.
The main audience for this API will be IDEs, CI servers, other UI authors, or integration testing of your Gradle plugins.
However, it is open for anyone who needs to embed Gradle in their application.
</p><p>A fundamental characteristic of the tooling API is that it operates in a version independent way.
This means that you can use the same API to work with different target versions of Gradle.
The tooling API is Gradle wrapper aware and, by default,
uses the same target Gradle version as that used by the wrapper-powered project.
</p><p>Some features that the tooling API provides today:
</p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem">You can query Gradle for the details of a build,
including the project hierarchy and the project dependencies,
external dependencies (including source and Javadoc jars),
source directories and tasks of each project.
</li><li class="listitem">You can execute a build and listen to stdout and stderr logging and progress
(e.g. the stuff shown in the 'status bar' when you run on the command line).
</li><li class="listitem">Tooling API can download and install the appropriate Gradle version, similar to the wrapper.
Bear in mind that the tooling API is wrapper aware so you should not need to configure a Gradle distribution directly.
</li><li class="listitem">The implementation is lightweight, with only a small number of dependencies.
It is also a well-behaved library, and makes no assumptions about your classloader structure or logging configuration.
This makes the API easy to bundle in your application.
</li></ul></div><p>
</p><p>In the future we may support other interesting features:
</p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem">Performance. The API gives us the opportunity to do lots of caching,
static analysis and preemptive work, to make things faster for the user.
</li><li class="listitem">Better progress monitoring and build cancellation.
For example, allowing test execution to be monitored.
</li><li class="listitem">Notifications when things in the build change, so that UIs and models can be updated.
For example, your Eclipse or IDEA project will update immediately, in the background.
</li><li class="listitem">Validating and prompting for user supplied configuration.
</li><li class="listitem">Prompting for and managing user credentials.
</li></ul></div><p>
</p></div><div class="section"><div class="titlepage"><div><div><h2 class="title"><a name="sec:embedding_daemon"></a>13.2. Tooling API and the Gradle Build Daemon</h2></div></div></div><p>Please take a look at <a class="xref" href="gradle_daemon.html">Chapter 6, <i>The Gradle Daemon</i></a>.
The Tooling API uses the daemon all the time. In fact, you cannot officially use the Tooling API without the daemon.
This means that subsequent calls to the Tooling API, be it model building requests or task executing requests
can be executed in the same long-living process. <a class="xref" href="gradle_daemon.html">Chapter 6, <i>The Gradle Daemon</i></a> contains more details about the daemon,
specifically information on situations when new daemons are forked.
</p></div><div class="section"><div class="titlepage"><div><div><h2 class="title"><a name="sec:embedding_quickstart"></a>13.3. Quickstart</h2></div></div></div><p>As the tooling API is an interface for developers, the Javadoc is the main documentation for it.
This is exactly our intention - we don't expect this chapter to grow very much.
Instead we will add more code samples and improve the Javadoc documentation.
The main entry point to the tooling API is the
<a class="ulink" href="../javadoc/org/gradle/tooling/GradleConnector.html" target="_top"><code class="classname">GradleConnector</code></a>.
You can navigate from there to find code samples and other instructions.
Another very important set of resources are the <span class="emphasis"><em>samples</em></span> that live
in “<code class="filename">$gradleHome/samples/toolingApi</code>”. These samples also specify all of the
required dependencies for the Tooling API, along with the suggested repositories to obtain the jars from.
</p></div></div><div class="navfooter"><div><div class="navbar"><a xmlns:xslthl="http://xslthl.sf.net" href="troubleshooting.html" title="Chapter 12. Troubleshooting">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="pt03.html" title="Part III. Writing Gradle build scripts">Next</a></div></div></div></body></html>
|