黄鹤楼 builder

1. 概述

hhlb 全称为 HHL Builder,黄鹤楼项目构建工具。

hhlb 的作用是创建、调用、处理 client 项目所需的资源,以及将黄鹤楼项目打包成为最终的产品。

hhlb 的主要功能采用 python 3.4 写成,它也要调用许多已有的程序,例如 NDK、git、php、python2 等等。

调用命令为 hhlb 参数

2. 配置 hhlb

2.1 安装与更新

hhlb 需要安装后才能使用。安装之后,所有管理相关的功能都可以使用 hhlb 来完成。

如果是完全干净的系统,还没有任何 HHL 相关的项目,可以使用这个命令来安装:

pip install -r http://192.168.18.18/project/1201/tool/hhlb_requirements.txt

更新 hhlb,请重复执行上面的命令。

要查看当前的 hhlb 版本,请执行::

pip list

2.2 配置文件

第一次运行的时候,会自动创建配置文件。配置文件中会保存正确的项目文件夹,因此第一次运行时, 必须 位于 client 项目的上级文件夹。

Warning

普通用户尤其要注意上面这点。

创建了配置文件之后,就可以在任何位置运行 hhlb 命令了。

hhlb 每次运行都会读取配置文件,读取顺序是这样的:

  1. 寻找当前文件夹下的 hhlb_conf.py ,如果这个文件存在,就使用它的值;若不存在则继续;
  2. 寻找用户 HOME 文件夹下的 hhlb_conf.py ,若存在,则使用它的值;若不存在,就会创建这个文件。

想知道当前使用的是哪个配置文件,可以使用 hhlb -h 命令。

2.3 针对普通用户的配置

hhlb 有许多依赖,为了使用 hhlb 的所有功能,需要进行一些设置。

但普通用户(策划和美术同学)不需要 hhlb 的所有功能,因此进行简单的设置即可使用。请遵循下面的步骤:

  1. 正常安装 hhlb ,参考 2.1 安装与更新
  2. 修改 hhlb_conf.py 配置文件, 将其中的 check_ece 的值改为 False

Warning

zrong 2015-04-16

本文档子命令及之后的部分不再更新,请以命令行帮助为准。
使用 hhlb -h 查看命令行帮助。

2. 子命令

build 采用子命令的方式调用,使用 hhlb -h 可以查看 build 支持的所有子命令::

admin               管理员专用;
init                初始化项目(或者重新初始化)使用;
update              更新资源或者 git 库;
templ               根据模版生成文件;
res                 转换和生成资源;
android             安卓打包工具;
ios                 iOS 打包工具。

3. admin 子命令

admin 子命令的功能是管理项目。

使用 hhlb admin -h 可以查看 init 子命令的所有参数::

-a, --all           处理所有内容。
--cocos             创建 cocos2d-x zip 文件,并上传到18服务器。
--lua               创建 quick 和 cocos lua 框架 zip 文件,并上传到18服务器。
--res               从 client/res 创建资源 zip 文件,并上传到18服务器。
--cpp               从 client/frameworks/runtime-src 创建 C++ 项目的 zip 文件,并上传到18服务器。
--src               从 client/src 创建所有 lua 源码的 zip 文件,并上传到18服务器。
--upself            更新 hhlb 工具自身。
--reconf            重建 build_conf.py 配置文件。
--tolua {auto,manual,all}
                    创建 lua 绑定文件。
--doc {hhl,zrong,all}
                    生成文档并上传到18服务器。
--updist {hhlb,hhlc,zrong}
                    上传python 工具到18服务器。

4. init 子命令

Warning

在使用 --force 参数时必须十分小心,因为它会 删除 所有已存在的项目。未保存或者未提交的内容都会完全丢失。

使用 hhlb init -h 可以查看 init 子命令的所有参数::

--refresh           1. 重新生成 build_conf.py 配置文件.
                    2. 安装最新的 python 模块。
                    3. 若提供这个参数,则会忽略其他所有参数。
-f, --force         删除相关的文件夹和项目,强制重新初始化。
-a, --all           初始化所有的 git 仓库、项目以及库。
--client            初始化 client git 仓库。
--resource          初始化 resource git 仓库。
--config            初始化 config git 仓库。
--data_tester       初始化 data_tester git 仓库。
--protocol          初始化 protocol git 仓库。
--serverctrl        初始化 serverctrl git 仓库。
--socketserver      初始化 socketserver git 仓库。

