README

buildjs-plus

a plus version for buildjs-beta

技术前提：同buildjs-beta

环境要求：安装nodejs

标签：基于SeaJS , Web前端集成自动化构建 , Buildjs-plus

## 前序 buildjs-beta(github为buildjs，npm上由于buildjs名称被使用，只能命名为buildjs-beta)提供了基于linux和inotifywait的实时文件监听和集成编译流程，由于buildjs-beta采用了gruntjs的编译流程，并非管道式编译，存在效率上的问题，同时，并没有提供版本号控制，有部分问题需要改进，于是基于buildjs-beta的编译流程，做了buildjs-plus的改进版本。

改进版的编译流程不再受gruntjs的限制，采用瀑布流编译流程： Buildjs 简易图示

## 改进功能

采用nodejs的chokidar来做文件监听，保证windows和linux下都无缝兼容；
提供单文件编译流程（如上图）；
提供css的合并功能，通过@import的语句（同css的@import）来输出合并后的css文件（循环依赖会被切断）；
提供版本号控制，针对图片文件以生成新文件方式控制（生成新文件命名格式为：xx@vxx.png等），针对js和css文件对seajs的前端配置文件做map字段的替换；
优化配置，通过一个文件bjs.conf.js来控制所有编译的配置路径，简化配置文件数量

## 如何使用 buildjs-plus需要了解3个大步骤：目录结构、配置文件bjs.conf.js、命令行：

demo
    ├ front
    .   ├ conf
    .       └ conf.js
    .   ├ bjs.conf.js(编译流程的配置文件)
    .   ├ src（开发时关注的模块目录）
    .       ├ app
    .           ├ common
    .               ├ normalize.css
    .               ├ common.css
    .               ├ common.js
    .               └ view
    .                   ├ head.tpl
    .                   └ foot.tpl
    .           └ login
    .               ├ css
    .                   └ index.css
    .               ├ img
    .                   ├ icon.png
    .                   ├ index.png
    .                   └ ...
    .               ├ js
    .                   └ index.js
    .               └ view
    .                   └ login.tpl
    .       └ widget
    .          ├ alert
    .              ├ alert.css
    .              ├ alert.js
    .              └ alert.htpl (通过编译工具 => alert.htpl.js, 符合seajs模块)
    .   └ lib(第三方插件)
    ├ resource(编译后的部署路径)
    └ views（在bjs.conf.js下配置使用smarty时生成的tpl放置的位置）
         ├ src
             ├ common
                 ├ head.tpl（只保留两层目录结构：模块名/文件名.tpl）
                 └ foot.tpl
             └ login
                 └ login.tpl

目录结构只是一个示例，具体命名可以按需修改，但是唯一需要注意的是，不要把编译后部署的目标路径指定在监听的源文件夹路径下，这样会导致循环触发文件变动，使编译工具无止境循环执行。

配置文件 bjs.conf.js

相比buildjs-beta，plus版本的配置文件更简洁明了。buildjs-plus提供了bjs.set(key, value)或bjs.set(object)的方式指定编译时的相关配置，下面代码按照支持的key进行说明：

// 设置项目采用的编译模式，默认是cmd（即是基于seajs），目前仅支持cmd
bjs.set("ctype", "cmd");

// 源项目业务模块路径，如：demo/front/src，由于运行工具时需要在demo/front文件夹下运行，故此key可以设置为"./src"
bjs.set("src", "./src");

// 编译后的业务模块部署的路径
bjs.set("dst", '../resource/src');

// 编译后的文件部署的路径（如：demo/front -> demo/resource，包括front下其他只做copy不做其他动作的文件）
bjs.set("dist", "../resource");

// 制定项目是否使用了php的smarty模板引擎
bjs.set("smarty", true);

// smarty字段设置为true时，需要重新制定.tpl输出的路径（这种方式是为了与php制定的smarty模板路径配合，方便php管理）
bjs.set("view", "../views/src");

// 前端模块加载器的配置文件，由于目前仅支持cmd，故此文件其实为seajs的前端配置文件
bjs.set("conf", "./conf/conf.js");

// 设置模块编译过程需要忽略的某些模块，默认为第三方库
bjs.set("ignore", "./lib");

// 是否需要对css进行合并
bjs.set("cssImport", true);

// 是否需要对css进行压缩
bjs.set("cssMinify", true);

// 是否需要对js进行合并压缩
bjs.set("uglify", true);

// 是否需要带版本号的编译
bjs.set("version", true);

// 设置合并压缩过程忽略的某些模块（以模块的相对路径为key，一般seajs会制定base路径，其他业务模块会基于base设定相对路径）
bjs.set("mignore", {
    js: {
        "widget/ipick.alert/ipick.alert.js": 1
    },
    css: {}
});

// 设置需要加载的插件（编译工具支持自定义插件，但需要按一定的开发格式，后续会详细介绍）
bjs.set("plugins", [
    // less
    {
        pattern: /\.less$/,
        lib: 'css-less/task.js'
    }
]);

// 设置国际化输出的相关路径，其中用{lang}来标记语言替换，如运行命令：bjs xgettext en，那么{lang}会被替换为"en"
bjs.set("i18n", {
    po: './_bjs_/i18n/i18n.{lang}.po',	// 生成po文件的路径
    src: './src',						// 提取待翻译字段的源路劲
    msrc: '../resource/src',			// 需要翻译的业务模块源路径
    mdst: '../resource/{lang}',			// 翻译输出的业务模块路径
    vsrc: '../views/src',				// 需要翻译的页面资源源路径（使用smarty后需要配置）
    vdst: '../views/{lang}'				// 翻译输出的页面资源路径
});

命令行

全局安装了buildjs-plus之后，bjs的命令会添加到系统环境变量中，可以使用以下命令开启或停止编译工具：

bjs init

初始化bjs.conf.js文件，生成简单的配置文件

bjs watch

开启文件实时监听和编译

使用此命令时，远程窗口或cmd窗口会处于运行状态，按ctrl+c或者关闭窗口都可以停止该程序的运行。开启文件实时监听后，只有源文件夹有文件的增删改，都会触发编译。若初始化时源文件夹下文件较多，则需要等待较长时间。单文件编译效率较高，在一般主机配置、CPU占用率和500个文件左右的前提下，编译时间大概在1s以内。

bjs stop

停止文件实时监听和编译

此命令只在linux下生效，并且只针对使用了bjs/bin/bjs.sh的方式。使用bjs watch由于会阻塞进程，不能让程序在后台进程中执行，编译工具提供另一种方式可以在后台运行，同时提供此方式来停止后台进程的运行。

bjs clear

清除生成的旧的版本号文件（针对图片的版本号冗余情况）

bjs xgettext [lang]

提取待翻译的字段，其中参数[lang]支持多语言，不同语言间用","隔开，如：bjs xgettext en-US,zh_CN

bjs gettext [lang]

根据指定的语言翻译已提取的字段，其中参数[lang]同xgettext

安装方式

确认系统已经安装了nodejs和npm。

带插件版本的：npm install buildjs-plus --save-dev
不带插件版的：npm install buildjs-plus-noplugin --save-dev

在linux下，还需要运行buildjs-plus/bin/init.sh，将bjs命令添加到系统命令，即可执行上述的命令，同时，bjsc这个命令也被添加到系统命令，其功能同bjs watch，只不过是其程序后台进程运行的方式。

Usage no npm install needed!