項(xiàng)目腳手架

grunt-init

grunt-init是一個(gè)用于自動(dòng)創(chuàng)建項(xiàng)目腳手架的工具。它會(huì)基于當(dāng)前工作環(huán)境和你給出的一些配置選項(xiàng)構(gòu)建一個(gè)完整的目錄結(jié)構(gòu)。至于其所生成的具體文件和內(nèi)容，依賴(lài)于你所選擇的模版和構(gòu)建過(guò)程中你對(duì)具體信息所給出的配置選項(xiàng)。

注意：這個(gè)獨(dú)立的程序曾經(jīng)是作為Grunt內(nèi)置的"init"任務(wù)而存在的。在從0.3升級(jí)到0.4指南中可以查看更多關(guān)于它演變的信息。

安裝

為了使用grunt-init，需要將其安裝到全局環(huán)境中。

npm install -g grunt-init

這樣就會(huì)把grunt-init命令安裝了到你的系統(tǒng)路徑，從而允許你在任何目錄中都可以運(yùn)行它。

注意：你可能需要使用sudo權(quán)限或者作為超級(jí)管理員運(yùn)行shell命令來(lái)執(zhí)行這個(gè)操作。

用法

• 使用grunt-init --help來(lái)獲取程序幫助以及列出可用模板清單
• 使用grunt-init TEMPLATE并基于可用模板創(chuàng)建一個(gè)項(xiàng)目
• 使用grunt-init /path/to/TEMPLATE基于任意其他目錄中可用的模板創(chuàng)建一個(gè)項(xiàng)目

注意，大多數(shù)的模板都應(yīng)該在當(dāng)前目錄(執(zhí)行命令的目錄)中生成它們的文件(自動(dòng)生成的項(xiàng)目相關(guān)的文件)，因此，如果你不想覆蓋現(xiàn)有的文件，注意一定要切換到一個(gè)新目錄中來(lái)保證文件生成到其他目錄。

安裝模板

一旦模板被安裝到你的~/.grunt-init/目錄中(在Windows平臺(tái)是%USERPROFILE%\.grunt-init\目錄)，那么就可以通過(guò)grunt-init命令來(lái)使用它們了。建議你使用git將模板克隆到項(xiàng)目目錄中。例如, grunt-init-jquery模板可以像下面這樣安裝：

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

注意：如果你希望在本地像"foobarbaz"這樣使用模板，你應(yīng)該指定~/.grunt-init/foobarbaz之后再克隆。grunt-init會(huì)使用實(shí)際在于~/.grunt-init/目錄中的實(shí)際的目錄名。

下面是一些有Grunt官方維護(hù)的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)

定制模版

你可以創(chuàng)建和使用自定義模板。但是你的模板必須遵循與上述模板相同的文件結(jié)構(gòu)。

下面是一個(gè)名為my-template的模板示例，它必須遵循下面這樣的常規(guī)文件結(jié)構(gòu)：

• my-template/template.js - 主模板文件。
• my-template/rename.json - 模板特定的重命名規(guī)則，作為模板進(jìn)行處理。
• my-template/root/ - f要復(fù)制到目標(biāo)位置的文件。

假設(shè)這些文件存儲(chǔ)在/path/to/my-template目錄中，那么命令grunt-init /path/to/my-template就會(huì)處理這些模板。這個(gè)目錄中可能存在多個(gè)命名唯一的模板(多個(gè)不重名的模板)。

此外，如果你把這個(gè)自定義模板放在你的~/.grunt-init/目錄中(在Windows上是%USERPROFILE%\.grunt-init\目錄)，那么只需要使用grunt-init my-template命令就可以使用這個(gè)模版了。

復(fù)制文件

當(dāng)執(zhí)行初始化模板時(shí), 只要模板使用init.filesToCopy和init.copyAndProcess方法，任何位于root/子目錄中的文件都將被復(fù)制到當(dāng)前目錄。

注意所有被復(fù)制的文件都會(huì)被做為模板進(jìn)行處理，并且所有{% %}模板都會(huì)依據(jù)props數(shù)據(jù)對(duì)象集合中的數(shù)據(jù)進(jìn)行替換，除非設(shè)置了noProcess選項(xiàng)?？梢钥纯?a href="http://eska-fuses.cn/targetlink?url=https://github.com/gruntjs/grunt-init-jquery" target="_blank" target="_blank">jquery template中的案例。

重命名或者排除模板文件

rename.json用于描述sourcepath到destpath的重命名映射關(guān)系。sourcepath必須是相對(duì)于root/目錄要被復(fù)制的文件路徑，但是destpath值可以包含{% %}模板，用于描述目標(biāo)路徑是什么。

