Scilab 5.3.3下模块的移植、在线帮助的编写以及工具箱的建立.docx

Scilab 5.3.3下模块的移植、在线帮助的编写以及工具箱的建立By 廖昊夫 孙琪一、 引言Scilab作为一个仍在不断开发更新的开源计算软件，其每一个版本较之前都有很大变化，这种变化使得之前在旧版本上开发的一些模块，不能很好地在新版本（Scilab 5.3.3）上运行，基于此问题本文将展开深入探讨，并给出工具箱的建立办法。二、 模块的移植 Xcos 界面 Xcos是新版本Scilab的仿真器，其在界面上较之前有很大的改动。新版本界面如下： 图 1 Xcos组件盘 图 2 Xcos主窗口如上图所示，图1是Xcos的组件盘，组件盘中存放的是用户或者系统已经添加并分类好的模块，通过它用户可以很方便的向Xcos的主窗口添加模块。图2是Xcos的主窗口，是用户搭建自己仿真模型的区域。 Xcos图片文件在Xcos中图片文件分为三类：.gif或.png文件，.svg文件以及.h5文件。它们均用来显示模块的外观，但用在不同的场所。u .gif或.png文件是标准的图片文件，是位图，其主要用于在组件盘中显示模块的外观，如图1中红方框内的模块图片实际上就由调用对应的.png文件所实现的。Scilab自带的该类文件存放于SCImodulesxcosimagespalettesu .svg文件由XML语言编写，属于矢量图。当该类文件对应的图片被放大时，图片的清晰度不会发生改变。因此该图片被用于显示Xcos主窗口中的模块外观。如图2中红方框内的模块外观就是由.svg文件产生的。Scilab自带的该类文件存放于SCImodulesxcosimagesblocksu .h5文件是Scilab通过模块的接口函数自动生成的文件，用于向Xcos中添加模块时使用，Xcos能够通过.h5文件生成对应的.svg图片。Scilab自带的该类文件存放于SCImodulesscicos_blocksblocks 模块的加载在5.3.x中打开SciNotes，图 3 SciNotes打开示意图，如红方框所示进入SciNotes后，输入如下形式的代码：loadXcosLibs();/读取Xcos模块库pal = xcosPal(My palette);/设置你要在xcos中存放你模块的文/件名exec(接口函数路径,-1);/运行接口函数和计算函数，相当于注册exec(计算函数路径,-1);/以便Scilab能够识别这些外来函数/另外当计算函数用非Scilab语言编写时，这时的注册方式不/能用exec()函数来注册,而应该用ilib_for_link函数注/册PathName =你需要存放的.h5文件路径;/在Scilab中模块的加载需要先生成一/个.h5文件来配套使用scs_m = 接口函数名(define);/以job=define运行接口函数，由/返回值scs_m获取模块的数据结构及/初始化参数、外观等信息export_to_hdf5(PathName, scs_m);/生成.h5文件，需要说明的是这里的/PathName及scs_m均是自己设定的/变量名pal = xcosPalAddBlock(pal,PathName,.png或.gif文件路径, .svg文件路径); /由.h5，.png和.svg文件及设置好/的pal名，向xcos中加载模块。其/中.png文件和.svg文件路径为可/选参数xcosPalAdd(pal);/在xcos中添加存放模块的文件夹由上面的代码我们可以看出，在5.3.x中生成模块需要首先生成一个包含模块信息各方面的.h5文件，然后再调用加载模块函数xcosPalAddBlock，以在xcos中生成图形化界面。当编写好加载代码后点击运行，然后打开xcos我们就能看到模块已经成功加载完成了。点击运行按钮，执行代码：图 4 执行按钮示意图，如红方框所示模块加载成功：代码中设定的文件名图 5 模块加载完成示意图图5中模块图片与系统自带原生模块图片有出入，这是因为在编写模块加载代码时，我们并没有为模块指定.png文件以及.svg文件，即xcosPalAddBlock（）函数的第三、四个参数为空。此时系统只能由.h5文件自动生成模块图片，图5的模块图片均由系统自动生成。 计算函数接口对于由非scilab语言编写的计算函数，我们并不能直接将其运行，因此需要使用scilab里面专门提供的接口函数（这里所说的接口函数不是模块里的接口函数，请勿混淆）最主要的就是ilib_for_link这个函数，它的各参数的意义为：ilib_for_link(标签名, .c文件, , c)u 这里的标签名对应于模块接口函数中model.sim=list(计算函数名,函数类型用数字（15表示）)的计算函数名。u 在最新版本的Scilab中第三个参数应为计算函数源文件（旧版本位.obj文件）u 第三个参数一般置空，第四个参数则是你计算函数所用的语言类型，C语言用c表示,fortran语言用f表示。u 在执行完ilib_for_link这个函数后应该紧接着写一句exec loader.sce来完成计算函数的运行值得注意的是，在使用ilib_for_link函数时，计算函数源文件应该放置在scilab当前默认的文件夹中，其路径可以在主窗口中直接输入pwd查看。若想改变scilab默认路径可采用cd(修改后的路径名)来修改。最终的非Scilab语言计算函数的注册方式如下：ilib_for_link(标签名,.c文件,c);exec loader.sce三、 在线帮助的编写在线帮助，即Scilab的help。当我们在Scilab中开发好自己编写好的函数或者模块后，为了方便别人使用，我们需要为其添加在线帮助，以告诉使用者我们编写的函数或模块的使用方法。 在线帮助界面图 6 Scilab在线帮助界面如图6所示，在线帮助分为两个部分，左侧为在线帮助的书签，用于将在线帮助分类。右侧为在线帮助的主窗口，该窗口界面由XML语言编写。 在线帮助资源Scilab在线帮助所调用的资源分为两类：.xml文件和.jar文件。u .xml文件由XML语言编写，是在线帮助的核心部分，Scilab通过该类型的文件来显示在线帮助的内容u .jar文件由.xml文件生成，Scilab能够通过相应的函数将.xml文件以及其他生成在线帮助所需的所有资源封装成.jar文件，最终Scilab通过调用.jar文件生成在线帮助。因此，生成在线帮助的逻辑框图如下：.xml文件.xml文件.xml文件.xml文件. jar文件在线帮助添加函数生成函数 .XML文件的编写在Scilab中添加帮助文档，最基本的一步是在遵循xml语法的基础上按照Scilab对其的格式要求编写xml文档。先介绍一下xml的语法，然后以DES模块的帮助文档DES.xml为例，介绍帮助文档的书写格式。1. xml语法简介u 各元素是以开始，以结束的，其中aaa是该段的标识，两个标志之间的内容即属于此部分。u xml中，注释是格式u 在Scilab的帮助文档中，有以下几个常用标示符： 用于区分说明文档中各个部分 标识文档日期 标识该部分的题目 放置图片文件 放置带显示的文字 以列表条目形式显示内容 每条列表项内容（通常itemizedlist、listitem、para嵌套使用） 用于标识该条目的标题 用于链接同文件夹中的文件2. 示例以DES.xml文档为例解释xml文档的书写格式:refentry xmlns=/ns/docbook xmlns:xlink=/1999/xlink xmlns:svg=/2000/svg xmlns:mml=/1998/Math/MathML xmlns:db=/ns/docbook version=5.0-subset Scilab xml:lang=en xml:id=DES 22-08-2011 DES module DES (Data Encryption Standard) module, used to encrypt messages Block Screenshot Palette DES Palette Description Enter the size of bit of input binary numbers and the content of the key.This module will encrypt messages using the key. Dialog box Input size. The size of each group of binary numbers. The recommended value is 8. key. The key is a 7-bit vector whose every bit is a number ranging 0 255. Interfacing function DES on 5.3.xmodelDESdes_int.sci Computing function DES on 5.3.xmodelDESdes_com.sci Author Liao Haofu, Cen Jianhu, Sun Qi, Sun Jianfeng 3. 关于链接文件在需要加入超链接的地方输入：example_1_function_7其中，example_1_function_7是一个xml文件名，且此文件与当前编辑的xml文件在同一文件夹下。 在线帮助的加载在线帮助的标准加载代码非常简单，只有两句：xmltojar(存放.xml文件的文件夹路径, 在线帮助书签名,在线帮助所用语言名);add_help_chapter(在线帮助书签名, 存放.xml文件的文件夹路径的上两层路径/jar);u 第一个函数的作用是将.xml文件转换为.jar文件，该函数有三个参数，经实测真正起作用的是该函数的前两个参数，即无论第三个参数为什么内容，实际上对最终添加结果没有影响，但第三个参数内容通常为存放.xml文件的文件夹名。该函数的调用最终结果有一个特点：最终转换完成的.jar文件一定会存放在存放.xml文件的文件夹上两层的文件夹中的一个叫jar的文件夹里。如当.xml文件存放于.testhelpen_US时，那么最终转换完的.jar文件一定存放于.testjar中。u 第二个函数的作用是调用.jar文件在Scilab中添加在线帮助，该函数有两个参数，经实测第一个参数不起作用，即第一个参数并不能决定在线帮助书签名，实际上该名称只由xmltojar这个函数的第二个参数决定。该函数的第二个参数为所调用的.jar文件所在文件夹的路径。u 值得注意的是，尽管用于加载在线帮助的两个函数均有两个参数没有实际意义，但在使用他们时仍应按照规则填写，否则当重复加载时会出现意想不到的错误。因此这里我们给出了推荐的标准文件夹名以及函数参数设置方法：图 7 标准在线帮助文件夹在线帮助的标准文件夹设置方式如图7所示，我们一般将帮助文档的不同语言类型的.xml文件夹放在help文件夹下，不同语言类型的.xml文件夹名应为：en_US(英语)、fr_FR(法语)、zh_CH(中文)，另外.xml文件所调用的图片资源应放在help文件夹下一个叫png的文件夹里。最终生成的.jar文件将自动被放在jar文件夹里，而jar文件夹与help文件夹应该同在用户自定义的一个文件夹中，图中我们定义的文件夹名为help template，另外若我们希望添加的在线帮助书签名为DES则我们所对应的在线帮助加载函数应写为：xmltojar(.help templatehelpen_US, DES , en_US );add_help_chapter(DES , .help template jar);四、 工具箱的建立前文分别讲述了模块以及在线帮助的加载方法，本节将通过对工具箱的建立，以实现对前两种加载方法在Scilab的封装，从而让使用者能够更加快捷和规范地在Scilab上进行开发工作。 工具箱框架在Scilab里，开发人员已经写好了标准的工具箱框架，读者可以在SCIcontrib里找到，该文件夹里包括了两个工具箱框架toolbox_skeleton以及xcos_toolbox_skeleton。其中toolbox_skeleton是函数工具箱框架，而xcos_toolbox_skeleton则是Xcos模块工具箱框架。二者的框架结构十分相似，但后者相对复杂且实用，因此我们在此将主要讲解xcos_toolbox_skeleton的内容。图 8 xcos_toolbox_skeleton工具箱框架下面我们对其主要部分进行介绍：u help正如前文在线帮助一节的介绍，help文件夹里存放的是生成在线帮助文档所必须的.xml文件。其采用之前所介绍的标准文件夹命名方式。u jar同样jar文件夹里存放的是生成在线帮助文档所必须的.jar文件。具体内容详见第三节。u marcosmarcors文件夹里主要存放模块的接口函数，以及用Scilab语言编写的计算函数，同时里面还包含了加载接口函数说必须的build文件等。u imagesimages文件夹里有3个文件夹分别为h5、svg、gif，正如前文模块移植一节所介绍该文件夹里存放模块的外观图片资源。注意：在Scilab 5.3.3的xcos_toolbox_skeleton里imagine文件夹中并没有h5这个文件夹，这是一个严重的错误，读者请自行添加，否则将导致工具箱加载错误。u src该文件夹里存放c语言编写的模块计算函数，以及执行模块计算函数注册的加载文件。u sci_gateway该文件夹里存放c语言编写的接口函数，以及加载文件。u etc该文件夹里村存放的是工具箱的核心加载程序，用于对macros、palette、simulation functions、gateways、help、demos等的加载。u builder.sce工具箱的建立程序，用于完成对工具箱的建立。u clean.sce工具箱的删除程序，用于完成对工具箱的清除。 自定义工具箱以上介绍的是工具箱的标准框架，该框架里包含的都是些例子模块及程序。下面我们介绍如何通过修改标准工具箱里面的内容来完成对工具箱的自定义工作。1. 自定义工具箱名称要建立一个自己的工具箱，我们首先要为我们设定一个自己的名字，当然在设定之前我们应该首先赋值一个xcos_toolbox_skeleton工具箱，然后我们需要修改如下几个地方：u 将整个工具箱文件夹修改成自己定义的名称。图 9 修改后的工具箱文件夹如图9所示，我们在SCIcontrib文件夹下，添加了一个名称为DES的工具箱框架。u 打开自己的工具箱文件夹，并在SciNotes里，将工具箱目录下的builder.sce文件打开。并将里面的 TOOLBOX_NAME、TOOLBOX_TITLE的值均由原来的xcos_toolbox_skeleton该为自己定义的名称。图 10 修改后的builder.sce如图10所示，我们将DES下的builder.sce中的TOOLBOX_NAME、TOOLBOX_TITLE的值均改为了DES。u 再打开自己定义的工具箱文件夹下的etc文件夹，将其中的xcos_toolbox_skeleton.start和xcos_toolbox_skeleton.quit文件名改为DES.start和DES.quit，如图11所示。图 11 修改后的etc文件夹内容至此，我们的工具箱名称已经初步改为我们自己所设定好的名字了，且运行builder.sce不会报错。2. 自定义工具箱模块u 添加自定义模块的接口函数和用Scilab语言编写的计算函数首先，将需要添加的模块的接口函数和计算函数存放到macros文件夹下，然后用SciNotes打开macros文件夹中名为buildmacros.sce的文件，将其中的tbx_build_blocks(toolbox_dir, TBX_SUM_c);语句中的TBX_SUM_c替换为自己添加的接口函数名，如果添加多个接口函数则应为接口函数1,接口函数2,，接着在tbx_build_blocks(toolbox_dir, 接口函数名);语句后面添加如下形式的语句exec(macros_path + 计算函数名.sci);用以向Scilab中加载计算函数，如有多个计算函数则添加多条该语句。图 12 向macros模块里面添加自定义的计算函数和接口函数图 13 修改buildmacros.sce里面的内容如图12所示，我们向macros文件夹中添加了analpf_int.sci、APCM_int.sci、UPSMPL_c.sci这3个接口函数，以及APCM_com.sci这一个计算函数（.bin文件是加载完成后工具箱自动生成的文件，不需要添加），因此我们在图13中对buildmacros.sce做了如下修改，将tbx_build_blocks(toolbox_dir, TBX_SUM_c);改为tbx_build_blocks(toolbox_dir, analpf_int,APCM_int,UPSMPL_c);并添加了exec(macros_path + APCM_com.sci);语句。u 添加C语言编写的计算函数首先向 工具箱名scrc文件夹中添加计算函数源文件（.c文件），然后用SciNotes打开 工具箱名scrc文件夹中名为builder_c.sce的文件，找到tbx_build_src(block_sum, business_sum, . block_sum.c, business_sum.c, 并将其替中的两个里面的内容替换为自己添加的计算函数名，注意第一个里仅填写函数名，第二个须填写函数名加扩展名如：tbx_build_src(函数名1, 函数名2, .函数名1.c, 函数名2.c, 图 14 向DESscrc文件夹中添加计算函数图 15 修改builder_c.sce中的内容如图14所示我们在DESscrc文件夹中添加了upsmplblk.c这个文件，并打开该文件夹中的builder_c.sce，做了如图15所示的修改。u 添加模块的自定义图片添加完模块的计算函数和接口函数后，如果我们不为其指定相应的外观图片资源，就会产生如第二节图5中的情况。因此，为了美观起见我们还需向工具箱中添加我们自定义的图片资源。添加的方法比较简单，向工具箱的images文件夹里的svg，gif文件夹中添加相应的图片资源即可，但注意资源名称应与其相对应模块的接口函数名一致。h5资源自动生成不需要添加。如图16，我们向我们的DES工具箱中添加了analpf_int.svg、APCM_int.svg、UPSMPL_c.svg这三个svg资源以及analpf_int.gif、APCM_int.gif、UPSMPL_c.gif这三个gif资源。h5资源自动生成不需要添加。图 16 添加svg以及gif资源u 修改模块加载后Xcos组件盘的标签名当模块加载好后，如果我们没有事先为其指定组件盘的标签名，则将会出现如图17中的情况。图 17 图中标签名为系统自定义标签名u 为此，我们需要事先为其指定标签名。首先，在SciNotes中打开工具箱下ect文件夹中的.start文件，将其中的Add blocks to the Xcos palette部分（37至43行）找到pal = xcosPal(Xcos toolbox blocks);语句将中的内容改为自己需要修改成的组件盘标签名即可。如图18，我们将组件盘的标签名改成了D