// Copyright (C) 2024 Gradle, Inc.
//
// Licensed under the Creative Commons Attribution-Noncommercial-ShareAlike 4.0 International License.;
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
//      https://creativecommons.org/licenses/by-nc-sa/4.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.

[[part6_writing_tasks]]
= Part 6: Writing Tasks

Learn the basics of authoring Gradle tasks by creating a simple one in your Build script.

****
**In this section, you will:**

- Understand Tasks
- Create a custom Task for the Plugin
****

[[part6_begin]]
== Step 0. Before you Begin

1. You initialized your Java app in <<part1_gradle_init_project.adoc#part1_begin,part 1>>.
2. You understand the Gradle Build Lifecycle from <<part2_build_lifecycle.adoc#part2_begin,part 2>>.
3. You added a subproject and a separate Build in <<part3_multi_project_builds#part3_begin, part3>>.
4. You viewed a Settings file in <<part4_settings_file.adoc#part4_begin,part 4>>.
5. You authored a Build script in <<part5_build_scripts.adoc#part5_begin,part 5>>.

[[ab_part6_step1]]
== Step 1. Understand Tasks

A Task is an executable piece of code that contains sequences of actions.

Actions are added to a Task via the `doFirst{}` and `doLast{}` closures.

A Task can depend on other tasks.

[[ab_part6_step2]]
== Step 2. Register and Configure Tasks

Early on in the tutorial, we registered and configured `task1` in the `app` build script:

====
include::sample[dir="snippets/tutorials/authoring-builds/writingTasks-registerConfigure/kotlin",files="build.gradle.kts[tags=register-configure]"]
include::sample[dir="snippets/tutorials/authoring-builds/writingTasks-registerConfigure/groovy",files="build.gradle[tags=register-configure]"]
====
<1> You can use the `register()` method to create new tasks.
<2> You can use the `named()` method to configure existing tasks.

[[ab_part6_step3]]
== Step 3. Create a custom Task

To create a custom task, you must subclass link:{groovyDslPath}/org.gradle.api.DefaultTask.html#org.gradle.api.DefaultTask[`DefaultTask`] in Groovy DSL or link:{kotlinDslPath}/gradle/org.gradle.api/-default-task/index.html[`DefaultTask`] in Kotlin DSL.

Create a custom class called `LicenseTask` with the code below and add it to the bottom of the `gradle/license-plugin/plugin/src/main/kotlin/license/LicensePlugin.kt` or `gradle/license-plugin/plugin/src/main/groovy/license/LicensePlugin.groovy` file:

====
include::sample[dir="snippets/tutorials/authoring-builds/writingTasks-licenseTask/kotlin",files="build.gradle.kts[tags=license-task]"]
include::sample[dir="snippets/tutorials/authoring-builds/writingTasks-licenseTask/groovy",files="build.gradle[tags=license-task]"]
====

The `LicenseTask` class encapsulates the task action logic and declares any inputs and outputs the task expects.

The task action is annotated with `@TaskAction`.
Inside, the logic first finds a file called "license.txt".
This file contains text for an Apache license:

.license.txt
[source,text]
----
/*
* Licensed under the Apache License
*/
----

The task then looks for files with the extension `.java` and adds a license header.

The task has a single input, the license file name, annotated with `@Input`.

Gradle uses the `@Input` annotation to determine if the task needs to run.
If the task has not run before or if the input value has changed since the previous execution, then Gradle will execute the task.

While a custom class has been created, it is not yet added to the `LicensePlugin`.
Running `LicenseTask` is not currently possible.

All you can do for now is make sure `./gradlew build` runs without failing:

[source,bash]
----
$ ./gradlew build
----
[source,text]
----
SETTINGS FILE: This is executed during the initialization phase

> Configure project :app
BUILD SCRIPT: This is executed during the configuration phase

BUILD SUCCESSFUL in 1s
13 actionable tasks: 6 executed, 7 up-to-date
----

[.text-right]
**Next Step:** <<part7_writing_plugins#part7_writing_plugins,Writing Plugins>> >>
