---------- Forwarded message ----------
From: Jason Porter <lightguard.jp@gmail.com>
Date: Wed, May 4, 2011 at 12:03 PM
Subject: Fwd: [gradle-user] tooling api
To: lincolnbaxter@gmail.com

Adam has done a good job of describing what the Tooling API is.
Certainly something to look into for forge.

---------- Forwarded message ----------
From: Adam Murdoch
Date: Sunday, May 1, 2011
Subject: [gradle-user] tooling api
To: user@gradle.codehaus.org

Hi,
The 1.0-milestone-3 release includes a new API, called the tooling
API, which you can use for embedding Gradle. This API allows you to
execute and monitor builds, and to query Gradle about the details of a
build. It does so in a version independent way, so that you can use
the same API to work with different versions of Gradle. The main
audience for this API is IDE, CI server, and other UI authors.
However, it is open for anyone who needs to embed Gradle in their
application.
So, what does this API give you? Here are some features:
* 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.
* You can execute a build, and listen to stdout and stderr logging and
progress (ie the stuff shown in the 'status bar' when you run on the
command line).
* Gradle wrapper aware and, by default, uses the same Gradle version
as that used when you run on the command-line.
* Downloads and installs the appropriate Gradle version, similar to the wrapper.
* Lightweight implementation, 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.
* Integrated with the daemon, and will use it where appropriate, for
fast builds which don't pollute the JVM which your application is
running in.
We plan to add a bunch more UI and IDE friendly features. Some examples:
* Performance. The API gives us the opportunity to do lots of caching,
static analysis and preemptive work, to make things faster for the
user. Given that this is the first cut of the API, the implementation
does not take advantage of this yet.
* Better progress monitoring and build cancellation. For example,
allowing test execution to be monitored.
* Notifications when things in the build change, so that UIs and
models can be updated.
* Validating and prompting for user supplied configuration.
* Prompting for and managing user credentials.
This API is now the official and recommended way to embed Gradle. This
means that the existing APIs, namely GradleLauncher and the open API
(UIFactory and friends), are now deprecated and will be removed in
future versions of Gradle. This will almost certainly happen before
Gradle 1.0 is released. And for the GradleLauncher API, this might
happen before the next milestone.
If you happen to use one of the above APIs, please consider changing
your application to use the tooling API instead.
You can find some samples in $gradleHome/samples/toolingApi. The build
files for these samples show the appropriate repository configuration
and dependency declarations you'll need in order to use it. See also
the Javadoc for GradleConnector, which is the main entry point of the
API: http://gradle.org/current/docs/javadoc/org/gradle/tooling/GradleConnector.html
The tooling API currently supports only Gradle 1.0-milestone-3. It
will also support any future releases of Gradle. At this stage, we are
not planning to add any support for older Gradle releases. That is,
you won't be able to use the tooling API to execute a build that needs
Gradle 0.9, for example. However, if there's a convincing reason, we
can look at adding support for some earlier Gradle releases.

--Adam Murdoch
Gradle Co-founder
http://www.gradle.org
VP of Engineering, Gradleware Inc. - Gradle Training, Support, Consulting
http://www.gradleware.com

--
Jason Porter
http://lightguard-jp.blogspot.com
http://twitter.com/lightguardjp

Software Engineer
Open Source Advocate
Author of Seam Catch - Next Generation Java Exception Handling

PGP key id: 926CCFF5
PGP key available at: keyserver.net, pgp.mit.edu