Глава 5. Gradle Wrapper.

Для большинства инструментов требуется установка прежде, чем вы сможете их использовать. Если установка проста, вы можете подумать, что это прекрасно. Но это может быть тяжким бременем для пользователей сборки. Настолько же важно, установит ли пользователь правильную версию инструмента? Что, если он собирает устаревшей версией программного обеспечения?

Gradle Wrapper (далее просто Wrapper) решает обе этих проблемы и является предпочтительным путем запуска сборки.

5.1. Выполнение сборки с помощью Wrapper'а.

Если у проекта Gradle настроен Wrapper (и создатели Gradle рекомендуют настраивать его для все проектов), вы можете запустить сборку используя одну из следующих команд из корня проекта:

  • ./gradlew <задача> (на юниксоподобных платформах, таких как Linux и Mac OS x)
  • gradlew <задача> (на Windows используя gradlew.bat файл командной строки)

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

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

Для полноты изложения и чтобы убедиться, что вы не удалите важные файлы, ниже приведен список файлов и папок в проекте Gradle, которые составляют Wrapper:

  • gradlew (скрипт командной строки юникс)
  • gradlew.bat (командый файл Windows)
  • gradle/wrapper/gradle-wrapper.jar (Wrapper JAR)
  • gradle/wrapper/gradle-wrapper.properties (свойства Wrapper'а)

Если вы гадаете, где хранится дистрибутивы Gradle, их можно найти в вашей домашней папке в подпапке $USER_HOME/.gradle/wrapper/dists.

5.2. Добавление Wrapper'а в проект.

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

Для установки Wrapper'а в ваш проект, используйте задачу wrapper. (Эта задача всегда доступна, даже если вы не добавляли его в вашу сборку). Для указания версии Gradle, используйте --gradle-version в командной строке. По умолчанию, Wrapper берет дистрибутив bin. Это самый маленький дистрибутив Gradle. Некоторые инструменты, такие как Android Studio или Intellij IDEA, предоставляют дополнительную контекстную информацию, когда работают с дистрибутивом all. Для выбора отличного типа дистрибутива Gradle существует опция --distribution-type. Еще вы можете установить URL, с которого загружать Gradle, посредством --gradle-distribution-url. Если ни версия, ни URL дистрибутива не были указаны, Wrapper будет настроен для использования версии, в которой была выполнена задача wrapper. Если вы запустите wrapper с Gradle 2.4, то конфигурация по умолчанию будет использовать версию 2.4.

Пример 5.1. Запуск задачи Wrapper

Вывод выполнения gradle wrapper --gradle-version 2.0

> gradle wrapper --gradle-version 2.0
:wrapper

BUILD SUCCESSFUL

Total time: 1 secs
	  

В дальнейшем, Wrapper может быть модифицирован добавлением и настройкой задачи Wrapper в ваш сборочный скрипт и выполнением его.

Пример 5.2. Задача Wrapper

build.gradle

task wrapper(type: Wrapper) {
    gradleVersion = '2.0'
}
	  

После выполнения вы найдете следующие новый или измененные файлы в папке вашего проекта (в случае использования конфигурации задачу по умолчанию).

Пример 5.3. Файлы сгенерированные Wrapper'ом

Разметка сборки

simple/
  gradlew
  gradlew.bat
  gradle/wrapper/
    gradle-wrapper.jar
    gradle-wrapper.properties
	  

Все эти файлы должны быть добавлены в систему контроля версий. Но это необходимо сделать единожды. После добавления этих файлов в проект, он должен собираться используя добавленную команду gradlew. Она может быть использована таким же образом, как и команда gradle.

Если вы хотите переключиться на новую версию Gradle, нет необходимости снова запускать задачу wrapper. Достаточно всего лишь изменить соответствующую строчку в файле gradle-wrapper.properties, но если вы хотите получить преимущества новой функциональности в Gradle Wrapper, тогда надо пересоздать его файлы.

5.3. Конфигурация.

Когда вы запускаете Gradle командой gradlew, Wrapper проверяет доступен ли ему дистрибутив. Если доступен, он передает аргументы, поданные на вход gradlew, команде gradle из дистрибутива. Если дистрибутив не найден, Wrapper предварительно его скачает.

Когда вы настраиваете задачу wrapper, вы можете указать версию Gradle, которую желаете использовать. Команда gradlew загрузит соответствующий дистрибутив из хранилища Gradle. В качестве альтернативы, вы можете указать URL загрузки дистрибутива Gradle. Команда gradlew использует этот URL для загрузки дистрибутива. Если вы не указали ни версию Gradle, ни URL для загрузки, то команда gradlew загрузит ту версию, которая в помощью которой были с сгенерированы файлы Wrapper'а.

Подробные сведения о настройке Wrapper'а ищите в классе Wrapper в документации по API.

Если вы не желаете, чтобы что-то загружалось при сборке через gradlew, просто добавьте дистрибутив Gradle в zip-архиве в вашу систему контроля версий в местоположение, указанное в конфигурации Wrapper'а. Относительный URL тоже поддерживается - вы можете указать файл дистрибутива относительно местоположения файла gradle-wrapper.properties

Если вы собираете проект с использованием Wrapper'а, то любой существующий дистрибутив Gradle, установленный на машине, будет проигнорирован.

5.4. Загрузка проверенного дистрибутива Gradle.

Gradle Wrapper может загружать дистрибутивы Gradle с серверов, используя Базовую Аутентификацию HTTP. Это дает вам возможность разместить дистрибутив Gradle на закрытом защищенном сервере. Вы можете указать имя пользователя и пароль двумя разными способами, в зависимости от ситуации: как системные свойства или включив их напрямую в свойство distributionUrl. Регистрационная информация указанная в системных свойствах приоритетнее включенной в distributionUlr.

Настроить системные свойства можно в файле .gradle/gradle.properties в домашней папке пользователя или с помощью других средств, смотрите Секцию 12.1 "Настройка окружения сборки с помощью gradle.properties".

Пример 5.4. Указание регистрационных данных для Базовой Аутентификации HTTP с помощью системных свойств

gradle.properties

systemProp.gradle.wrapperUser=username
systemProp.gradle.wrapperPassword=password
	  

Включение регистрационных данных в distributionUrl в файле gradle/wrapper/gradle-wrapper.properties тоже работает. Пожалуйста, обратите внимание, что этот файл будет добавлен в вашу систему контроля версий. Общие регистрационные данные включенные в distributionUrl должны быть использованы только в окружении, которое находится под вашим контролем.

Пример 5.5. Указание регистрационных данных для Базовой Аутентификации HTTP в distributionUrl

gradle-wrapper.properties

distributionUrl=https://username:password@somehost/path/to/gradle-distribution.zip
	  

Это может быть использовано в связке с прокси, аутентифицированной или нет. Чтобы узнать более подробно о настройке Wrapper'а для использования прокси, смотрите Секцию 12.3 "Доступ к веб через прокси"

5.5. Проверка загруженных дистрибутивов Gradle.

Gradle Wrapper допускает проверку загруженного дистрибутива через сравнение хэш-суммы SHA-256. Благодаря такой проверке, увеличивается защищенность от направленных атак, препятствуя человеку-посредине подделать загруженный дистрибутив.

Для включения этой функции, для начала вы можете подсчитать хэш SHA-256 уже известного дистрибутива Gradle. Для генерации хэша на Linux, OSX или Windows (через Cygwin) воспользуйтесь командой shasum.

Пример 5.6. Генерация хэша SHA-256
> shasum -a 256 gradle-2.4-all.zip
371cb9fbebbe9880d147f59bab36d61eee122854ef8c9ee1ecf12b82368bcf10  gradle-2.4-all.zip
	  

Добавьте полученную хэш-сумму в файл gradle-wrapper.properties в свойство distributionSha256Sum.

Пример 5.7. Настройка проверки контрольной суммы SHA-256

gradle-wrapper.properties

distributionSha256Sum=371cb9fbebbe9880d147f59bab36d61eee122854ef8c9ee1ecf12b82368bcf10
	  

5.6. Разрешения для файлов на Unix.

Задача Wrapper добавляет соответствующие файловые разрешения для *NIX команды gradlew. Subversion сохраняет эти разрешения. Создатели Gradle не уверены в том, как с этим работают другие системы контроля версий. Что всегда сработает, так это выполнение "sh gradlew" в терминале.