Building a JAR with Dependencies Using Gradle: Resolving Configuration State Errors

Problem Background and Error Analysis

In Gradle multi-project builds, developers often need to create a JAR file that includes all dependencies for easy deployment and distribution. However, when defining such tasks, configuration state-related errors may occur. The error message in the original issue, Cause: You can't change a configuration which is not in unresolved state!, indicates an attempt to modify a configuration after it has been resolved, which is not permitted.

Core Solution

According to best practices, the key to resolving this issue is to ensure the mainClassName property is declared before the jar task definition. Here is the corrected code example:

// Main class name must be defined before the jar task
mainClassName = "com.company.application.Main"

jar {
  manifest { 
    attributes "Main-Class": "$mainClassName"
  }  

  from {
    configurations.compile.collect { it.isDirectory() ? it : zipTree(it) }
  }
}

This code collects all compile dependencies using configurations.compile.collect and includes them in the JAR file. The zipTree method handles JAR dependencies, ensuring all class files are properly packaged.

Advanced Configuration and Optimization

For more complex scenarios, it is advisable to create a separate fatJar task to avoid interfering with the standard jar task. Here is an enhanced example:

jar {
  manifest {
    attributes(
      'Main-Class': 'my.project.main',
    )
  }
}

task fatJar(type: Jar) {
  manifest.from jar.manifest
  classifier = 'all'
  from {
    configurations.runtimeClasspath.collect { it.isDirectory() ? it : zipTree(it) }
  } {
    exclude "META-INF/*.SF"
    exclude "META-INF/*.DSA"
    exclude "META-INF/*.RSA"
  }
  with jar
}

This configuration addresses two common issues: Manifest attribute setting and META-INF file conflicts. The exclude directive removes signature files to prevent security validation errors.

Integration into Build Process

To integrate the Fat JAR task into the standard build process, add it to the artifacts configuration:

artifacts {
    archives fatJar
}

This ensures the Fat JAR is automatically generated when executing the assemble or build tasks.

Version Compatibility Notes

Dependency configuration names may change across different Gradle versions. In newer versions, it is recommended to use configurations.runtimeClasspath instead of the older configurations.runtime to ensure proper dependency resolution.

Conclusion

By following the correct task definition order and using appropriate dependency collection methods, developers can effectively build JAR files that include all dependencies. It is recommended to choose the appropriate solution based on project requirements and be mindful of differences between Gradle versions.