…and other useful stuff you can do with the Gradle build system.
The project uses Gradle as the build system. This is just a little collection of the common tasks you need to know to develop, build and deploy JBake. For more detailed information about gradle have a look at the gradle userguide.
To execute the tasks use the gradle wrapper. That way you do not need to install gradle for yourself and can be sure you are using the exact version everyone else is using to build JBake.
You can execute the build using one of the following commands from the root of the project:
-
./gradlew <task>(on Unix-like platforms such as Linux and Mac OS X) -
gradlew <task>(on Windows using the gradlew.bat batch file)
To get an overview of all available tasks with a short description run ./gradlew tasks
There are 4 projects:
- root aka. jbake-base
-
configures subprojects, jacoco execution aggregation and coveralls
- jbake-core
-
-
the core library. produces jbake-core-{version}.jar (
build/libs) -
publishes to bintray maven repository jbake-core
-
- jbake-maven-plugin
-
-
the JBake maven plugin, build by Gradle too
-
- jbake-dist
-
-
bundles the cli to an distribution (
build/distribution) -
publishes to bintray binary repository jbake
-
publish to sdkman
-
If you want to run a task in a specific project from root run ./gradlew :jbake-core:test for example.
While developing this is the most common task you should execute.
./gradlew test
This task compiles and executes all tests within src/test and produces a report afterwards.
You can find the report at jbake-core/build/reports/tests/test/index.html and can view it with your browser.
This is very useful if something went wrong.
You find the full stacktrace and output there.
The task is not very verbose. An successful execution looks like the following listing.
./gradlew test BUILD SUCCESSFUL in 53s 6 actionable tasks: 6 executed
You can set different log levels with the command option -i for info or -d for debug. (e.g.: ./gradlew -i test)
To execute the tests as soon as some input file changes run the task with
-t option.
./gradlew -t test Continuous build is an incubating feature. BUILD SUCCESSFUL in 0s 6 actionable tasks: 1 executed, 5 up-to-date Waiting for changes to input files of tasks... (ctrl-d to exit) <-------------> 0% WAITING > IDLE
The jbake-dist module has a task called smokeTest.
It executes the produced application, initializes a jbake project for each supported example project and bake it.
The check task depends on the smokeTest task and is part of the travis CI execution.
You can find the report at jbake-dist/build/reports/tests/smokeTest/
To generate a nice code coverage report run the following task.
./gradlew jacocoRootReport
It compiles your code, execute your tests, collect data and generate a report with jacoco. It produces XML and html reports. The xml file is used to trigger the coveralls service with the coveralls task.
The reports can be found at build/reports/jacoco/jacocoRootReport/html.
|
Note
|
This is an aggregation of all project modules. You can generate coverage reports for each module with The report can be found at |
The build task assembles and tests the project.
./gradlew build
It clones the example projects from github, creates zip files, generates start scripts for *NIX and Windows, bundles a distribution package, signs archives (if signing is configured properly), generates javadocs, assemble the packages and runs checks.
./gradlew build BUILD SUCCESSFUL in 47s 28 actionable tasks: 10 executed, 18 up-to-date
If successful you can find everything in the jbake-dist/build directory.
The distribution package can be found at jbake-dist/build/distributions and is called jbake-{version}-bin.zip
You can install the distribution locally.
./gradlew installDist
The distribution can be found in an exploded directory called jbake-dist/build/install/jbake.
|
Note
|
This task does not run checks. It just compiles and bundles the distribution. |
|
Warning
|
Never add credentials to the repository |
Bump desired project version in the projects gradle.properties file.
Like
version = 2.7.0
Commit and push to origin at github.
./gradlew signArchives ./gradlew githubRelease
The task will create a tag for you and create a release. Additionaly it uploads the binary distribution and the corresponding signature to the release.
|
Note
|
You need to add some properties to your local gradle.properties file (~/.gradle/gradle.properties) github.token=<access token> github.release.owner=jbake-org github.release.repo=jbake It’s also possible to dry-run this task. Execute |
You can publish to nexus with
./gradlew publishToSonatype
The task will create a staging repository. You need to close and publish it manually.
You can automate this process with the other tasks like closeSonatypeStagingRepository and closeAndReleaseSonatypeStagingRepository.
For more information see:
You need to add two properties to your local gradle.properties file (~/.gradle/gradle.properties).
sonatypeUsername=username sonatypePassword=secret
To release, set to default and announce a new candidate of JBake to sdkman run
./gradlew sdkMajorRelease
Add the following properties to your local gradle.properties file (~/.gradle/gradle.properties):
sdkman_consumer_key=key sdkman_consumer_token=token
To enable code signing you need to add some more properties to your local gradle.properties file (~/.gradle/gradle.properties):
signing.keyId=24875D73 signing.password=secret signing.secretKeyRingFile=/Users/me/.gnupg/secring.gpg
To skip signing on purpose add -PskipSigning=true.
The Checkstyle Plugin is configured to use our code conventions defined in config/checkstyle/checkstyle.xml.
It gets executed with the check Task and prints warnings about violations to the console.
A report can be found at jbake-core/build/reports/checkstyle/.
It’s sometimes hard to keep track of the latest versions for your dependencies. Fear not.
./gradlew dependencyUpdates :dependencyUpdates Download https://jcenter.bintray.com/org/assertj/assertj-core/3.8.0/assertj-core-3.8.0.pom ------------------------------------------------------------ : Project Dependency Updates (report to plain text file) ------------------------------------------------------------ The following dependencies are using the latest milestone version: - args4j:args4j:2.33 - org.asciidoctor:asciidoctorj:1.5.5 - commons-configuration:commons-configuration:1.10 - commons-io:commons-io:2.5 - org.apache.commons:commons-lang3:3.5 - org.kt3k.gradle.plugin:coveralls-gradle-plugin:2.8.1 - org.freemarker:freemarker:2.3.26-incubating - com.jfrog.bintray.gradle:gradle-bintray-plugin:1.7.3 - com.github.ben-manes:gradle-versions-plugin:0.14.0 - org.codehaus.groovy:groovy:2.4.11 - org.codehaus.groovy:groovy-templates:2.4.11 - de.neuland-bfi:jade4j:1.2.5 - org.eclipse.jetty:jetty-server:9.4.5.v20170502 - com.googlecode.json-simple:json-simple:1.1.1 - org.slf4j:jul-to-slf4j:1.7.25 - junit:junit:4.12 - ch.qos.logback:logback-classic:1.2.3 - ch.qos.logback:logback-core:1.2.3 - org.mockito:mockito-core:2.8.9 - com.orientechnologies:orientdb-graphdb:2.2.20 - org.slf4j:slf4j-api:1.7.25 - org.thymeleaf:thymeleaf:3.0.6.RELEASE The following dependencies exceed the version found at the milestone revision level: - org.pegdown:pegdown [1.6.0 <- 1.5.0] The following dependencies have later milestone versions: - org.assertj:assertj-core [3.7.0 -> 3.8.0] - org.apache.commons:commons-vfs2 [2.1 -> 2.1.1744488.1] Failed to determine the latest version for the following dependencies (use --info for details): - gradle.plugin.io.sdkman:gradle-sdkvendor-plugin Generated report file build/dependencyUpdates/report.txt BUILD SUCCESSFUL Total time: 6.721 secs