Recommended way to stop a Gradle build

Question

How can I stop a Gradle build after detecting a problem? I can use an assert, throw an exception, do a System.exit (bad idea), or use a dedicated function in Gradle (but I could not find one). What is the best way for Gradle (and why?).

Solution 1

I usually throw the relevant exception from the org.gradle.api package, for example InvalidUserDataException for when someone has entered something invalid, or GradleScriptException for more general errors.

If you want to stop the current task or action, and move on to the next, you can also throw a StopActionException

Solution 2

If you want to stop the build, throw:

throw new GradleException('error occurred')

or throw the subclasses for the above exception. Some of the subclass exceptions actually only fail the current task but continue with the build.

Solution 3

There is currently no dedicated method, although there have been discussions to add one.

The recommended way to stop a Gradle build is to throw an exception. Since Groovy doesn't have checked exceptions, and Gradle by default does not print the exception type, it's not that critical which exception is thrown. In build scripts, GradleException is often used, but a Groovy assertion also seems reasonable (depending on the circumstances and audience). What's important is to provide a clear message. Adding a cause (if available) helps for debugging (--stacktrace).

Gradle provides dedicated exception types StopExecutionException/StopActionException for stopping the current task/task action but continuing the build.

Solution 4

Another option if you don't have any desire to be able to catch the exception later on is to call the ant fail task. It's slightly easier to read in my opinion and you can give a nice message to the user without use of --stacktrace.

task (tarball, dependsOn: warAdmin) << {
    ant.fail('The sky is falling!!')
}

Gives you a message like:

* What went wrong:
Execution failed for task ':tarball'.
> The sky is falling!!

Probably you can catch this (perhaps it throws ant's BuildException?) but if that's a goal then I wouldn't use ant.fail. I'd just make it easy to see what exception to catch by throwing standard gradle exception as tim_yates suggested.

Solution 5

Throwing a simple GradleException works in stopping the build script. This works great for checking required environment setup.

GradleException('your message, why the script is stopped.')

Example:

if(null == System.getenv()['GRADLE_USER_HOME']) {
    throw new GradleException('Required GRADLE_USER_HOME environment variable not set.')
}

View more solutions

Comments

[powder366]

How do I set it up? Call it?

[Gus]

just call ant.fail('message of your choice') no setup required

[Xabs]

You can also use TaskExecutionException if a task does not execute successfully. (This is true according to the gradle 1.11 docs, I'm not sure when it was introduced.)

[Groostav]

are there any nice syntax options here? Consider kotlin's preconditions syntax: require(something != whatever) { "No good!" } as opposed to the more verbose and type-ee if(something != whatever){ throw new GradleException("No good!") }

[Hakanai]

The awful thing about GradleScriptException is that it requires a second parameter for a cause.

[mgaert]

It looks like the output of this is identical to using throw new GradleException("The sky is falling!!") (Gradle 3.4.1)

[Gus]

@mgaert I seem to recall that 4 years ago when I wrote this, the message printed did differ (but that's a long time and I don't feel like figuring out what version was current at that time and checking). Beyond that, IMHO ant.fail more clearly communicates the intent to fully stop the build, whereas the thrown exception reads as something that might be caught and handled.

[will]

... Of course we are avoiding saying that this is "programming by exceptions"?! I have legacy coded written that way and it is a horror to maintain ... In the olde days the philosophy around make is that rules (task-s) succeeded or failed. I once tried return false -- Gradle just ignored it and continued to run.