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.
