火山模块的封装和使用方法

注意: 本手册内容普通用户无需掌握

 

一、什么是火山模块

火山模块实际上就是一系列以下各类文件的集合:

1、火山模块定义文件;

2、所包含的火山源程序文件;

3、火山源程序文件所需要使用的相关辅助文件(譬如外部库、资源等)

系统类库中的所有类均以模块的方式提供,我们可以打开火山平台安装目录的“plugins\vprj_android\classlib\sys\android\app_updater”子目录,该目录中提供了一个名为“应用程序自动更新支持”的在安卓项目下可用的模块:

二、如何定义火山模块

注意: 本节内容普通用户无需掌握

每个火山模块需要提供一个后缀为".vgrp"的Unicode文本文件,该文件为一个文本属性表文件,属性表中可以使用的属性及其格式如下:

doc_format_version = xxx

project_identifier = xxx

name = xxx

[author] = xxx

[version] = xxx

[explain] = xxx

[discard] = true/false

[dependence] = xxx

[unique_mark] = xxx

file

{

[filter] = xxx

name = xxx

}

...

以上属性中,被中括号括住属性的为可选属性,否则为必须提供的属性.

名称 数据类型 解释
doc_format_version 整数 文档格式版本,目前必须为1。
project_identifier 文本型 本模块所支持项目类型的标识符,必须提供且有效. 譬如安卓项目类型(版本号为1)的标识符为: "wutao.vproject.mobile.android.1"
name 文本型 本模块的名称,必须为有效的名称文本。
author 文本型 本模块的作者名称
version 整数 本模块的版本号
explain 文本型 本模块的相关注释文本
discard 逻辑型 表明本模块是否已经被废弃不再使用
dependence 文本型 本模块正常使用所依赖的其它外部火山模块的定义文件路径,如果存在多个,请使用逗号分隔。

所依赖模块文件路径如果为相对路径,则为相对本模块定义文件所处的目录;如果以星号字符(‘*’)开始,表明为从当前项目类型支持插件的类库根目录开始(为项目支持插件目录内的"classlib"子目录 ,譬如安卓项目即为“plugins\vprj_android\classlib”)。

在加入本模块到程序项目中时,这些所依赖外部模块会被自动加入。

unique_mark 文本型 为本模块指定一个唯一性的标记文本,用户程序中只能同时加入一个具有此标记文本的模块。
file   用作定义一个本模块中的火山源文件,本节可以在模块文件中存在多个。
file.filter 文本型 当前火山源文件所处的过滤器路径名称,过滤器路径之间使用'/'字符分隔(如“火山/安卓”)。

在加入本模块到项目中时,该过滤器会被自动创建。

file.name 文本型 提供当前位于本模块中的火山源文件路径。

文件路径如果为相对路径,则为相对本模块定义文件所处的目录。

具体例子请参见火山平台系统安装目录下“plugins\vprj_android\classlib\sys”目录内各子目录中的vgrp文件。

系统在启动时,会自动在所有项目类型支持插件的类库根目录中搜寻火山模块定义文件,然后将其载入以备使用或查询其中信息。

 

三、如何在程序中使用火山模块

打开程序解决方案后,在所欲使用该模块的项目上单击鼠标右键,选择"配置项目所使用模块"菜单项目:

在所显示的对话框中,选择(使用)或者取消选择(不再使用)所指定名称的火山模块,点击确定即可:

当加入某模块后,该模块的定义文件中所有"file"节内列出的火山源程序文件均将被自动加入到所指定项目中,从而支持在该项目中使用此模块中提供的功能。

譬如,假设我们在上面对话框中选择加入了前面所提到的“应用程序自动更新支持”模块,那么其中所包含的源程序文件“a_app_updater.v”将被自动加入到项目中,我们就可以使用在该源程序文件中定义的类了:

 

四、如何生成火山模块安装包文件

注意: 本节内容普通用户无需掌握

模块需要被安装到系统类库中才能被用户所使用,安装模块的方法是通过使用对应的模块安装包。

1、准备好需要打包到模块中的所有文件并放到单个子目录中

这些文件中至少应该有一个火山模块定义文件(vgrp),我们以“应用程序自动更新支持”模块的内容来举例:

A、将“plugins\vprj_android\classlib\sys\android\app_updater”子目录中的所有内容拷贝到任意一个外部目录,譬如:”h:\vcom_test":

B、为了与系统中现有的该模块有所区别,我们使用文本编辑器打开”a_app_updater.vgrp”文件,将其“name”属性改为“我的测试模块”:

2、执行菜单项“工具->制作模块安装包”来生成模块安装包

以下为上面对话框中各参数的说明:

1、选择模块所对应的项目类型;

2、指定模块中的内容所欲安装到对应类型项目插件的用户类库根目录的子目录名称;

3、提供用来对所生成模块安装包进行数字签名的火山证书文件,该数字签名用作对模块的作者进行身份认证,有符合要求的作者可以向我公司申请获取证书文件;

4、提供存放有模块中所有内容的被打包目录路径名(上一步中所准备的单个目录),该目录中的所有内容及其子目录结构均将被压缩打包到模块安装包中,然后在安装时原样解压释放到第2个参数所指定的类库目的目录中;

5、用作指定当用户安装所生成的模块安装包时所需要输入的密码。

下图为上面例子所填写的对话框内容:

点击“生成”按钮,系统将会显示所有安装包参数并询问是否生成,再点击确认即可生成“h:\test.vcip”模块安装包文件。

 

五、如何安装所指定的模块安装包

1、执行“工具->安装模块”,然后选中我们先前所生成的“h:\test.vcip”模块安装包文件;

2、如果先前生成安装包时设置了密码,将会提示用户输入正确的密码;

3、然后系统会显示该安装包的签名信息,用户确认无误后点击“确定”按钮即可将该模块安装到系统。

安装完毕后,用户就可以在项目中加入并使用此模块了。

系统会自动更新类库手册,并选中当前所安装的模块且显示其帮助页面:

该模块被安装到类库目录中的内容和打包时所提供的内容是完全一致的。实际上,安装模块就是将被打包的模块内容释放到系统类库目录中,因此直接将模块内容拷贝到系统类库目录中效果是一样的,但是不提倡这样做,因为通过安装包安装可以进行譬如身份认证、加密、被覆盖内容详情提示等操作,但是如果只是为了备份/恢复系统中所安装的现有模块,那是可以的。

 

六、如何卸载已经安装的模块

执行菜单项“工具->卸载模块”,在对话框中选中所欲卸载的模块名称即可将该模块从系统类库中卸除:

需要注意的是:

1、只有用户自行安装的模块才能被卸载,系统本身自带的模块无法被卸载(在上面对话框中没有列出);

2、模块被卸载后,所有使用了该模块的项目将无法被正常编译,所有依赖该模块的其它模块将无法正常使用,所以请务必慎重;

3、与安装时相同,卸载的本质就是从系统类库目录中将所指定模块的对应子目录删除,同样除了因为需要备份/恢复现有模块,不推荐直接这样操作。

 

七、其它

1、目前可用的模块内容加密措施:

如果您想所封装模块的部分内容对用户保密,可以将关键部分使用外部库实现(如火山安卓平台中使用so或jar库文件,火山视窗平台中使用dll动态链接库),然后 在外部库采用对应加密措施来处理保密工作。