Глава 4. Использование командной строки Gradle.

Эта глава представляет основы командной строки Gradle. Вы можете запустить сборку используя команду gradle, которую уже видели в действии в предыдущих главах.

4.1. Выполнение составных задач.

Вы можете выполнять составные задачи в одиночной сборке просто перечисля все задачи в командной строке. Например, команда gradle compile test выполнит задачи compile и test. Gradle выполнит их в том порядке, в котором они были перечислены в командной строке, также, будут выполнены все зависимости для каждой из задач. Каждая задача выполняется только один раз, не зависимо от того, как она была включена в сборку: были ли она определена в командной строке, или как зависимость для другой задачи, или и то, и другое. Давайте посмотрим на пример.

Ниже определены 4 задачи. Обе, dist и test, зависят от задачи compile. В результате запуска gradle dist test для этого сборочного скрипта, задача compile выполнится только единожды.

Рисунок 4.1. Зависимость задач
Рисунок 4.1. Зависимость задач
Пример 4.1. Выполнение составных задач

build.gradle

task compile {
    doLast {
        println 'compiling source'
    }
}

task compileTest(dependsOn: compile) {
    doLast {
        println 'compiling unit tests'
    }
}

task test(dependsOn: [compile, compileTest]) {
    doLast {
        println 'running unit tests'
    }
}

task dist(dependsOn: [compile, test]) {
    doLast {
        println 'building the distribution'
    }
}
	  

Вывод выполнения gradle dist test

> gradle dist test
:compile
compiling source
:compileTest
compiling unit tests
:test
running unit tests
:dist
building the distribution

BUILD SUCCESSFUL

Total time: 1 secs
	  

Каждая задача выполнилась только один раз, так что gradle test test, то же самое, что и gradle test.

4.2. Исключение задач

Вы можете исключить задачу из выполнения, используя -x опцию командной строки и указывая имя для исключения. Попробуем на примере сборочного скрипта, указанного выше.

Пример 4.2. Исключение задач

Вывод выполнения gradle dist -x test

> gradle dist -x test
:compile
compiling source
:dist
building the distribution

BUILD SUCCESSFUL

Total time: 1 secs
	  

Как вы можете видеть из этого вывода, задача test не выполнялась, хотя от нее и зависит задача dist. Также обратите внимание, что зависимости задачи test, такие как compileTest, тоже не выполнялись. Другие зависимости test, которые требуются для другой задачи, такой как compile, были выполнены.

4.3. Продолжение сборки при сбоях

По умолчанию, Gradle прерывает выполение сборки, как только выполнение хотя бы одной задачи провалится. Благодаря такому поведению, сборка заканчивается скорее, но скрываются другие сбои, которым могли бы проявиться. Для того, чтобы обнаружить как можно больше сбоев за один раз, вы можете использовать опцию --continue.

При выполнении с опцией --continute, Gradle каждую задачу, для которой все зависимости выполнились без сбоев, вместо того, чтобы прерывать выполнение при первом сбое. Каждый встреченный сбой будет запротоколирован и выведен в отчете в конце сборки.

4.4. Сокращение имени задачи.

Вам не необходимости указывать полное имя задачи, когда вы определяете задачи для запуска в командной строке. Достаточно указать часть имени, которая уникально его определяет. Например, в образце сборки определенном выше, вы можете выполнить задачу dist запустив gradle di:

Пример 4.3. Сокращенное имя задачи

Вывод выполнения gradle di

> gradle di
:compile
compiling source
:compileTest
compiling unit tests
:test
running unit tests
:dist
building the distribution

BUILD SUCCESSFUL

Total time: 1 secs
	  

Вы также можете указать аббревиатуру каждого слова в имени задачи в стиле CamelCase. Например, чтобы выполнить задачу compileTest, запустите gradle compTest или даже gradle cT

Пример 4.4. Сокращенное имя задачи в стиле CamelCase

Вывод выполнения gradle cT

> gradle cT
:compile
compiling source
:compileTest
compiling unit tests

BUILD SUCCESSFUL

Total time: 1 secs
	  

Вы можете использовать сокращения совместно с опцией -x, которая исключает задачи из выполнения.

4.5. Выбор сборки для выполнения.

Когда вы запускаете команду gradle, она ищет файл сборки в текущей директории. Вы можете использовать опцию -b для выбора другого файла сборки. Если вы используете эту опцию, то файл settings.gradle не будет использоваться. Пример:

Пример 4.5. Выбор проекта, используя файл сборки

subdir/myproject.gradle

task hello {
    doLast {
        println "using build file '$buildFile.name' in '$buildFile.parentFile.name'."
    }
}
	  

Вывод команды gradle -q -b subdir/myproject.gradle hello

