grunt-init是一个用于自动创建项目脚手架的工具。它会基于当前工作环境和你给出的一些配置选项构建一个完整的目录结构。至于其所生成的具体文件和内容,依赖于你所选择的模版和构建过程中你对具体信息所给出的配置选项。
注意:这个独立的程序曾经是作为Grunt内置的"init"任务而存在的。
安装
为了使用grunt-init,需要将其安装到全局环境中。
npm install -g grunt-init
这样就会把grunt-init命令安装到你的系统路径中,从而允许你在任何目录中都可以运行它。
用法
使用grunt-init --help来获取程序帮助以及列出可用模板清单
使用grunt-init TEMPLATE,基于可用模板创建一个项目
使用grunt-init /path/to/TEMPLATE,基于任意其他目录中可用的模板创建一个项目
注意,大多数的模板都应该在当前目录(执行命令的目录)中生成它们的文件(自动生成的项目相关的文件),因此,如果你不想覆盖现有的文件,注意一定要切换到一个新目录中。
安装模板
一旦模板被安装到你的~/.grunt-init/目录中(在Windows平台是%USERPROFILE%\.grunt-init\目录),那么就可以通过grunt-init命令来使用它们了。建议你使用git将模板克隆到项目目录中。例如, grunt-init-jquery模板可以像下面这样安装:
git clone https://github.com/gruntjs/grunt-init-jquery.git ~/.grunt-init/jquery
下面是一些有Grunt官方维护的grunt-init模板:
grunt-init-commonjs - Create a commonjs module, including Nodeunit unit tests. (sample "generated" repo | creation transcript)
grunt-init-gruntfile - Create a basic Gruntfile. (sample "generated" repo | creation transcript)
grunt-init-gruntplugin - Create a Grunt plugin, including Nodeunit unit tests. (sample "generated" repo | creation transcript)
grunt-init-jquery - Create a jQuery plugin, including QUnit unit tests. (sample "generated" repo | creation transcript)
grunt-init-node - Create a Node.js module, including Nodeunit unit tests. (sample "generated" repo | creation transcript)
定制模版
你可以创建和使用自定义模板。但是你的模板必须遵循与上述模板相同的文件结构。
下面是一个名为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/目录中(在Windows上是%USERPROFILE%\.grunt-init\目录),那么只需要使用grunt-init my-template命令,就可以使用这个模版了。
当执行初始化模板时, 只要模板使用init.filesToCopy
和init.copyAndProcess
方法,任何位于root/
子目录中的文件都将被复制到当前目录。注意所有被复制的文件都会被做为模板进行处理,并且所有{% %}
模板都会依据props
数据对象集合中的数据进行替换,除非设置了noProcess
选项。
rename.json用于描述sourcepath到destpath的重命名映射关系。sourcepath必须是相对于root/目录要被复制的文件路径,但是destpath值可以包含{% %}模板,用于描述目标路径是什么。如果destpath被指定为false,那么文件就不会被复制。此外,srcpath还支持通配符匹配模式。
每个初始化提示都会有一个硬编码的默认值或者它会根据当前环境来尝试确定该缺省值。如果你想覆盖某个特定提示信息的默认值,你可以在Linux的~/.grunt-init/defaults.json或者Windows的%USERPROFILE%\.grunt-init\defaults.json文件中选择性的进行处理。
例如,由于我希望使用一个与众不同的名字来替代默认的名字,并且我还希望排除我的邮箱地址,同时我还希望自动指定一个作者的url,那么我的defaults.json看起来就可能像下面这样。
{
"author_name": "\"Cowboy\" Ben Alman",
"author_email": "none",
"author_url": "http://benalman.com/"
}
注意:所有的内置提示信息都有文档,你还可以在源代码中找到他们的名字和默认值。
定义一个初始化模块,也就是template.js文件中的内容
exports.description属性的作用
当用户运行grunt init
或者grunt-init
来显示所有可用的初始化模板时,这个简短的模板描述会和模板名一起显示。比如:
exports.description = ‘Create a jQuery plugin, including QUnit unit tests.‘;
当运行grunt init时,‘Create a jQuery plugin, including QUnit unit tests.‘会和模板的名字一起显示出来。
exports.notes属性的作用
如果指定了这个选项,这个可选的扩展描述将会在任何提示信息显示之前显示出来。这是一个给用户提供一些解释命名空间相关帮助信息的很好的地方。这些提示可能是必选的也可能是可选的,等等。
exports.notes = ‘_Project name_ should not contain "jquery" or "js" ‘;
exports.warnOn属性的作用
如果这个可选的通配模式或者通配模式数组有匹配项出现,Grunt将终止并生成一个警告信息。这对于初始化模板可能覆盖现有文件的情况来说是非常有用的。
exports.warnOn = ‘*‘;
最常见的值是‘*‘
,它能够匹配任意文件或者目录。使用minimatch通配符模式具有很大的灵活性。比如:
exports.warnOn = ‘Gruntfile.js‘; // 警告 on a Gruntfile.js file. exports.warnOn = ‘*.js‘; // 警告 on any .js file. exports.warnOn = ‘.*‘; // Warn on any dotfile or dotdir. exports.warnOn = ‘!*/**‘; // 在任何文件上发出警告,目录就不会 exports.warnOn = ‘*.{png,gif,jpg}‘; // 警告 on any image file. // 通配符模式数组 exports.warnOn = [‘*.png‘, ‘*.gif‘, ‘*.jpg‘];
exports.template函数的作用
虽然exports的属性都定义在该函数的外面,然而所有实际的初始化代码都在此函数的内部。这个函数接受三个参数,grunt参数是一个grunt的引用,它包含所有的grunt方法和库。init参数是一个包含特定于这个初始化模板而存在的方法和属性的对象。done参数是在初始化模板执行完成时必须调用的函数。
exports.template = function(grunt, init, done) { // See the "Inside an init template" section. };
初始化模板的内部,也就是template函数中的内容
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.copyAndProcess方法的作用
遍历对象files中的所有文件,将源文件复制到目标路径,并处理相关内容。
init.copyAndProcess(files, props[, options])
init.destpath方法的作用
目标文件的绝对路径。
init.destpath()
init.expand方法的作用
返回一个独一无二的与给定通配符模式所匹配的所有文件或目录路径的数组。这个方法接收一个逗号分割的通配符模式或者数组形式的通配符模式参数。如果路径匹配模式以!开头,与模式所匹配的结果就会从返回的数组中排除。模式是按顺序处理的,所以包含和排除在数组中出现的顺序是非常重要的。
init.expand([options, ] patterns)
init.prompt方法的作用
给用户一个提示,并让用户输入自己选择的值。
init.prompt(name[, default])
还有很多方法的描述,这里就不细讲了。
内置提示
author_email
package.json
中的用于公开作者的邮箱地址。默认情况下会尝试从用户的git配置中找到一个默认值。
author_name
package.json
中的用于公开作者的全名和版权信息。也会尝试从用户的git配置中找到一个默认值。
author_url
package.json
中的用于公开作者个人网站的URL。
还有很多的这种默认属性值,这些属性值,我们都可以通过init.prompt方法得到,比如:
init.prompt(‘author_name‘),
init.prompt(‘author_email‘),
init.prompt(‘author_url‘),
加油!