// Copyright 2017 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.

[[announce_plugin]]
= The Announce Plugin

[CAUTION]
====
This plugin is deprecated and will be removed in the next major Gradle release. New builds should not use this plugin.
====

The Gradle announce plugin allows you to send custom announcements during a build. The following notification systems are supported:

* https://twitter.com[Twitter]
* http://manpages.ubuntu.com/manpages/xenial/man1/notify-send.1.html[notify-send] (Ubuntu)
* https://sites.google.com/site/snarlapp/home[Snarl] (Windows)
* http://growl.info/[Growl] (macOS)

[[sec:announce_usage]]
== Usage

To use the announce plugin, apply it to your build script:

.Applying the announce plugin
====
include::sample[dir="announce/groovy",files="build.gradle[tags=use-plugin]"]
include::sample[dir="announce/kotlin",files="build.gradle.kts[tags=use-plugin]"]
====

[[sec:announce_configuration]]
== Configuration

NOTE: See also the link:{groovyDslPath}/org.gradle.api.plugins.announce.AnnouncePluginExtension.html[AnnouncePluginExtension] class in the API documentation.

Configure your notification service(s) of choice (see table below for which configuration properties are available):

.Configure the announce plugin
====
include::sample[dir="announce/groovy",files="build.gradle[tags=announce-plugin-conf]"]
include::sample[dir="announce/kotlin",files="build.gradle.kts[tags=announce-plugin-conf]"]
====

Finally, send announcements with the `announce` method:

.Using the announce plugin
====
include::sample[dir="announce/groovy",files="build.gradle[tags=announce-usage]"]
include::sample[dir="announce/kotlin",files="build.gradle.kts[tags=announce-usage]"]
====

The `announce` method takes two String arguments: The message to be sent, and the notification service to be used. The following list shows supported notification services and their configuration properties.

=== Supported notification services

`twitter`::
Works on all operating systems. Requires `username` and `password`.

`snarl`::
Windows only. Requires no extra configuration.

`growl`::
macOS only. Requires no extra configuration.

`notify-send`::
Ubuntu only. Requires the notify-send package to be installed. Use `sudo apt-get install libnotify-bin` to install it.

`local`::
Automatically chooses between snarl, growl, and notify-send depending on the current operating system.