> gradle -q -b subdir/myproject.gradle hello
using build file 'myproject.gradle' in 'subdir'.
	  

В качестве альтернативы, вы можете использовать опцию -p для указания папки проекта. Для многопроектных скриптов, вы должны пользоваться опций -p, вместо -b.

Пример 4.6. Выбора проекта с использованием папки

Вывод команды gradle -q -p subdir hello

> gradle -q -p subdir hello
using build file 'build.gradle' in 'subdir'.
	  

4.6. Принудительный запуск задач.

Многие задачи, в особенности предоставляемые Gradle, поддерживают инкрементальные сборки. Такие типы задач могут определить нужно ли им запускаться на выполнение или нет, основываясь на изменения входных или выходных данных с момента их прошлого запуска. Вы без проблем можете определить задачи, которые участвуют в инкрементальной сборке, так как Gradle печатает UP-TO-DATE рядом с их именами во время выполнения сборки.

Иногда вам нужно заставить Gradle запустить все задачи, не взирая на проверку их состояния. В этом случае, просто используйте опцию --rerun-tasks. Ниже представлен пример запуска задачу с использованием опции и без нее:

Пример 4.7. Принудительный запуск задач

Вывод команды gradle doIt

> gradle doIt
:doIt UP-TO-DATE
	  

Вывод команды gradle --rerun-tasks doIt

> gradle --rerun-tasks doIt
:doIt
	  

Обратите внимание, что это заставит выполнится все необходимые задачи, не только те, которые вы указали в командной строке. Это похоже на выполнение команды clean, но без удаления сгенерированных сборкой файлов.

4.7 Получение информации о вашей сборке.

Gradle предоставляет несколько встроенных задач, которые показывают определенные детали вашей сборки. Они могут быть полезны для понимания структуры и зависимостей вашей сборки, а также для отладки проблем.

В дополнение к встроенным задачам описанным ниже, вы можете пользоваться плагином отчета проекта, чтобы добавить задачи в ваш проект, которые выдадут эти отчеты.

4.7.1. Вывод списка проектов.

Запуск gradle projects выдаст вам список подпроектов выбранного проекта, отображаемый с учетом иерархии. Ниже показан пример:

Пример 4.8. Получение информации о проектах.

Вывод команды gradle -q projects

> gradle -q projects

------------------------------------------------------------
Root project
------------------------------------------------------------

Root project 'projectReports'
+--- Project ':api' - The shared API for the application
\--- Project ':webapp' - The Web application implementation

To see a list of the tasks of a project, run gradle :tasks
For example, try running gradle :api:tasks
	  

Этот отчет показывает описание каждого проекта, если оно задано. Вы можете добавить описание для проекта, установив свойство description:

Пример 4.9. Добавление описания для проекта.

build.gradle

description = 'The shared API for the application'
	  

4.7.2. Вывод списка задач.

Запуск gradle tasks выдаст список главных задач выбранного проекта. Этот отчет показывает предопределенные задачи для проекта, если они есть, и описание для каждой задачи. Ниже пример отчета:

Пример 4.10. Получение информации о задачах.

Вывод команды gradle -q tasks

> gradle -q tasks

------------------------------------------------------------
All tasks runnable from root project
------------------------------------------------------------

Default tasks: dists

Build tasks
-----------
clean - Deletes the build directory (build)
dists - Builds the distribution
libs - Builds the JAR

Build Setup tasks
-----------------
init - Initializes a new Gradle build. [incubating]
wrapper - Generates Gradle wrapper files. [incubating]

Help tasks
----------
buildEnvironment - Displays all buildscript dependencies declared in root project 'projectReports'.
components - Displays the components produced by root project 'projectReports'. [incubating]
dependencies - Displays all dependencies declared in root project 'projectReports'.
dependencyInsight - Displays the insight into a specific dependency in root project 'projectReports'.
dependentComponents - Displays the dependent components of components in root project 'projectReports'. [incubating]
help - Displays a help message.
model - Displays the configuration model of root project 'projectReports'. [incubating]
projects - Displays the sub-projects of root project 'projectReports'.
properties - Displays the properties of root project 'projectReports'.
tasks - Displays the tasks runnable from root project 'projectReports' (some of the displayed tasks may belong to subprojects).

To see all tasks and more detail, run gradle tasks --all

To see more detail about a task, run gradle help --task 
	  

По умолчанию, этот отчет показывает только те задачи, которым назначена группа, так называемые видимые задачи. Вы можете установить свойство group для задачи, чтобы ей была назначена группа. Вы также можете установить свойство description, чтобы предоставить описание, которое будет включено в отчет

Пример 4.11. Изменение содержимого отчета задачи.

build.gradle