如果destpath被指定為false，那么文件就不會(huì)被復(fù)制。此外，srcpath還支持通配符匹配模式。

為詢(xún)問(wèn)信息指定默認(rèn)選擇

每個(gè)初始化提示都會(huì)有一個(gè)硬編碼的默認(rèn)值或者它會(huì)根據(jù)當(dāng)前環(huán)境來(lái)嘗試確定該缺省值。如果你想覆蓋某個(gè)特定提示信息的默認(rèn)值，你可以在OS X或者Linux的~/.grunt-init/defaults.json或者Windows的%USERPROFILE%\.grunt-init\defaults.json文件中選擇性的進(jìn)行處理。

例如，由于我希望使用一個(gè)與眾不同的名字來(lái)替代默認(rèn)的名字，并且我還希望排除我的郵箱地址，同時(shí)我還希望自動(dòng)指定一個(gè)作者的url，那么我的defaults.json看起來(lái)就可能像下面這樣。

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

注意：即使所有的內(nèi)置提示信息都有文檔，你還可以在源代碼中找到他們的名字和默認(rèn)值。

定義一個(gè)初始化模

exports.description

當(dāng)用戶(hù)運(yùn)行grunt init或者grunt-init來(lái)顯示所有可用的初始化模板時(shí)，這個(gè)簡(jiǎn)短的模板描述也會(huì)和模板名一起顯示。

exports.description = descriptionString;

exports.notes

如果指定了這個(gè)選項(xiàng)，這個(gè)可選的擴(kuò)展描述將會(huì)在任何提示信息顯示之前顯示出來(lái)。這是一個(gè)給用戶(hù)提供一些解釋命名空間相關(guān)幫助信息的很好的地方。這些提示可能是必選的也可能是可選的，等等。

exports.notes = notesString;

exports.warnOn

如果這個(gè)(推薦指定)可選的通配模式或者通配模式數(shù)組有匹配項(xiàng)出現(xiàn)，Grunt將終止并生成一個(gè)警告信息，用戶(hù)可以使用--force來(lái)覆蓋這個(gè)默認(rèn)行為。這對(duì)于初始化模板可能覆蓋現(xiàn)有文件的情況來(lái)說(shuō)是非常有用的。

exports.warnOn = wildcardPattern;

然而最常見(jiàn)的值是'*'，它能夠匹配任意文件或者目錄。使用minimatch通配符模式具有很大的靈活性。例如：

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屬性定義在該函數(shù)的外面，然而所有實(shí)際的初始化代碼指定在它內(nèi)部。這個(gè)函數(shù)接受三個(gè)參數(shù)，grunt參數(shù)是一個(gè)grunt的引用，它包含所有的grunt方法和庫(kù)。init參數(shù)是一個(gè)包含特定于這個(gè)初始化模板而存在的方法和屬性的對(duì)象。done參數(shù)是在初始化模板執(zhí)行完成時(shí)必須調(diào)用的函數(shù)。

exports.template = function(grunt, init, done) {
  // See the "Inside an init template" section.
};

初始化模板的內(nèi)部

init.addLicenseFiles

可以給files對(duì)象添加適當(dāng)命名的許可協(xié)議證書(shū)文件。

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

init.availableLicenses

返回一個(gè)可用許可協(xié)議證書(shū)的數(shù)組：

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

init.copy

它提供一份絕對(duì)或者相對(duì)源文件路徑，以及一個(gè)可選的相對(duì)的目標(biāo)文件路徑，復(fù)制一個(gè)文件時(shí)，可以通過(guò)傳遞的回調(diào)函數(shù)來(lái)選擇性的處理它。

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

init.copyAndProcess

遍歷所傳遞對(duì)象中的所有文件，將源文件復(fù)制到目標(biāo)路徑，并處理相關(guān)內(nèi)容。

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

init.defaults

用戶(hù)在defaults.json中指定的默認(rèn)初始值。

init.defaults

init.destpath

目標(biāo)文件的絕對(duì)路徑。

init.destpath()

init.expand

與grunt.file.expand相同。

返回一個(gè)獨(dú)一無(wú)二的與給定通配符模式所匹配的所有文件或目錄路徑數(shù)組。這個(gè)方法接收一個(gè)逗號(hào)分割的通配符模式或者數(shù)組形式的通配符模式參數(shù)。如果路徑匹配模式以!開(kāi)頭，與模式所匹配的結(jié)果就會(huì)從返回的數(shù)組中排除。模式是按順序處理的，所以包含和排除在數(shù)組中出現(xiàn)的順序是非常重要的。