5. update 子命令

与 init 子命令不同,update 负责初始化之后对项目的更新。因此 update 子命令一般 不会 破坏或者删除现有项目。

Warning

在使用 --force 参数时必须十分小心,因为它会对指定的 git 仓库执行 git reset --hard 操作,以保证仓库干净(clean),所有没有提交的内容都会丢失。

使用 hhlb update -h 可以查看 update 子命令的所有参数::

-f, --force         对指定的仓库(由下面的参数提供)执行 "git reset --hard" ,然后执行 "git pull origin master"。
-a, --all           更新下面的所有内容。
--cocos             更新 cocos2d-x 框架。删除 client/frameworks/cocos2d-x,从 18 下载压缩包并解压到已删除路径。
--cpp               更新 C++ 框架。删除 client/frameworks/runtime-src,从 18 下载压缩包并解压到已删除路径。
--lua               更新 lua 框架。删除 client/src/[quick|cocos],从 18 下载压缩包并解压到已删除路径。
--client            对 client git 仓库执行 git pull origin master。
--resource          对 resource git 仓库执行 git pull origin master.
--config            对 config git 仓库执行 git pull origin master.
--data_tester       对 data_tester git 仓库执行 git pull origin master.
--protocol          对 protocol git 仓库执行 git pull origin master.
--serverctrl        对 serverctrl git 仓库执行 git pull origin master。
--socketserver      对 socketserver git 仓库执行 git pull origin master。

6. templ 子命令

templ 子命令负责生成项目中使用的配置文件。 --templ-sub-name 参数是必填参数,在生成配置文件的时候,必须指定一个替换模版的名称。

使用 hhlb templ -h 可以查看 templ 子命令的所有参数::

-n TEMPL_SUB_NAME, --templ-sub-name TEMPL_SUB_NAME
                      必须提供一个替换模版的名称。例如 1 代表 1 号模版。
-a, --all             生成所有可生成的文件。
--resinfo             生成 client/res/resinfo.lua。
--server              生成 client/src/conf/server.lua。
--runapp              生成 runapp.sh 或 runapp.bat,提供调用模拟器参数的功能。

7. res 子命令

res 子命令负责生成项目中使用的资源文件。 它主要处理 resource git 仓库中的资源。

Warning

在使用 --force 参数时,如果同时提供了 --all 参数,则会直接删除 res 文件夹。

使用 hhlb res -h 可以查看 res 子命令的所有参数::

-f, --force           在处理之前,移除处理的目标文件夹。若与 -a 选项同时使用,则直接移除 res 文件夹。
-a, --all             处理所有资源文件夹。
--plst [PLST [PLST ...]]
                      处理碎图文件所在的 plst 文件夹。接受多个参数指定要处理的子文件夹。不提供参数则处理所有子文件夹。
--pdir [PDIR [PDIR ...]]
                      处理完整图像文件所在的 pdir 文件夹。接受多个参数指定要处理的子文件夹。不提供参数则处理所有子文件夹。
--arm [ARM [ARM ...]]
                      处理骨骼动画所在的 arm 文件夹。接受多个参数指定要处理的子文件夹。不提供参数则处理所有子文件夹。
--fnt [FNT [FNT ...]]
                      处理字体文件所在的 fnt 文件夹。接受多个参数指定要处理的子文件夹。不提供参数则处理所有子文件夹。
--par [PAR [PAR ...]]
                      处理粒子特效所在的 par 文件夹。接受多个参数指定要处理的子文件夹。不提供参数则处理所有子文件夹。
--snd [SND [SND ...]]
                      处理声音效果所在的 snd 文件夹。接受多个参数指定要处理的子文件夹。不提供参数则处理所有子文件夹。
--ani [ANI [ANI ...]]
                      处理逐帧动画所在的 ani 文件夹。接受多个参数指定要处理的子文件夹。不提供参数则处理所有匹配的文件。
--test                直接删除 res/test ,将 resource/test 中的所有内容复制过去。
--conf                生成 config 中的所有配置文件,将其复制到 src/conf 目录中。
--prot                生成 protocol 中的所有 socket 协议,将其复制为 src/conf/protocols.lua 。
--lang {zh_cn}        处理特定的语言,默认为 zh_cn 。
--density {sd}        处理特定的分辨率。默认为 sd 。
--vendor {team1201}   处理特定的发行商。默认为 team1201。

