# Chapter 13. Writing Build Scripts

This chapter looks at some of the details of writing a build script.

## 13.1. Project API

In the tutorial in Chapter 6, Java Quickstart we used, for example, the `apply()` method. Where does this method come from? We said earlier that the build script defines a project in Gradle. For each project in the build creates an instance of type `Project` and associates this `Project` object with the build script. As the build script executes, it configures this `Project` object:

### Getting help writing build scripts

Don't forget that your build script is simply Groovy code that drives the Gradle API. And the `Project` interface is your starting point for accessing everything in the Gradle API. So, if you're wondering what 'tags' are available in your build script, you can start with the javadocs for the `Project` interface.

- Any method you call in your build script, which is not defined in the build script, is delegated to the `Project` object.

- Any property you access in your build script, which is not defined in the build script, is delegated to the `Project` object.

Let's try this out and try to access the `name` property of the `Project` object.

Example 13.1. Accessing property of the Project object

`build.gradle`

    println name
    println project.name

    task check << {
    }

Output of `gradle -q check`

    > gradle -q check
    projectApi
    projectApi

Both `println` statements print out the same property. The first uses auto-delegation to the `Project` object, for properties not defined in the build script. The other statement uses the `project` property available to any build script, which returns the associated `Project` object. Only if you define a property or a method which has the same name as a member of the `Project` object, you need to use the `project` property.

### 13.1.1. Standard project properties

The `Project` object provides some standard properties, which are available in your build script. The following table lists a few of the commonly used ones.

Table 13.1. Project Properties

Name | Type | Default Value
`project` | `Project` | The `Project` instance
`name` | `String` | The name of the directory containing the build script.
`path` | `String` | The absolute path of the project.
`description` | `String` | A description for the project.
`buildFile` | `File` | The build script.
`projectDir` | `File` | The directory containing the build script.
`buildDirName` | `String` | `build`
`buildDir` | `File` | ``projectDir`/build`
`group` | `Object` | `unspecified`
`version` | `Object` | `unspecified`
`ant` | `AntBuilder` | An `AntBuilder` instance

Below is a sample build which demonstrates some of these properties.

Example 13.2. Project properties

Build layout

    projectCoreProperties/
      build.gradle
      subProject/
        build.gradle

`build.gradle`

    task check << {
        allprojects {
            println "project path $path"
            println "  project name = $name"
            println "  project dir = '${rootProject.relativePath(projectDir)}'"
            println "  build file = '${rootProject.relativePath(buildFile)}'"
            println "  build dir = '${rootProject.relativePath(buildDir)}'"
        }
    }

Output of `gradle -q check`

    > gradle -q check
    project path :
      project name = projectCoreProperties
      project dir = '.'
      build file = 'build.gradle'
      build dir = 'build'
    project path :subProject
      project name = subProject
      project dir = 'subProject'
      build file = 'subProject/build.gradle'
      build dir = 'subProject/build'

## 13.2. Script API

When Gradle executes a script, it compiles the script into a class which implements `Script` .