Gradle assemble task essentials

Learn everything you’ll ever need to know about Gradle’s task for creating artifacts, assemble.

Assemble is a task you run from the command line using ./gradlew assemble in Linux and Mac or gradlew assemble in Windows.

To fully understand assemble you need to know about the 2 types of Gradle tasks:

1. actionable tasks have some action(s) attached to do work in your build
2. lifecycle tasks are workflow tasks with no actions attached

Assemble is a lifecycle task with no actions attached. Lifecycle tasks often combine other tasks and are useful to run in your development workflow.

The purpose of assemble is to combine all tasks which produce a distribution or artifact into a single task.

For Maven users out there, assemble is similar to Maven’s package phase. 

Adding assemble to a Gradle project

assemble is added into your Gradle project by the base plugin, which registers standard tasks to ensure consistency.

Tasks added by the base plugin (from Gradle docs)

The base plugin is applied automatically by java and other plugins, so don’t be surprised if you’ve never heard of it.

We’ll apply the base plugin in a Gradle Kotlin build script.

plugins {
    base
}

When we run the tasks task we see that assemble is in the build tasks group.

$ ./gradlew tasks
...
Build tasks
-----------
assemble - Assembles the outputs of this project.
...

At this point when we run assemble, it doesn’t do anything.

It’s up to other plugins or you as a build author to configure assemble to depend on the relevant artifact producing tasks.

Tasks that assemble depends on

One example of how this works is the java plugin.

plugins {
    java
}

This adds a jar task to package compiled classes and resources into a jar file. It also configures assemble to depend on jar.  

So in a Java project when we run assemble, jar runs first, generating a jar file.

The Spring Boot plugin also sets up task dependencies from assemble to its own tasks. 

plugins {
    id("org.springframework.boot") version "2.6.2"
}

Let’s run assemble, and we see that Gradle runs bootJar first to generate the special Spring Boot fat jar file.

If you have other tasks that generate artifacts, you can hook them into the assemble task by configuring a task dependency. 

val customArtifactTask by tasks.registering {
    doLast {
        // create some custom artifact
    }
}

tasks.named("assemble") {
    dependsOn(customArtifactTask)
}

Ways to run assemble

So what ways can we run assemble?

You’ve seen the simplest of just passing the full task name with ./gradlew assemble.

But you can also use an abbreviated name of ./gradlew a, saving you 7 precious keystrokes! 😂

In IntelliJ IDEA, the assemble task is in the Gradle tool window under build. Double click it to run.

Assemble also gets run when you run the build task, because of a task dependency added by the base plugin.

Gradle runs assemble then check, the verification task which you can learn all about in this article.

When you run assemble when nothing’s changed in your project, it’s marked as UP-TO-DATE and no work should be done, saving you time.

When to use assemble

That leaves the question then, when should you use assemble?

Well, any time you need to build your application’s artifacts without running any verification tasks. That might be if you want to try out code changes in the generated jar file, but aren’t concerned at the moment about running additional checks.

assemble vs. build

You can also run assemble by running build, but that also runs tests which you might not want.

Running assemble instead of build can be quicker.

assemble vs. jar

Assemble is a superset of all artifact producing tasks, and includes jar which generates your application’s jar file. If jar is the only artifact producing task in your project, then assemble and jar are equivalent.

But it might be a good idea to start using assemble now, in case you ever add any other artifact producing tasks in the future.

To learn more about the Gradle fundamentals in Java projects, such as the task graph, why not check out my free course Get Going with Gradle?

Stop reading Gradle articles like these

This article helps you fix a specific problem, but it doesn't teach you the Gradle fundamentals you need to actually help your team succeed.

Instead, follow a step-by-step process that makes getting started with Gradle easy.

Download this Free Quick-Start Guide to building simple Java projects with Gradle.

• Learn to create and build Java projects in Gradle.
• Understand the Gradle fundamentals.

Download Now