res 文件夹中除了资源之外,可能还包含一些奇怪的东西,例如 resinfo.lua ,这个就不属于资源的一部分。因此如果删除了 res 文件夹,则需要重新生成这些奇怪的东西。

如果 --force 参数不是和 --all 一起使用,而是和具体的资源类型一起使用,那么命令将仅仅删除对应资源的文件夹。例如 hhlb res -f --plst --pdir 则会删除 res/plstres/pdir 文件夹(但不会无聊到跑去删除 res 文件夹),然后生成这两个文件夹中的所有资源。

--ani 参数的使用有些不同。
由于ani 中的文件夹名称必须以 ani_ 开头,因此这里的参数,可以使用文件夹的全名,也可以不包含 ani_ 开头的部分。
例如,有个 ani 文件夹为 ani_1003 ,那么在提供参数的时候可以直接使用 hhlb res --ani ani_1003hhlb res --ani 1003

8. server 子命令

server 子命令负责管理 hhl 服务器程序。它通过处理服务器相关项目的 git 仓库来控制服务器的更新和重启等动作。

使用 hhlb server -h 可以查看 server 子命令的所有参数::

-t {socket,http,dt,redis}, --type {socket,http,dt,redis}
                      详见下方介绍
-s {start,stop,reopen,reload,quit}, --signal {start,stop,reopen,reload,quit}
                      详见下方介绍
-u [UPDATE [UPDATE ...]], --update [UPDATE [UPDATE ...]]
                      详见下方介绍
-m, --merge-master    在执行服务器命令之前,先合并要当前项目的 master 分支。

8.1 服务器类型

--type 参数提供4个服务器支持:

socket

socketserver 进行控制;

http

httpserver 进行控制;

dt

dtserver 进行控制;

redis

对 redis 服务器进行控制。

8.2 服务器信号

--signal 参数对服务器发出信号,一共有 5 个信号可用:

  1. start
  2. stop
  3. reopen 停止服务器,然后重新启动,连接会中断。
  4. reload 重载配置文件,但不会重启服务器,连接不会中断。
  5. quit

redis 服务器仅支持前3个信号,其他服务器支持所有信号。

8.3 服务器更新

--update 参数用于更新服务器端的代码。若提供这个参数,则在 git push 的时候,钩子会将 git 库中的代码部署到对应的服务器中。

这个参数是可选的,可传递分支名称或者 sha1 名称。

  • 如果不提供参数,则使用自己的分支中的内容更新服务器;
  • 传递的分支或者 sha1,则使用提供的分支内容更新服务器。

8.4 Samples

除了可以直接使用 hhlb 命令行来控制服务器,还可以通过自行在提交信息中加入控制码来达到 --signal--update 选项的效果。

hhlb 会从配置文件的 user_conf.name 字段中读取当前的用户名称,这个名称必须与你的 httpserverdtserversocketserverserverctrl git 仓库的分支名称匹配。

下面用几个 Sample 来展示用法。

8.4.1 Sample 1

目前位于 serverctrl git 仓库的 zrong 分支,下面的三行代码是等价的:

git commit --allow-empty -m 'SOCKET reload' && git push origin zrong
hhlb server -t socket -s reload
hhlb server -s reload

上面的代码都会重载(reload) socketserver 服务器,因为它是默认的服务器,所以可以省略 –type 参数。

使用空提交 --allow-empty ,不必修改任何库内容。

8.4.2 Sample 2

目前位于 httpserver git 仓库的 zrong 分支。下面两行代码是等价的:

git commit --allow-empty -m 'UP' && git push origin zrong
hhlb server -t http -u

8.4.3 Sample 3

目前位于 dtserver git 仓库中的 zrong 分支,下面的代码指定将 git 服务器 上的当前裆裤的 allen 分支的内容更新到 zrong 使用的程序中:

git commit --allow-empty -m 'UP allen' && git push origin zrong
hhlb server -t dt -u allen

8.4.4 Sample 4

在提交 server 代码修改的时候,可以同时更新服务器上的程序,只需要将控制码单独放在第一行即可,这样做可以减少一次空提交:

git commit -m 'UP allen\nhello world!'

使用 GUI 就更简单,在控制码之后回车,写入其他提交信息即可。