<!--
  ~ Copyright 2009 the original author or authors.
  ~
  ~ Licensed under the Apache License, Version 2.0 (the "License");
  ~ you may not use this file except in compliance with the License.
  ~ You may obtain a copy of the License at
  ~
  ~      http://www.apache.org/licenses/LICENSE-2.0
  ~
  ~ Unless required by applicable law or agreed to in writing, software
  ~ distributed under the License is distributed on an "AS IS" BASIS,
  ~ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  ~ See the License for the specific language governing permissions and
  ~ limitations under the License.
  -->
<chapter id='overview' xmlns:xi="http://www.w3.org/2001/XInclude">
    <title>Overview</title>
    <section id='sec:special_feature_of_gradle'>
        <title>Features</title>
        <para>Here is a list of some of Gradle's features.
        </para>
        <variablelist>
            <varlistentry>
                <term>Declarative builds and build-by-convention</term>
                <listitem>
                    <para>At the heart of Gradle lies a rich extensible Domain Specific Language (DSL) based on Groovy.
                        Gradle pushes declarative builds to the next level by providing declarative language elements
                        that you can assemble as you like. Those elements also provide build-by-convention support for
                        Java, Groovy, OSGi, Web and Scala projects. Even more, this declarative language is extensible.
                        Add your own new language elements or enhance the existing ones. Thus providing concise,
                        maintainable and comprehensible builds.
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>Language for dependency based programming</term>
                <listitem>
                    <para>The declarative language lies on top of a general purpose task graph, which you can fully
                        leverage in your builds. It provides utmost flexibility to adapt Gradle to your unique needs. 
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>Structure your build</term>
                <listitem>
                    <para>The suppleness and richness of Gradle finally allows you to apply common design principles to your build.
                        For example, it is very easy to compose your build from reusable
                        pieces of build logic. Inline stuff where unnecessary indirections would be inappropriate. Don't be
                        forced to tear apart what belongs together (e.g. in your project hierarchy). Thus avoiding smells
                        like shotgun changes or divergent change that turn your build into a maintenance nightmare.
                        At last you can create a well structured, easily maintained, comprehensible build.</para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>Deep API</term>
                <listitem>
                    <para>From being a pleasure to be used embedded to its many hooks over the whole lifecycle of build
                        execution, Gradle allows you to monitor and customize its configuration and execution behavior
                        to its very core.
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>Gradle scales</term>
                <listitem>
                    <para>Gradle scales very well. It significantly increases your productivity,
                        from simple single project builds up to huge enterprise multi-project builds. This is true
                        for structuring the build. With the state-of-art incremental build function, this is also true for
                        tackling the performance pain many large enterprise builds suffer from.
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>Multi-project builds</term>
                <listitem>
                    <para>Gradle's support for multi-project build is outstanding. Project dependencies are first class
                        citizens. We allow you to model the project relationships in a multi-project build as they really
                        are for your problem domain. Gradle follows your layout not vice versa.
                    </para>
                    <para>Gradle provides partial builds. If you build a single subproject Gradle takes care of building
                        all the subprojects that subproject 
                        depends on. You can also choose to rebuild the subprojects that depend on a particular subproject.
                        Together with incremental builds this is a big time saver for larger builds.
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>Many ways to manage your dependencies</term>
                <listitem>
                    <para>Different teams prefer different ways to manage their external dependencies.
                        Gradle provides convenient support for any strategy. From transitive dependency 
                        management with remote maven and ivy repositories to jars or dirs on the local file system.</para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>Gradle is the first build integration tool</term>
                <listitem>
                    <para>Ant tasks are first class citizens. Even more interesting, Ant projects are first class citizens as well.
                        Gradle provides a deep import for any Ant project, turning Ant targets into native Gradle tasks at runtime.
                        You can depend on them from Gradle, you can enhance them from Gradle, you can even declare dependencies on
                        Gradle tasks in your build.xml. The same integration is provided for properties, paths, etc ...</para>
                    <para>Gradle fully supports your existing Maven or Ivy repository infrastructure for publishing and retrieving
                        dependencies. Gradle also provides a converter for turning a Maven pom.xml into a Gradle script.
                        Runtime imports of Maven projects will come soon.</para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>Ease of migration</term>
                <listitem>
                    <para>Gradle can adapt to any structure you have. Therefore you can always develop your Gradle build
                        in the same branch where your production build lives and both can evolve in parallel.
                        We usually recommend to write tests that make sure that the produced artifacts are similar.
                        That way migration is as less disruptive and as reliable as possible. This is following the best-practices
                        for refactoring by applying baby steps.
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>Groovy</term>
                <listitem>
                    <para>Gradle's build scripts are written in Groovy, not XML. But unlike other approaches this is not
                        for simply exposing the raw scripting power of a dynamic language. That would just lead to a very
                        difficult to maintain build. The whole design of Gradle is oriented towards being used as a language,
                        not as a rigid framework. And Groovy is our glue that allows you to tell your individual story with
                        the abstractions Gradle (or you) provide. Gradle provides some standard stories but they are not
                        privileged in any form. This is for us a major distinguishing features compared to other declarative
                        build systems. Our Groovy support is also not just some simple coating sugar layer. The whole Gradle API
                        is fully groovynized. Only by that using Groovy is the fun and productivity gain it can be.
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>The Gradle wrapper</term>
                <listitem>
                    <para>The Gradle Wrapper allows you to execute Gradle builds on machines where Gradle is not
                        installed. This is useful for example for some continuous integration servers. It is also
                        useful for an open source project to keep the barrier low for building it. The wrapper is also
                        very interesting for the enterprise. It is a zero administration approach for the client machines.
                        It also enforces the usage of a particular Gradle version thus minimizing support issues. 
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>Free and open source</term>
                <listitem>
                    <para>Gradle is an open source project, and is licensed under the <ulink url="website:license.html">ASL</ulink>.
                    </para>
                </listitem>
            </varlistentry>
        </variablelist>
    </section>
    <section id='sec:why_groovy'>
        <title>Why Groovy?</title>
        <para>We think the advantages of an internal DSL (based on a dynamic language) over XML are tremendous in case
            of <emphasis>build scripts</emphasis>. There are a couple of dynamic languages out there. Why Groovy? The
            answer lies in the context Gradle is operating in. Although Gradle is a general purpose build tool at its
            core, its main focus are Java projects.
            In such projects obviously the team members know Java. We think a build
            should be as transparent as possible to <emphasis>all</emphasis> team members.
        </para>
        <para>You might argue why not using Java then as the language for build scripts. We think this is a valid
            question. It would have the highest transparency for your team and the lowest learning curve. But due to
            limitations of Java such a build language would not be as nice, expressive and powerful as it could be.
            <footnote>
                <para>At
                    <ulink url='http://www.defmacro.org/ramblings/lisp.html'/>
                    you find an interesting article comparing Ant, XML, Java and Lisp. It's funny that the 'if Java had
                    that syntax' syntax in this article is actually the Groovy syntax.
                </para>
            </footnote>
            Languages like Python, Groovy or Ruby do a much better job here. We have chosen Groovy as it offers by far
            the greatest transparency for Java people. Its base syntax is the same as Java's as well as its type system,
            its package structure and other things. Groovy builds a lot on top of that. But on a common ground with Java.
        </para>
        <para>For Java teams which share also Python or Ruby knowledge or are happy to learn it, the above arguments
            don't apply. The Gradle design is well-suited for creating another build script engine in JRuby or Jython.
            It just doesn't have the highest priority for us at the moment. We happily support any community effort
            to create additional build script engines.
        </para>
    </section>
</chapter>
