Обновление с версии 0.3 до 0.4

Обратите внимание, что даже если вы знакомы с grunt, будет полезно ознакомиться с новым руководством Начало работы.

Grunt теперь разделен на три части: grunt, grunt-cli и grunt-init.

1. Модуль npm grunt должен быть установлен локально в вашем проекте. Он содержит код и логику для выполнения задач, загрузки плагинов и т. д.
2. Модуль npm grunt-cli должен быть установлен глобально. Он добавляет команду grunt в ваш PATH, так что вы можете её выполнить из любой точки. Сам по себе он ничего не делает; его задача — загружать и выполнять Grunt, который был установлен локально в вашем проекте, независимо от версии. Для получения дополнительной информации о том, почему это было изменено, пожалуйста, прочтите npm 1.0: Глобальная против локальной установки.
3. Задача init была разделена на свой собственный модуль npm, grunt-init. Она должна быть установлена глобально с помощью npm install -g grunt-init и запущена с помощью команды grunt-init. В ближайшие месяцы Yeoman полностью заменит grunt-init. Более подробную информацию см. на странице проекта grunt-init.

Примечания к Grunt 0.3

Если вы обновляете с Grunt 0.3, убедитесь, что вы удалили глобальный grunt:

npm uninstall -g grunt

Обратите внимание, что для 0.3.x имена плагинов и параметры конфигурации задач могут отличаться от показанных в разделе "Файл Gruntfile".

Этот файл назывался grunt.js для версий Grunt 0.3.x.

Существующие задачи и плагины

Все плагины grunt-contrib-* серии совместимы с Grunt 0.4. Однако маловероятно, что плагины сторонних разработчиков, написанные для Grunt 0.3, будут продолжать работать с 0.4 до тех пор, пока не будут обновлены. Мы активно работаем с авторами плагинов, чтобы это произошло как можно скорее.

Будущий выпуск Grunt будет сосредоточен на отвязке архитектуры grunt, чтобы плагины не затрагивались будущими обновлениями.

Требования

• Grunt теперь требует версию Node.js >= 0.8.0

Файл Gruntfile

• Файл "Gruntfile" изменился с grunt.js на Gruntfile.js.
• CoffeeScript поддерживается в вашем проекте Gruntfile.coffee Gruntfile или файлах задач *.coffee (транспиляция в JS происходит автоматически).

Дополнительную информацию см. в разделе "Файл Gruntfile" руководства Начало работы.

Основные задачи теперь являются плагинами Grunt

Восемь основных задач, включенных в Grunt 0.3, теперь являются отдельными плагинами Grunt. Каждый из них является отдельным модулем npm, который необходимо установить как плагин в соответствии с разделом "Загрузка плагинов и задач Grunt" руководства Начало работы.

• concat → плагин grunt-contrib-concat
• init → автономная утилита grunt-init
• lint → плагин grunt-contrib-jshint
• min → плагин grunt-contrib-uglify
• qunit → плагин grunt-contrib-qunit
• server → плагин grunt-contrib-connect
• test → плагин grunt-contrib-nodeunit
• watch → плагин grunt-contrib-watch

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

Настройка

Формат конфигурации для задач Grunt 0.4 был стандартизирован и значительно улучшен. Дополнительную информацию см. в руководстве Настройка задач, а также в документации отдельных плагинов.

• Шаблоны файлов globbing (с подстановкой) теперь могут быть отрицательными, чтобы исключить совпадающие файлы.
• Задачи теперь поддерживают стандартный объект options.
• Задачи теперь поддерживают стандартный объект files.

Шаблоны строк <% %> style, указанные в качестве данных конфигурации внутри Gruntfile, автоматически расширяются, см. документацию grunt.template для получения дополнительной информации.

Директивы были удалены, но их функциональность сохранена. Эти замены могут быть сделаны:

• '<config:prop.subprop>' → '<%= prop.subprop %>'
• '<json:file.json>' → grunt.file.readJSON('file.json')
• '<file_template:file.js>' → grunt.template.process(grunt.file.read('file.js'))

Вместо указания баннера в списке файлов с '<banner>' или '<banner:prop.subprop>', плагины grunt-contrib-concat и grunt-contrib-uglify каждый имеют опцию banner.

Вместо удаления баннеров из файлов индивидуально с '<file_strip_banner:file.js>', плагины grunt-contrib-concat и grunt-contrib-uglify каждый имеют опцию удаления/сохранения баннеров.

Изменения в задаче псевдонима

При указании задачи-псевдонима список задач для выполнения теперь должен быть задан в виде массива.

// v0.3.x (old format)
grunt.registerTask('default', 'jshint nodeunit concat');
// v0.4.x (new format)
grunt.registerTask('default', ['jshint', 'nodeunit', 'concat']);

Аргументы задач теперь могут содержать пробелы

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

grunt my-task:argument-without-spaces "other-task:argument with spaces"

Кодировки символов

Метод file.defaultEncoding был добавлен для нормализации кодировок символов, и все методы grunt.file были обновлены для поддержки указанной кодировки.

Помощники

Система помощников Grunt была удалена в пользу node require. Для краткого примера того, как обмениваться функциональностью между плагинами Grunt, см. grunt-lib-legacyhelpers. Авторам плагинов рекомендуется обновить свои плагины.

