Differences between revisions 3 and 4
Revision 3 as of 2018-08-15 09:10:41
Size: 3367
Editor: ?MarkusKoschany
Comment:
Revision 4 as of 2021-04-05 18:48:41
Size: 6253
Comment: Add tips for debugging build system with Gradle
Deletions are marked like this. Additions are marked like this.
Line 13: Line 13:

= Examples =

There are [[https://codesearch.debian.net/search?q=--buildsystem%3Dgradle|many packages in Debian]] that use the Gradle build system. They could act as a examples when your create a package that uses Gradle.
Line 40: Line 44:
= Debugging Tips =

The following tips could be useful when you have debug a build system written in Gradle, Gradle plugins or Gradle itself.

 * Setup a VM for development and perform all builds inside it without sbuilder/pbuilder. This is simpler for debugging.
 * Vagrant with KVM or VirtualBox is an easy to setup combination for a VM. Ensure that as many CPUs as possible are allocated to the build. Ensure that VM has atleast 4GiB RAM. Mount any additional shared folders. Following is a sample Vagrant configuration for using VirtualBox and Debian AMD64 testing.
 {{{
  Vagrant.configure("2") do |config|
    config.vm.box = "debian/testing64"
    config.vm.synced_folder "../../debian-developer/jitsi", "/jitsi"
    config.vm.provider "virtualbox" do |vb| vb.cpus = 4
      vb.cpus = 4
      vb.memory = "4096"
    end
  end
}}}
 * Invoke the build using gbp without the --git-pbuilder option.
 * Once a build fails with with gbp. It leaves the build directory in the failed state without further cleanup. One can run 'debian/rules override_dh_auto_build' or write a similar script to re-run the build without first cleaning it. It is possible then to:
   * Examine the files in their post-patched state (to map the correct line numbers etc.).
   * Try quick fixes on the source without having to go through quilt, git commit then and re-run gbp.
   * Continue the build instead from where it left off instead of fully rebuilding. This is possibly becuase maven/gradle build tools examine the source files and built output and figure out which ones need to be rebuilt avoiding ones that have already been built. This is usually safe. This is, no outputs are left outdated when sources change.
   * Additional arguments to Gradle can be sent by passing the argument to dh_auto_build after '--' in debian/rules in the override_dh_auto_build target.
 * Examine the build in detail with lot of log messages by adding '--debug' option to gradle.
 * To debug a build plugin, build script or gradle, use the Java debugger (jdb) from openjdk. Pass the option '-Dorg.gradle.debug=true' to gradle. Gradle will pause and wait for debugging after basic startup is completed. Then attach the debugger by running 'jdb -attach 5005'. You can also debug outside the VM with your favourite graphical tool if VM is configured to foward the port 5005 from host into the VM. After connecting, you can set breakpoints for specific methods or lines of code using 'stop on' and 'stop at' debugger commands. Gradle process can be resumed using 'resume'. It is possible to examine stack, switch context in the stack, print local variables, watch etc.

Translation(s): English

Gradle

Gradle is a sophisticated Java build system that uses a Groovy-based domain specific language. It is very flexible but this also makes it more difficult to package Gradle projects for Debian. It is possible for Gradle projects to use conventions but most of them look very different. Gradle is also known for frequent incompatibilities which is why upstream recommends to depend on a certain version of Gradle to avoid that kind of breakage. Packaging multiple versions of Gradle is not very Debian-like though because it leads to code duplication, more maintenance burden and possibly more security risks.

You will have to patch the build.gradle file most of the time, to remove unneeded plugins or make the build system Debian compliant, e.g. prevent any downloads from the internet at build time and use system libraries instead. The gradle-debian-helper package will help you to transform build-dependencies from Maven Central into local Debian coordinates in /usr/share/maven-repo. By adding a debian/maven.rules file it is possible to change groupId, artifactId or version similar to Maven based projects.

If you have a choice, we recommend to use a different build system like Ant or Maven which are better supported in Debian and are more stable when it comes to Debian Java packaging.

Examples

There are many packages in Debian that use the Gradle build system. They could act as a examples when your create a package that uses Gradle.

mongo-java-driver

The mongo-java-driver library is a typical Gradle-based library. In debian/rules you can specify --with buildsystem=gradle to make sure that the Gradle build system is used.

It uses maven_repo_helper to provide Maven artifacts. The debian/libmongodb-java.poms file installs the jars with the --artifact option into /usr/share/maven-repo but also into /usr/share/java (with --java-lib)

Please note that mongo-java-driver uses gradle-debian-helper. This means you can use a debian/maven.rules file to override Maven coordinates.

libsejda-eventstudio-java

This library is another very simple example of a Gradle-based library project. Similar to mongo-java-driver it uses maven-repo-helper to install Maven artifacts into /usr/share/maven-repo. Since the project did not provide a pom.xml file, it was downloaded from Maven Central and added to the debian directory.

syncany ( a Gradle-based application)

Syncany is a cloud storage and filesharing application. It is not ready for prime time yet but it also uses gradle-debian-helper to override Maven coordinates and is a good example of a typical Gradle-based application project.

Please note that you can omit compilation steps in debian/rules by using the -x option.

dh_auto_build -- installDist -x test

dh_auto_build will automatically recognize the Gradle build system and execute the installDist build step. However it is also smart enough to exclude the test build step. Just pass -x test.

Syncany is also an example of a Gradle-based project that installs its own startup script, which is patched by Debian. Symlinks are managed by the debian/links file, jar files are installed with install files. In this case there is no need to modify the MANIFEST attribute or to use jarwrapper or java-wrappers.

Debugging Tips

The following tips could be useful when you have debug a build system written in Gradle, Gradle plugins or Gradle itself.

  • Setup a VM for development and perform all builds inside it without sbuilder/pbuilder. This is simpler for debugging.
  • Vagrant with KVM or VirtualBox is an easy to setup combination for a VM. Ensure that as many CPUs as possible are allocated to the build. Ensure that VM has atleast 4GiB RAM. Mount any additional shared folders. Following is a sample Vagrant configuration for using VirtualBox and Debian AMD64 testing.

      Vagrant.configure("2") do |config|
        config.vm.box = "debian/testing64"
        config.vm.synced_folder "../../debian-developer/jitsi", "/jitsi"
        config.vm.provider "virtualbox" do |vb| vb.cpus = 4
          vb.cpus = 4
          vb.memory = "4096"
        end
      end
  • Invoke the build using gbp without the --git-pbuilder option.
  • Once a build fails with with gbp. It leaves the build directory in the failed state without further cleanup. One can run 'debian/rules override_dh_auto_build' or write a similar script to re-run the build without first cleaning it. It is possible then to:
    • Examine the files in their post-patched state (to map the correct line numbers etc.).
    • Try quick fixes on the source without having to go through quilt, git commit then and re-run gbp.
    • Continue the build instead from where it left off instead of fully rebuilding. This is possibly becuase maven/gradle build tools examine the source files and built output and figure out which ones need to be rebuilt avoiding ones that have already been built. This is usually safe. This is, no outputs are left outdated when sources change.
    • Additional arguments to Gradle can be sent by passing the argument to dh_auto_build after '--' in debian/rules in the override_dh_auto_build target.
  • Examine the build in detail with lot of log messages by adding '--debug' option to gradle.
  • To debug a build plugin, build script or gradle, use the Java debugger (jdb) from openjdk. Pass the option '-Dorg.gradle.debug=true' to gradle. Gradle will pause and wait for debugging after basic startup is completed. Then attach the debugger by running 'jdb -attach 5005'. You can also debug outside the VM with your favourite graphical tool if VM is configured to foward the port 5005 from host into the VM. After connecting, you can set breakpoints for specific methods or lines of code using 'stop on' and 'stop at' debugger commands. Gradle process can be resumed using 'resume'. It is possible to examine stack, switch context in the stack, print local variables, watch etc.