dists {
    description = 'Builds the distribution'
    group = 'build'
}
	  

Вы сможете получить больше информации в списке задач, если используете опцию --all. С этой опцией, задача отчета перечислит все задачи в проекте, включая те, которым не назначена группа, так называемые скрытые задачи. Пример:

Пример 4.12. Получение больше информации о задачах.

Вывод команды gradle -q tasks --all

> gradle -q tasks --all

------------------------------------------------------------
All tasks runnable from root project
------------------------------------------------------------

Default tasks: dists

Build tasks
-----------
clean - Deletes the build directory (build)
api:clean - Deletes the build directory (build)
webapp:clean - Deletes the build directory (build)
dists - Builds the distribution
api:libs - Builds the JAR
webapp:libs - Builds the JAR

Build Setup tasks
-----------------
init - Initializes a new Gradle build. [incubating]
wrapper - Generates Gradle wrapper files. [incubating]

Help tasks
----------
buildEnvironment - Displays all buildscript dependencies declared in root project 'projectReports'.
api:buildEnvironment - Displays all buildscript dependencies declared in project ':api'.
webapp:buildEnvironment - Displays all buildscript dependencies declared in project ':webapp'.
components - Displays the components produced by root project 'projectReports'. [incubating]
api:components - Displays the components produced by project ':api'. [incubating]
webapp:components - Displays the components produced by project ':webapp'. [incubating]
dependencies - Displays all dependencies declared in root project 'projectReports'.
api:dependencies - Displays all dependencies declared in project ':api'.
webapp:dependencies - Displays all dependencies declared in project ':webapp'.
dependencyInsight - Displays the insight into a specific dependency in root project 'projectReports'.
api:dependencyInsight - Displays the insight into a specific dependency in project ':api'.
webapp:dependencyInsight - Displays the insight into a specific dependency in project ':webapp'.
dependentComponents - Displays the dependent components of components in root project 'projectReports'. [incubating]
api:dependentComponents - Displays the dependent components of components in project ':api'. [incubating]
webapp:dependentComponents - Displays the dependent components of components in project ':webapp'. [incubating]
help - Displays a help message.
api:help - Displays a help message.
webapp:help - Displays a help message.
model - Displays the configuration model of root project 'projectReports'. [incubating]
api:model - Displays the configuration model of project ':api'. [incubating]
webapp:model - Displays the configuration model of project ':webapp'. [incubating]
projects - Displays the sub-projects of root project 'projectReports'.
api:projects - Displays the sub-projects of project ':api'.
webapp:projects - Displays the sub-projects of project ':webapp'.
properties - Displays the properties of root project 'projectReports'.
api:properties - Displays the properties of project ':api'.
webapp:properties - Displays the properties of project ':webapp'.
tasks - Displays the tasks runnable from root project 'projectReports' (some of the displayed tasks may belong to subprojects).
api:tasks - Displays the tasks runnable from project ':api'.
webapp:tasks - Displays the tasks runnable from project ':webapp'.

Other tasks
-----------
api:compile - Compiles the source files
webapp:compile - Compiles the source files
docs - Builds the documentation
	  

4.7.3. Вывод деталей об использовании задачи.

Запуск gradle help --task someTask выдаст детальную информацию о задаче или нескольких задачах с заданным именем в вашем многопроектной сборке. Ниже представлен пример детальной информации:

Пример 4.13. Получение детальной помощи о задачах.

Вывод команды gradle -q help --task libs

> gradle -q help --task libs
Detailed task information for libs

Paths
     :api:libs
     :webapp:libs

Type
     Task (org.gradle.api.Task)

Description
     Builds the JAR

Group
     build
	  

Эта информация содержит полный путь задачи, тип, допустимые опции командной строки и описание.

4.7.4. Вывод зависимостей проекта.

Запуск gradle dependencies выдаст список зависимостей выбранного проекта, разбитый по конфигурации. Для каждой конфигурации, прямые и переходящие зависимости показаны в виде дерева. Ниже пример отчета:

Пример 4.14. Получение информации о зависимостях.

Вывод команды gradle -q dependencies api:dependencies webapp:dependencies

> gradle -q dependencies api:dependencies webapp:dependencies

------------------------------------------------------------
Root project
------------------------------------------------------------

No configurations

------------------------------------------------------------
Project :api - The shared API for the application
------------------------------------------------------------

compile
\--- org.codehaus.groovy:groovy-all:2.4.7

testCompile
\--- junit:junit:4.12
     \--- org.hamcrest:hamcrest-core:1.3

------------------------------------------------------------
Project :webapp - The Web application implementation
------------------------------------------------------------

compile
+--- project :api
|    \--- org.codehaus.groovy:groovy-all:2.4.7
\--- commons-io:commons-io:1.2