API

API Grunt претерпел существенные изменения с версии 0.3 до 0.4.

• grunt
  • Удалены методы grunt.registerHelper и grunt.renameHelper.
• grunt.config
  • Метод config.get изменён на автоматическое рекурсивное раскрытие шаблонов <% %>.
  • Добавлен метод config.getRaw, который извлекает исходные (нераскрывленные) данные конфигурации.
  • Метод config.process изменён на обработку значения так, как если бы оно было извлечено из конфигурации, рекурсивно раскрывая шаблоны. Этот метод вызывается внутри config.get, но не внутри config.getRaw.
• grunt.event добавлен для возможности отправки событий задачами.
• grunt.fail
  • Не будет издавать звуковой сигнал, если указан параметр --no-color.
  • Добавлена таблица соответствия кодов завершения fail.code.
  • Удален метод fail.warnAlternate.
• grunt.file
  • Задачи больше не загружаются автоматически из каталога ~/.grunt/tasks/ (установите их локально в свой проект!).
  • Добавлен метод file.defaultEncoding для нормализации кодировки символов во всех методах grunt.file.
  • Добавлен метод file.delete.
  • Добавлены методы для проверки, относительно самообъяснительные: file.exists, file.isDir, file.isFile, file.isLink, file.isPathCwd, file.isPathInCwd, file.doesPathContain, file.arePathsEquivalent.
  • Добавлены методы file.match и file.isMatch для сопоставления шаблонов с подстановочными знаками с путями к файлам.
  • Добавлен метод file.expandMapping для использования в генерации соответствий файлов 1:1 src-dest.
  • Добавлен метод file.readYAML.
  • Изменён метод file.findup на использование модуля findup-sync.
  • Изменён метод file.glob на использование модуля glob.
  • Добавлен метод file.minimatch, который предоставляет модуль minimatch.
  • Удален метод file.userDir (перемещен в grunt-init).
  • Удален метод file.clearRequireCache.
  • Удалены методы file.expandFiles и file.expandDirs , используйте параметр filter метода file.expand вместо них.
  • Удален метод file.expandFileURLs. Не указывайте URL, где должны быть указаны файлы (например, задача qunit теперь позволяет использовать параметр urls).
• grunt.task
  • Задачи, зарегистрированные с помощью task.registerTask и task.registerMultiTask, получают метод this.options.
  • Добавлен метод task.normalizeMultiTaskFiles для нормализации объектов files многозадачных задач в свойство this.file.
  • Удалены методы task.registerHelper и task.renameHelper.
  • Удалено свойство task.searchDirs.
  • Удалены методы task.expand task.expandDirs task.expandFiles task.getFile task.readDefaults (перемещены в grunt-init).
• grunt.package отражает метаданные, хранящиеся в package.json grunt.
• grunt.version — текущая версия Grunt в виде строки.
• grunt.template
  • Добавлен метод template.addDelimiters для добавления новых разделителей шаблонов.
  • Добавлен метод template.setDelimiters для выбора разделителей шаблонов.
  • Разделители шаблонов init и user были удалены, но вы можете добавить их обратно, если нужно, с помощью template.addDelimiters (grunt-init использует это для активации разделителей шаблонов {% %}).
• grunt.util заменяет теперь удаленный grunt.utils.
  • Изменено util._ на использование Lo-Dash
  • Добавлен метод util.callbackify.
  • Изменён метод util.spawn для более корректного поведения и передачи более последовательных аргументов в обратный вызов.

Авторы задач/плагинов

Авторы плагинов, пожалуйста, чётко укажите в README вашего репозитория, какие версии вашего плагина Grunt несовместимы с Grunt 0.3.

Задачи

• Многозадачные задачи
  • Несколько соответствий файлов src-dest теперь могут быть указаны для каждой цели в объекте files (это необязательно).
• this.files / grunt.task.current.files
  • Свойство this.files — это массив объектов соответствий файлов src-dest, по которым нужно итерироваться в вашей многозадачной задаче. Это всегда массив, и вы всегда должны итерироваться по нему, даже если наиболее распространённый случай — это указание одного файла.
  • Каждый объект соответствия файла src-dest имеет свойство src и dest (и, возможно, другие, в зависимости от того, что указал пользователь). Свойство src уже раскрыто из любого шаблона подстановки, который мог указать пользователь.
• this.filesSrc / grunt.task.current.filesSrc
  • Свойство this.filesSrc — это уменьшенный, уникальный массив всех файлов, соответствующих всем указанным свойствам src. Полезно для задач только для чтения.
• this.options / grunt.task.current.options
  • В задачах может использоваться метод this.options для нормализации параметров. Внутри задачи вы можете указать параметры по умолчанию, например: var options = this.options({option: 'defaultvalue', ...});

Плагины

• Создан обновлённый шаблон gruntplugin для плагинов, совместимых с Grunt 0.4, и он доступен в автономном плагине grunt-init.

Устранение неполадок

• Если вы ранее установили тестовую версию Grunt 0.4 или плагины grunt-contrib, сначала очистите кеш npm с помощью npm cache clean для обеспечения того, что вы загружаете последнюю версию Grunt и плагинов grunt-contrib.