Статья-туториал от ведущего Java-разработчика "ITQ Group" Константина Киселевича.
Дорогой Junior и все, кто занимается copy-past конфигов Gradle.
В этой статье я хочу простым языком рассказать о gradl'овой конфигурации сборки проекта, чтобы вы не боялись использовать Gradle.
Давайте начнем с того, что после xml'ного Maven'а, действительно, непонятно, что значит каждая строчка из следующего примера:
buildscript { ext { springBootVersion = '2.7.4' lombokVersion = '1.18.24' h2Version = '2.1.214' orikaCoreVersion = '1.5.4' queryDslVersion = '4.2.2' javaxVersion = '1.3.2' sonarqubeVersion = '3.0' } } plugins { id('java-library') id('org.springframework.boot').version("${springBootVersion}").apply(false) id('org.sonarqube').version("${sonarqubeVersion}").apply(false) } allprojects { repositories { mavenCentral() } } subprojects { apply(plugin: 'java-library') apply(plugin: 'org.sonarqube') java { toolchain { languageVersion = JavaLanguageVersion.of(11) } withSourcesJar() withJavadocJar() } dependencies { api(platform("org.springframework.boot:spring-boot-dependencies:${springBootVersion}")) compileOnly("org.projectlombok:lombok:${lombokVersion}") annotationProcessor("org.projectlombok:lombok:${lombokVersion}") } } dependencies { implementation(project('deveducate-web')) }
Почему один dependencies {} вложен в subprojects {}, а второй - не вложен. Что такое buildscript {} и toolchain {}. Вопросов много, ответы в статье, но самый главный вопрос - что за программа этот текст читает и интерпретирует ?
Groovy
Давайте начнем с последнего вопроса и немного углубимся в историю.
Где-то в середине нулевых у программистов Java появились вопросы к языку - почему же так медленно появляются новые фичи? Действительно, посмотрим историю версий Java:
J2SE 5.0 сентябрь 2004
Java 6 декабрь 2006
Java 7 июль 2011
Java 8 март 2014
За 10 лет всего 4 версии. Прямо скажем, не так и много, как хотелось.
Ответом на такое медленное развитие стал язык Groovy. Его девиз: release early, release often (внедряй фичи раньше и чаще других).
Некоторые фичи Groovy перекочевали в другие языки:
синтаксис для оператора Элвиса "?:" (теперь в PHP и Kotlin);
оператор безопасной навигации "?." (теперь в C#, Swift, Kotlin и Ruby - как &.);
оператор <=> (теперь в PHP и Ruby).
Как называется программа ?
Программа называется Gradle. Скачать ее вы можете с сайта по ссылке.
Установка Gradle.
На выбор доступны два варианта работы с Gradle в проекте:
через файл gradle;
через файл gradlew, где w означает wrapper (обертка).
В чем разница ?
Разница в удобстве для ваших коллег. В случае использования обертки gradlew версия gradle будет одинаковой у всей команды, каждому из коллег не придется вручную качать дистрибутив gradle с сайта и проделывать манипуляции с распаковкой.
Итак.
Представим, что на вас возложили инициативу начать писать код проекта и использовать gradle в качестве сборщика проекта. Это большое доверие :)
Выберем директорией проекта C:\doit.
Поскольку вы первый в команде, вам необходимо самостоятельно скачать Gradle. Зайти на сайт по ссылке, скачать релиз и распаковать в какую-нибудь временную директорию вне директории проекта, например, C:\tmp.
Примерное содержание директории должно быть таким:
/bin /init.d /lib README
Нужный нам файл gradle находится в директории /bin.
Вы бережете время коллег, которым предстоит вместе с вами разрабатывать проект, и не хотите заставлять их так же вручную качать более 100мб дистрибутива Gradle и повторять ваши шаги.
Поэтому вы откроете терминал (cmd), зайдете в директорию проекта cd C:\doit и запустите C:\tmp\bin\gradle init.
В предложенных вариантах создания gradle проекта выберете basic. Это пустой проект.
В директории проекта C:\doit появились самые необходимые файлы: gradlew, settings.gradle и build.gradle и даже .gitignore.
В C:\doit\gradle\wrapper\gradle-wrapper.properties указана версия gradle:
distributionUrl=https\://services.gradle.org/distributions/gradle-7.5.1-bin.zip
Если вы добавите сгенерированные файлы в git, то у всех коллег будет одна и та же версия gradle и дистрибутив автоматически скачается при выполнении любой команды, например,
gradlew help
Таким образом, обертка gradle wrapper позволит всей команде вести разработку под одинаковой версией gradle и сама скачает/распакует дистрибутив в домашнюю директорию пользователя: ~\.gradle\wrapper\dists.
Gradle написан на Groovy + Kotlin.
Выше мы поговорили о скорости развития Groovy. Это важно, но существует еще одна причина в пользу языка.
Почему же Groovy был выбран для написания сценариев сборки проектов?
Ответ заключается в DSL. Groovy позволяет легко создавать новые специфические языки программирования под нужную нам задачу.
В Groovy для создания DSL реализуется концепция Метапрограммирования (по ссылке с диаграммой исполнения missingMethod).
Один из классов этой концепции - DelegatingScript:
Посмотрите пример и вы все поймете. Документация.
Cобственный язык (DSL)
Пример абстрактного файла для нашего выдуманного скриптового языка my.best.dsl.
foo(1,2) { // код метода } bar = "Hello world!";
А вот код класса на Groovy, который читает, парсит и выполняет скрипт my.best.dsl:
/** * класс с методом foo() и сеттером setBar() */ class MyDSL { public void foo(int x, int y, Closure z) { ... } public void setBar(String a) { ... } } CompilerConfiguration cc = new CompilerConfiguration(); cc.setScriptBaseClass(DelegatingScript.class.getName()); GroovyShell sh = new GroovyShell(cl,new Binding(),cc); DelegatingScript script = (DelegatingScript)sh.parse(new File("my.best.dsl")) script.setDelegate(new MyDSL()); script.run();
DelegatingScript парсит наш выдуманный язык, на котором мы написали скрипт my.best.dsl.
Но у DelegatingScript нет метода foo или setBar. Поэтому мы подсказываем, что исполнение методов необходимо делегировать объекту new MyDSL() (в строке script.setDelegate(new MyDSL())). То есть вызвать эти методы у объекта new MyDSL()
Заметьте, что метод foo последним аргументом имеет замыкание Closure.
public void foo(int x, int y, Closure z) { ... }
А в нашем придуманном языке вызов метода следующий:
foo(1,2) { // код метода }
Вот так в Groovy можно передавать аргументы: 1, 2 в скобках () и замыкание вне скобок ()если аргумент типа Closure последний в списке аргументов.
Надеюсь, теперь стало чуть понятнее, что такое в build.gradle
dependencies { implementation(project('deveducate-web')) }
dependencies(Closure c) - это метод с одним аргументом - функцией, тело которой содержит вызов метода implementation(...).
Согласитесь, насколько легко реализовать свой скриптовый язык при помощи Groovy.
Создатели сборщика проектов Gradle так же оценили эту возможность и придумали свой довольно простой язык.
Он действительно несложный. В нем, по сути, всего три главных метода: plugins(), buildScript(), task(). Аргументами этих методов являются функции, тело которых вы пишете в фигурных скобках { ... }.
Чуть-чуть подробнее. В примере выше методы foo и setBar принадлежали классу MyDSL. А какому классу/интерфейсу принадлежат plugins и buildScript ?
Они принадлежат интерфейсу org.gradle.api.Project: https://docs.gradle.org/current/javadoc/org/gradle/api/Project.html#buildscript-groovy.lang.Closure-
(Реализует же этот интерфейс класс org.gradle.api.internal.project.DefaultProject. Рекомендую клонировать сорцы gradle https://github.com/gradle/gradle и покопаться в них)
Прокрутите вверх интерфейс Project, указанный в ссылке выше. Посмотрите, сколько еще методов вы можете использовать в своем build.gradle. Документация по методам Gradle доступна на https://docs.gradle.org/current/dsl/index.html
В общем, если в build.gradle вам непонятно какое-то ключевое слово, открывайте интерфейс Project и ищите это ключевое слово там. Если не найдете, то, скорее всего, это название метода/свойства из подключенного вами плагина.
Про плагины Gradle. Зачем они нужны?
Можно, например, в build.gradle вручную на языке Groovyнаписать скрипт сборки jar, прописать директории, в которых ожидается исходный код, запустить команду компиляции, команду тестов и так далее.
Но, к счастью, все это уже написано за нас и упаковано в плагин java-library, который поставляется вместе с Gradle. (Плагин java-library расширяет возможности плагина java, наследует его возможности)
Чистый Gradle без плагинов позволяет запускать следующие задачи:
c:\doit>gradlew tasks > Task :tasks ------------------------------------------------------------ Tasks runnable from root project 'doit' ------------------------------------------------------------ Build Setup tasks ----------------- init - Initializes a new Gradle build. wrapper - Generates Gradle wrapper files. Help tasks ---------- buildEnvironment - Displays all buildscript dependencies declared in root project 'doit'. dependencies - Displays all dependencies declared in root project 'doit'. dependencyInsight - Displays the insight into a specific dependency in root project 'doit'. help - Displays a help message. javaToolchains - Displays the detected java toolchains. outgoingVariants - Displays the outgoing variants of root project 'doit'. projects - Displays the sub-projects of root project 'doit'. properties - Displays the properties of root project 'doit'. resolvableConfigurations - Displays the configurations that can be resolved in root project 'doit'. tasks - Displays the tasks runnable from root project 'doit'. To see all tasks and more detail, run gradlew tasks --all To see more detail about a task, run gradlew help --task <task> BUILD SUCCESSFUL in 1s 1 actionable task: 1 executed
Давайте подключим плагин java-library в наш проект: в самом начале build.gradle пропишем:
plugins { id('java-library') }
После подключения плагина появились новые таски для работы с проектом:
assemble - Assembles the outputs of this project. build - Assembles and tests this project. buildDependents - Assembles and tests this project and all projects that depend on it. buildNeeded - Assembles and tests this project and all projects it depends on. check - Runs all checks. classes - Assembles main classes. clean - Deletes the build directory. compileJava - Compiles main Java source. compileTestJava - Compiles test Java source. jar - Assembles a jar archive containing the main classes. javadoc - Generates Javadoc API documentation for the main source code. processResources - Processes main resources. processTestResources - Processes test resources. test - Runs the test suite. testClasses - Assembles test classes.
Итак, подключили плагин. А что такое плагин - это класс, реализующий интерфейс Plugin<Project>. Пример плагина HelloPlugin:
class HelloPlugin implements Plugin<Project> { void apply(Project project) { project.task('hello') { doLast { println 'Hello from the HelloPlugin' } } } }
У объекта Project появился новый метод/task hello. Точно так же плагин Java-library добавляет новые методы/таски и многое другое (в том числе и соглашения, например, что исходный код ищется по пути src/main/java).
Смотрите документацию по Java-library на странице https://docs.gradle.org/current/userguide/building_java_projects.html и https://docs.gradle.org/current/userguide/java_library_plugin.html
Плагины Java и Java-library немного отличаются. Второй плагин наследует первый и добавляет, например к implementation() новый метод api().
Теперь вы можете указать в подпроекте implementation("org.apache.commons:commons-lang3:3.5"), если ни один тип или метод из commons-lang не станет частью публичного API.
Теперь, если версия commons-lang изменится на 3.6, то подпроекты, зависимые от текущего подпроекта, не будут перекомпилироваться.
И наоборот для зависимости в api().
Все это ускоряет сборку на больших проектах.
Пример!
Пришла пора создать маленький Java проект из одного класса, выводящего в консоль стандартное Hello world.
Очистим рабочую C:\doit от старых файлов. Запустим в командной строке C:\tmp\bin\gradle init, которая добавит Gradle Wrapper, а так же создаст build.gradle.
В C:\doit появился gradle wrapper.
Осталось добавить Java класс в C:\doit\src\main\java.
Класс HelloWorld:
class HelloWorld { public static void main(String[] args) { System.out.println("Hello world!"); } }
И подключить плагин java-library в build.gradle, как делали выше.
plugins { id('java-library') }
Неплохо, уже можно и собрать наше маленькое приложение. Вспомним про документацию к Java-library https://docs.gradle.org/current/userguide/building_java_projects.html и https://docs.gradle.org/current/userguide/java_library_plugin.html или https://docs.gradle.org/current/dsl/. Поищем что-то по слову jar. Найдем таск jar.
jar - Собирает jar-архив с main классом.
Запускаем:
C:\doit>.\gradlew jar
Готово - появился C:\doit\build\libs\doit.jar, который можем запустить в командной строке через C:\doit>java -cp "C:\doit\build\libs\doit.jar" HelloWorld
Приходится указывать название класса при запуске jar'ника. Можно переместить название класса в файл манифеста MANIFEST.MF, согласно требованиям Java. Для этого откроем страницу building_java_projects или org.gradle.api.tasks.bundling.Jar и поищем по слову manifest. Находим пример:
jar { manifest { attributes("Implementation-Title": "Gradle", "Implementation-Version": archiveVersion) } }
Для запуска jar файла из командной строки без указания класса manifest должен содержать строку:
Main-Class: HelloWorld
Добавим в build.gradle:
jar { manifest { attributes 'Main-Class': 'HelloWorld' //или равнозначно //attributes('Main-Class': 'HelloWorld') } }
Почему такая странная запись через двоеточие? Так представлен элемент HashMap в Groovy, как параметр метода https://docs.gradle.org/current/javadoc/org/gradle/api/java/archives/Manifest.html
Прочтите The Groovy Development Kit https://www.groovy-lang.org/groovy-dev-kit.html
c:\doit>.\gradlew jar c:\doit>java -jar build\libs\doit.jar Hello world!
Разобраться несложно. Главное - не копипастить, а проходить каждую строчку в чужих примерах по документации.