init.expand([options, ] patterns)

init.filesToCopy

返回一個(gè)包含待復(fù)制文件的對(duì)象，每個(gè)文件都包含了源文件的絕對(duì)路徑和目標(biāo)文件的相對(duì)路徑，并按照rename.json(如果存在)中的規(guī)則進(jìn)行重命名(或者忽略)。

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

獲取單一的任務(wù)文件路徑。

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

init.getTemplates

返回一個(gè)包含所有可用模板的對(duì)象。

init.getTemplates()

init.initSearchDirs

在初始化目錄中搜索初始化模板。template是指模板的位置。還包括~/.grunt-init和grunt-init中的核心初始化任務(wù)。

init.initSearchDirs([filename])

init.process

啟動(dòng)程序并提示開(kāi)始輸入。

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

給用戶(hù)一個(gè)提示，并讓用戶(hù)輸入自己選擇的值。

init.prompt(name[, default])

init.prompts

此對(duì)象包含了所有提示信息。

var prompts = init.prompts;

init.readDefaults

讀取任務(wù)文件中(如果存在)讀取JSON格式的默認(rèn)值，并將它們合并到一個(gè)數(shù)據(jù)對(duì)象中。

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

init.renames

模板的重命名規(guī)則。

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

init.searchDirs

搜索模板的目錄數(shù)組。

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

init.srcpath

根據(jù)文件名搜索初始化模板路徑并返回一個(gè)絕對(duì)路徑。

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

init.userDir

返回用戶(hù)模板目錄的絕對(duì)路徑。

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

init.writePackageJSON

在目標(biāo)目錄中保存一個(gè)package.json文件?；卣{(diào)函數(shù)可以用于后置處理屬性的添加/移除/其他操作。

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

內(nèi)置提示

author_email

用于package.json中的作者郵箱地址。默認(rèn)情況下會(huì)嘗試從用戶(hù)的git配置中找到一個(gè)默認(rèn)值。

author_name

用于package.json中的作者全名和版權(quán)信息。也會(huì)嘗試從用戶(hù)的git配置中找到一個(gè)默認(rèn)值。

author_url

package.json中的用于公開(kāi)作者個(gè)人網(wǎng)站的URL。

bin

項(xiàng)目根目錄中cli腳本的相對(duì)路徑。

bugs

用于項(xiàng)目問(wèn)題跟蹤的公開(kāi)URL。如果項(xiàng)目有一個(gè)Github倉(cāng)庫(kù)，將自動(dòng)指向項(xiàng)目Github的問(wèn)題跟蹤模塊(issue)。

description

項(xiàng)目的描述。通常在package.json或者README文件中。

grunt_version

項(xiàng)目所需的有效Grunt版本范圍定義。

homepage

指向項(xiàng)目首頁(yè)的公開(kāi)URL。如果此項(xiàng)目使用的是github倉(cāng)庫(kù)，那么，默認(rèn)是Github倉(cāng)庫(kù)的url。

jquery_version

如果是jQuery項(xiàng)目，它表示項(xiàng)目所需的jQuery版本。必須是一個(gè)有效的版本范圍定義。

licenses

項(xiàng)目許可協(xié)議證書(shū)。多個(gè)許可協(xié)議證書(shū)使用空格分割，內(nèi)置的許可協(xié)議有：MIT、MPL-2.0、GPL-2.0和Apache-2.0。默認(rèn)是MIT協(xié)議?？梢允褂?a rel="external nofollow" target="_blank" target="_blank">init.addLicenseFiles方法添加自定義許可協(xié)議證書(shū)。

main

項(xiàng)目的主入口。默認(rèn)是lib目錄已項(xiàng)目名稱(chēng)命名的文件。

name

項(xiàng)目名稱(chēng)。在項(xiàng)目模版中將會(huì)大量使用，默認(rèn)指向當(dāng)前工作目錄。

node_version

項(xiàng)目所需的Node.js版本。必須是一個(gè)有效的版本范圍定義。

npm_test

項(xiàng)目中運(yùn)行測(cè)試的命令，默認(rèn)情況下是grunt。

repository

項(xiàng)目的git倉(cāng)庫(kù)。默認(rèn)是一個(gè)猜測(cè)的github url。

title

適合大家識(shí)別的項(xiàng)目名稱(chēng)。默認(rèn)是原始項(xiàng)目名稱(chēng)，并且經(jīng)過(guò)過(guò)濾，適合大家識(shí)別。

version

項(xiàng)目的版本號(hào)。默認(rèn)是第一個(gè)有效的語(yǔ)義版本號(hào)：0.1.0。