testCompile
No dependencies
	  

Отчет по зависимостям может быть очень большим, так что лучше будет его ограничить определенной конфигурацией. Этого можно достичь с помощью необязательного параметра --configuration:

Пример 4.15. Фильтрация отчета по конфигурации.

Вывод команды gradle -q api:dependencies --configuration testCompile

> gradle -q api:dependencies --configuration testCompile

------------------------------------------------------------
Project :api - The shared API for the application
------------------------------------------------------------

testCompile
\--- junit:junit:4.12
     \--- org.hamcrest:hamcrest-core:1.3
	  

4.7.5. Вывод списка зависимостей скрипта сборки.

Запуск gradle buildEnvironment покажет зависимости скрипта выбранного проекта, аналогично тому, как команда gradle dependencies выводит зависимости собираемого программного обеспечения.

4.7.6. Взгляд внутрь определенной зависимости.

Запуск gradle dependencyInsight позволит заглянуть внутрь определенной зависимости (или зависимостей), которая соответствует вводу. Ниже пример отчета:

Пример 4.16. Взгляд внутрь определенной зависимости.

Вывод команды gradle -q webapp:dependencyInsight --dependency groovy --configuration compile

> gradle -q webapp:dependencyInsight --dependency groovy --configuration compile
org.codehaus.groovy:groovy-all:2.4.7
\--- project :api
     \--- compile
	  

Эта задача чрезвычайно полезна для исследования разрешения зависимостей, выяснения откуда пришла эта зависимость и почему были выбраны определенные версии. Чтобы узнать больше информации, пожалуйста, взгляните на класс DependencyInsightReportTask в документации по API.

Встроенная задача dependencyInsight - часть группы задача 'Help' (Помощь). Для выполнения задачу необходимо передать зависимости и конфигурацию. Отчет ищет зависимости, которые совпадают со спецификацией зависимости в указанной конфигурации. Если применены плагины, связанные с Java, то в задачу dependencyInsight передается конфигурация 'compile', потому что обычно зависимости компиляции - это то, в чем вы заинтересованы. Вы должны указывать зависимость, которая вас интересует, с помощью опции командной строки '--dependency'. Если вас не устраивает конфигурация, использующаяся по умолчанию, то вы можете выбрать другую с помощью опции '--configuration'. Чтобы узнать больше информации, пожалуйста, взгляните на класс DependencyInsightReportTask в документации по API.

4.7.7. Вывод списка свойств проекта.

Запуск gradle properties выведет список свойств выбранного проекта. Ниже вырезка из вывода:

Пример 4.17. Информация о свойствах.

Вывод команды gradle -q api:properties

> gradle -q api:properties

------------------------------------------------------------
Project :api - The shared API for the application
------------------------------------------------------------

allprojects: [project ':api']
ant: org.gradle.api.internal.project.DefaultAntBuilder@12345
antBuilderFactory: org.gradle.api.internal.project.DefaultAntBuilderFactory@12345
artifacts: org.gradle.api.internal.artifacts.dsl.DefaultArtifactHandler_Decorated@12345
asDynamicObject: DynamicObject for project ':api'
baseClassLoaderScope: org.gradle.api.internal.initialization.DefaultClassLoaderScope@12345
buildDir: /home/user/gradle/samples/userguide/tutorial/projectReports/api/build
buildFile: /home/user/gradle/samples/userguide/tutorial/projectReports/api/build.gradle
	  

4.7.8. Профилирование сборки.

Опция командной строки --profile записывает полезную информацию о времени, во время работы сборки и сохраняет отчет в папку build/reports/profile. Название отчета будет состоять из времени запуска сборки.

Этот отчет выводит список суммарных времен и деталей для фазы конфигурации и выполнения задачи. Времена для конфигурации и выполнения задачи отсортированы от самого большего к самому меньшему. Результат выполнение задачи также показывает были ли пропущены (и причину) какие-либо задачи или не пропущенные задачи не работали.

Сборки, которые используют папку buildSrc сгенерируют отчет о профилировании для buildSrc в папке buildSrc/build.

Рисунок 4.2. Профилирование задач.

4.8. Холостой запуск.

Иногда вас интересует в каком порядке выполняются задачи указанные в командной строке, но вы не хотите, чтобы они выполнялись. Для этого вы можете использовать опцию -m. Например, если вы запустите команду "gradle -m clean compile", вы увидите все задачи, которые выполняются как часть задач clean и compile. Это дополнение к задаче tasks, которая отображает задачи доступные для запуска.

4.9. Резюме.

В этой главе вы увидели некоторые вещи, которые можете делать с помощью командной строки. Вы можете узнать больше о команде gradle в Приложении Г. Командная строка Gradle.