Grunt 入门指南5：项目脚手架

Project Scaffolding 项目脚手架

grunt-init

Grunt-init 是一个用来生成项目的脚手架工具. 它将基于当前环境以及命令的问答结果创建完整的项目目录结构.实际生成的项目文件和内容依赖于所选择的模版以及问答结果.

Installation 安装

开始使用grunt-init之前，你需要全局安装grunt-init

npm install -g grunt-init

安装好后就可以在任意目录使用grunt-init命令.

Usage 使用

• 使用grunt-init --help可以得到程序帮助以及可用的模版列表.
• 使用grunt-init TEMPLATE可以基于指定的模版生成项目
• grunt-init /path/to/TEMPLATE 基于指定位置的模版生车项目

注意大多数模版都会在当前目录产生文件,所以请确认在新目录执行以确保不会覆盖你已有的文件.

Installing templates 安装模版

一旦你的模版安装到了~/.grunt-init/目录(windows下是%USERPROFILE%\.grunt-init\)下, 就可以直接通过grunt-init来使用.推荐使用git克隆模版到这个目录中.比如,安装grunt-init-jquery模版可以像这样:

git clone git@github.com:gruntjs/grunt-init-jquery.git ~/.grunt-init/jquery

注意,如果你克隆时修改了模版的目录名, 使用grunt-init的时候就要用修改后的目录名

下面的模版是由官方来维护的: * grunt-init-commonjs * grunt-init-gruntfile * grunt-init-gruntplugin * grunt-init-jquery * grunt-init-node

Custom templates 自定义模版

你可以创建和使用自定义模版,你的模版也要构建成前面所提及的结构.

一个叫my-template的示例模版会有如下的文件结构:

• my-template/template.js - 主模版文件.
• my-template/rename.json - 模版特殊的重命名规则,由模版处理.
• my-template/root/ - 目录中文件将被拷贝到目标路径.

假设这些文件存在于 /path/to/my-template, 使用命令grunt-init /path/to/my-template将会处理这个模版.多个不同名的模版可以存在于同个目录,就像内建的模版那样.

此外,如果你把自定义模版放到你的~/.grunt-init/目录中,就可以直接使用grunt-init my-template.

Copying files 拷贝文件

只要一个模版使用了init.fileToCopy和init.copyAndProcess方法,在初始化模版执行的时候,任何在root/子目录的文件都会被拷贝到当前目录中.

注意所有已经拷贝的文件将会被模版处理,任何{% %}模版会收集props数据再次处理,除非设置了noProgress属性. 请参考jquery template的例子.

Renaming or excluding template file 重命名或者排除模版文件

rename.json描述了sourcepath到destpath的重命名映射.sourcepath必须是一个相对于root/目录的需要拷贝的文件路径,但是destpath可以包含{% %}模版来描述目标路径.

如果destpath被指定为false,该文件将不会被拷贝,同样,srcpath也支持 glob 模式.

Specifying default prompt answers 指定默认的提示答案

每次初始化提示,都会有一个硬编码的默认值或者查看当前环境来尝试确定一个默认值. 如果你希望覆盖一个特定提示的默认值,你可以改~/.grunt-init/defaults.json(windows下为%USERPROFILE%\.grunt-init\defaults.json)文件.

例如,我的defaults.json看起来像这样,因为我想用一个比默认名字稍微不同的名字, 并且排除掉我的email地址,以及自动指定一个作者url.

{
  "author_name": "\"Cowboy\" Ben Alman",
  "author_email": "none",
  "author_url": "http://benalman.com/"
}

Defining an init template 定义init模版

exports.description

模版的摘要描述将会在用户执行grunt init或者grunt-init的时候显示在可用模版的模版名字的后面.

exports.description = descriptionString;

exports.notes

如果指定了这个可选项,这个可选的扩展描述将会出现的任何提示的后面.你可以用它来给用户解释命名惯例,哪些选项是可选的还是必须等你等.

exports.warnOn

如果这个可选项(但是推荐设置)的通配符模式或者模式数组匹配成功, Grunt将会终止并且提示用户可以通过--force选项来继续操作. 这在初始化模版时会覆盖已存在的同名文件时很有用.

exports.warnOn = 'Gruntfile.js';        // Warn on a Gruntfile.js file.
exports.warnOn = '*.js';            // Warn on any .js file.
exports.warnOn = '*';               // Warn on any non-dotfile or non-dotdir.
exports.warnOn = '.*';              // Warn on any dotfile or dotdir.
exports.warnOn = '{.*,*}';          // Warn on any file or dir (dot or non-dot).
exports.warnOn = '!*/**';           // Warn on any file (ignoring dirs).
exports.warnOn = '*.{png,gif,jpg}'; // Warn on any image file.

// This is another way of writing the last example.
exports.warnOn = ['*.png', '*.gif', '*.jpg'];

exports.template

exports属性们在这个函数之外被定义,而所有实际的初始化代码都在放在里面.三个参数会传入这个函数,grunt参数是一个grunt对象的引用,包含了所有grunt的方法和库.init参数是一个对象,包含了init模版的方法和属性.done参数是一个函数,在初始化模版完成之后必须调用.

