This plugin provides prerequisites lifecycle to Gradle.
Prerequisites are all external artifacts used by the project.
Some artifacts should be preinstalled. For example, Gradle requires JRE to run under, and even Gradle Wrapper doesn't have an ability to download and install it for you.
Other artifacts could be installed automatically during build.
If you are using Gradle only, then you probably don't need this plugin. Gradle can manage Java (Maven and Ivy) dependencies by itself.
But if you use Gradle as main build tool for multi-language project and use different tools to install packages for different languages like Bundler, NPM or Pipenv then this plugin could help you to combine themselves into one lifecycle.
In the future we will have separate plugins for Bundler, NPM, Pipenv and maybe some more, which will be able to use generic prerequisites lifecycle provided by this plugin.
There are two types of prerequisites:
The distinction between them is relevant when we think in the terms of produced artifacts. If the prerequisite is used by produced artifact then the change of prerequisite or version could affect consumers and so could introduce breaking change. Сhanges in build tools prerequisites generally don't produce breaking changes (although, there could be exclusions).
The plugin follows Bundler-like style of managing prerequisites.
For each set of prerequisites there are three tasks:
install
— locks prerequisites' versions if they are not
already locked, then downloads and installs locked versions.
Note that for tools that could download prerequisites dynamically,
like Gradle itself, downloading and installation is not performed.
This should be run once at the start of new project
or after repository clone
update
— does the same as install
except that it also updates
locked versions
outdated
— prints all prerequisites that have
more recent versions available than locked
So, there are 9 tasks in total:
installPrerequisites | updatePrerequisites | outdatedPrerequisites |
installBuildTools | updateBuildTools | outdatedBuildTools |
installDependencies | updateDependencies | outdatedDependencies |
For Gradle >= 4.8 plugin integrates with built-in dependency locking mechanism, no extra setup is needed.
This lead to the following two requirements for running
install
and update
tasks with Gradle >= 4.8:
--write-locks
argument.There is an inconsistency: buildSrc
project belongs in whole
to build tools, but running updateDependencies
updates buildSrc
dependencies too.
There is no known way to overcome it.
Note that annotationProcessor
configurations are considered as build
tools, although, there could be a situation where annotation processor
generates some API, and change of processor version changes
that public API.
If this is your case, please, report an issue.
This plugin is NOT currently integrated with Gradle Wrapper.
Since wrapper
task should be run twice it is done manually.
It will be implemented in the future - see #4.
Plugin automatically integrates with the following plugins if they are applied. Some plugins don't provide a way to separate prerequisites to build tools and dependencies, such integration is called generic.
Plugin | Integration | Notes |
---|---|---|
nebula.dependency-lock |
generic | Full integration is possible, but not implemented |
com.github.jruby-gradle set of plugins |
full | Only with Gradle >= 4.8 dependency locking |
org.ajoberstar.stutter |
full | |
com.github.ben-manes.versions |
generic | |
com.ofg.uptodate |
generic |
Offerings and pull requests to support other plugins are appreciated.
This is self-applying plugin. That means that build script requires
the plugin itself (just compiled, not released to the repository).
So, if there are any errors during compilation or plugin applying,
Gradle build script just doesn't work.
If it is a compilation error, you can run ../gradlew build
in buildSrc
directory to figure out what's going on.
Copyright © 2018 Basil Peace
This file is part of gradle-prerequisites-plugin.
Copying and distribution of this file, with or without modification, are permitted in any medium without royalty provided the copyright notice and this notice are preserved. This file is offered as-is, without any warranty.