exports.template = function(grunt, init, done) {
  // See the "Inside an init template" section.
  //里面的内容，参考 “初始化模版的内部”
};

Inside an init template 在init模版的内部

init.addLicenseFiles

为files对象添加一个适当的许可

var files = {};
var licenses = ['MIT'];
init.addLicenseFiles(files, licenses);
// files === {'LICENSE-MIT': 'licenses/LICENSE-MIT'}

init.availableLicenses

返回一个可用许可的数组

var licenses = init.availableLicenses();
// licenses === [ 'Apache-2.0', 'GPL-2.0', 'MIT', 'MPL-2.0' ]

init.copy

拷贝文件，你可以给定一个相对或者绝对的源文件路径，和一个可选的相对的目标路径，以及一个可选的回调来文件内容.

init.copy(srcpath[, destpath], options)

init.copyAndProcess

迭代所有的传递进来的文件,把源文件拷贝到目标路径, 并处理文件内容.

init.copyAndProcess(files, props[, options])

init.defaults

来自defaults.json的用户指定的默认初始值

init.defaults

init.destpath

返回目标地址的绝对路径

init.destpath()

init.expand

等同于 grunt.file.expand

返回一个去重的数组, 数组里是所有匹配了给定的通配符的文件或者目录. 这个方法同样接受逗号分号的通配符或者通配符组成的数组. 模式开始于!的将会排除出返回的数组. 模式会按提供的数序处理,所以(使用多个通配符时)包含和排除的顺序很重要.

init.expand([options, ] patterns)

init.filesToCopy

返回一个对象,对象包含了所有拷贝到相对和绝对路径的,改名(或者省略的)符合rename.json(如果存在的话)规则的文件.

var files = init.filesToCopy(props);
/* files === { '.gitignore': 'template/root/.gitignore',
  '.jshintrc': 'template/root/.jshintrc',
  'Gruntfile.js': 'template/root/Gruntfile.js',
  'README.md': 'template/root/README.md',
  'test/test_test.js': 'template/root/test/name_test.js' } */

init.getFile

获取一个独立任务的文件路径

init.getFile(filepath[, ...])

init.getTemplates

返回一个包含所有可用的模版的对象.

init.getTemplates()

init.initSearchDirs

初始化目录并搜索可用模版.template是模版的地址. 同样包含了~/.grunt-init/和grunt-init的初始化任务核心.(这段特么的不会翻译了！)

init.initSearchDirs([filename])

init.process

启动一个进程来开始提示.

init.process(options, prompts, done)

init.process({}, [
  // Prompt for these values
  init.prompt('name'),
  init.prompt('description'),
  init.prompt('version')
], function(err, props) {
  // All finished, do something with the properties
});

init.prompt

为用户展示一个带有默认值的提示

init.prompt(name[, default])

init.prompts

返回一个所有提示的对象

var prompts = init.prompts;

init.readDefaults

读入来自task文件(如果存在)的默认JSON, 合并他们到一个数据对象.

init.readDefaults(filepath[, ...])

init.renames

模版的重命名规则

var renames = init.renames;
// renames === { 'test/name_test.js': 'test/{%= name %}_test.js' }

init.searchDirs

返回一个模版的搜索路径数组

var dirs = init.searchDirs;
/* dirs === [ '/Users/shama/.grunt-init',
  '/usr/local/lib/node_modules/grunt-init/templates' ] */

init.srcpath

根据文件名搜索初始化模版路径,并且返回一个绝对路径

init.srcpath(filepath[, ...])

init.userDir

返回用户的模版绝对路径

var dir = init.userDir();
// dir === '/Users/shama/.grunt-init'

init.writePackageJSON

保存一个package.json到目标目录.callback回调可以用来处理(package.json中的)添加/删除等等操作.

init.writePackageJSON(filename, props[, callback])

Built-in prompts 内建提示

author_email

package.json里用的作者email. 将会寻找用户的git配置提供一个默认值

author_name

package.json和版权声明里使用的用户全名.将会寻找用户的git配置提供默认值

author_url

package.json中使用的作者的网站的公开url

bin

一个项目根目录的相对路径指向cli的脚本

bugs

项目的问题跟踪的url.默认值会使用github的issue tracker.

description

项目描述,用在package.json以及README文件中

grunt_version

项目需要的Grunt的有效版本范围.

homepage

项目的主页君. 默认会使用github仓库地址

jquery_version

如果是个jQuery的项目, 这个值用来描述需要的jQuery版本. 必须是一个有效语法的版本范围描述符.

licenses

项目的开源许可. 多个许可用空格分开. 内建的许可有: MIT,MPL-2.0,'GPL-2.0,和Apache-2.0.默认使用MIT`. 添加自定义 的许可可以使用 init.addLicenseFiles.

main

项目主入口,默认使用lib目录中使用项目名称的文件.

name

项目的名称. 会大量的在项目模版中使用.默认使用当前工作目录的名字.

node_version

项目需要的nodejs的版本. 必须是一个有效语法的版本范围描述符.

npm_test

运行你项目测试的命令. 默认使用 grunt.

repository

项目的git仓库. 默认会猜测github的url

title

一个易读的项目名称.默认使用真实的项目名称.

version

项目的版本.默认使用一个有效语法版本,0.1.0.