Source Insight的使用指南V2.0.doc

Catalog 目 录1.概述32.工具栏以及窗口32.1工具栏42.1.1 Symbols Toolbar42.1.2 View Toolbar42.1.3 Navigation Toolbar42.2窗口52.2.1 Source File Windows52.2.2 Symbol Windows52.2.3 Project Windows62.2.4 Context Windows72.2.5 Relation Windows72.2.6 Search Results Window83.建立项目工程94 宏（Macro）134.1 简介134.2 如何使用154.3伪码转换代码功能164.4 附录文件165.PC-lint集成175.1 设置方法175.2 PC-lint多个文件185.3 Pc-lint错误与代码自动对应问题195.4 附录文件196.常用操作196.1 Lookup References196.1.1 选项说明206.1.2 实例216.2 Synchronize Files236.3 块拷贝246.4 Document Types246.5 查看函数调用关系266.5.1 说明266.5.2 查看调用关系286.5.3 筛选功能316.5.4 跟踪316.6 Smart Rename326.7 快捷方式346.7.1 Shift+F8346.7.2 F7346.7.3 CTRL+/356.7.4 Shift+F9356.7.5 Alt+,/ Alt+.356.7.6 F9/F10366.7.7 其他36Source Insight的使用指南Source Insight是一个支持多种开发语言（Java、C/C+/C#等等）的编辑器和浏览器，由于其查找、定位、彩色显示等功能的强大，在我们的实际工作中得到广泛的应用。1.概述Source Insight是一种基于项目工程的应用程序，它将对项目工程中的文件进行分析以后创建一个自身的数据库用于记录项目文件之间的联系，并且能够进行动态的更新。它能显示语法符号（变量、函数、类等等）之间的引用树，类的继承流图，以及调用树，极大地提高了代码的浏览速度；在进行代码的编辑，它会自动地给出非常有用的相关信息。2.工具栏以及窗口Source Insight是一种多文档（MDI）应用程序，每个源文件都有自己的子窗口，它的工作界面如图2.1所示，主要包括： 主菜单以及工具栏 源文件窗口，可以在窗口中对源文件进行编辑 其他各钟辅助性质的工具窗口图2.1 Source Insight界面2.1工具栏如图所示，工具栏位于source insight应用程序窗口的顶部，你可以通过菜单View Toolbars Main Toolbar打开或者关闭。它有很多子工具栏组成，例如大家都熟知的通用工具栏Standard、Edit等等，此外还包括一些Source Insight特有的工具栏。你可以通过菜单View Toolbars分别打开或者关闭，这些子工具栏是可以在窗口中任意拖动的。2.1.1 Symbols ToolbarSymbols Toolbar是source insight中一个很常用的工具，主要提供了访问变量、函数等语法操作方式，在实际工作中经常被用来查看、查找变量、函数的定义以及调用。2.1.2 View ToolbarView Toolbar用来显示/隐藏source insight的一些辅助窗口，例如常用Context、Project、Relation窗口。2.1.3 Navigation ToolbarReference功能是Source Insight的鲜明特色之一，它可以在速度极快的在整个工程中找到所有的标记，标记间的切换基本就是通过Navigation Toolbar来完成的。2.2窗口2.2.1 Source File WindowsSource Insight是一个多文档（MDI）应用程序，因此当你打开项目中任意一个文件时，它都将独立地显示在一个source file window中，同时一个symbol window将会自动附加在该窗口的左侧，当然你可以在Document Options中设置Usesymbol window复选框来控制是否使用这项功能。图2.2 Source File Windows2.2.2 Symbol WindowsSymbol window通常现在每个文件的源文件窗口的左侧，Symbol window中列举了该文件中定义的所有变量、函数、宏等等，这样可以帮助你很迅速地了解整个文件的概貌。你可以在symbol window直接点击某项，就可以很轻易地参看该变量、函数的定义。图2.3 Symbol Windows2.2.3 Project WindowsProject window中列举出了整个项目的源文件以及语法，它可以帮助你快捷地打开某个文件，你只需要在窗口中双击该文件名，而不用关心文件存放在哪个目录.图2.4 Project WindowsProject window提供了五种视图方式： File List View 列举项目中所有文件. File Directory 按照目录列举项目文件. File Type View 按照文件类型分类列举项目文件. Symbol List View 列举项目中所有语法符号. Symbol Class View 按照语法类型列举项目语法符号.2.2.4 Context WindowsContext Window是Source Insight的一个很鲜明的特性，它极大地方便了用户参看、编辑源代码。当你在源文件窗口中点击一个标识符时，Context Window中将会自动地显示出这个标识符的定义，函数还会同时显示出入口参数以及函数的具体实现。图2.5 Context Windows2.2.5 Relation WindowsRelation Windows是Source Insight又一鲜明的特征，它用图形化的方式生动地描述函数、变量之间的调用关系、引用关系以及更多的信息。你可以在Relation Window Properties对话框中设置关联关系。图2.6 Relation Windows2.2.6 Search Results Window当你执行Search Files 或者Lookup References命令以后，Source Insight会自动创建Search Results Window显示结果。窗口中的每一行对应符合查询条件的一条记录（某文件某一行代码符合查询条件），窗口中列举的所有符合条件的查询结果包括源链接（红色双向箭头），有点类似于超文本链接，直接点击的话就可以直接访问符合查询条件的某个文件某一行。图2.7 Search Results Windows3.建立项目工程Source Insight的操作都是围绕项目工程project来进行的，project是很多源文件的集合，当你建立project时需要加入源文件，Source Insight会建立一个简单的文件数据库用来记录哪些文件包含在project中。启动Source Insight程序后，可以进入如图3.1工作界面，不难发现界面上显示的都是第二节中介绍过的工具栏。图3.1 Source Insight建立Project（1） 首先选择主菜单中的 “Project”选项的子菜单“New Project”新建一个项目，此时会弹出对话框如图3.2要求你选择项目组文件存放的路径以及项目文件名，你可以任意选择。图3.2 选择存放的路径（2） 选择保存后，将会弹出一个对话框如图3.3，接受默认选择，如果硬盘空间足够的话，可以将Configuration的第一个复选框选上，该选项将会占用与源代码大致同等的空间来建立一个本地数据库以加快查找的速度。图3.3 Project设置（3） 选择“OK”按钮，将会有另一个新的对话框弹出如图3.4，在这个对话框里，可以选择将要编辑、浏览的文件加入工程。一种方式是通过在File Name中输入要阅读源代码文件的名称，点击“Add”按钮将其加入，也可以通过其中“Add All”和“Add Tree”两个按钮可以将选中目录的所有文件加入到工程中，其中“Add All”选项会提示加入顶层文件和递归加入所有文件两种方式，而“Add Tree”相当于“Add All”选项的递归加入所有文件，可以根据需要使用。实际使用过程中，个人感觉“Add Tree”更好一些。由于这种方式采用了部分打开文件的方式，没有用到的文件不会打开，所以，加入数千个文件也不用担心加入的文件超出程序的所能容忍的最大值。图3.4 增加文件到Project（4） 正确加入文件以后，Project基本上就建立完成了，此时建议执行Synchronize File命令，同时选上“Force all files to be re-parsed”复选框如图3.5，Source Insight将会为项目中所有文件更新语法信息库。图3.5 Synchronize File到此为止，Source Insight就完成了一个新的Project工程的建立。4 宏（Macro）4.1 简介Source Insight提供了一种类似于C的宏语言，宏的脚本文件命名时采用.em扩展名，可以在Source Insight中打开。以下为宏的源文件（utils.em）中一个功能代码：macro InsertHeader()hwnd = GetCurrentWnd()buff = GetCurrentBuf()hit = 0 if (hwnd != 0 & buff != 0 )sel = GetWndSel(hwnd)ln = sel.lnFirst cur_line = */ InsBufLine( buff, ln, cur_line ) cur_line = 修改记录: InsBufLine( buff, ln, cur_line ) cur_line = 返回: / 函数返回值的说明 InsBufLine( buff, ln, cur_line ) cur_line = 输出: / 对输出参数的说明。 InsBufLine( buff, ln, cur_line ) cur_line = 输入: / 输入参数说明，包括每个参数的作用、取值说明及参数间关系。 InsBufLine( buff, ln, cur_line ) cur_line = 修改表: / 被修改的表（此项仅对于牵扯到数据库操作的程序） InsBufLine( buff, ln, cur_line ) cur_line = 访问表: / 被访问的表（此项仅对于牵扯到数据库操作的程序） InsBufLine( buff, ln, cur_line ) cur_line = 被调用: / 调用本函数的函数清单 InsBufLine( buff, ln, cur_line ) cur_line = 调用: / 被本函数调用的函数清单 InsBufLine( buff, ln, cur_line ) cur_line = 描述: / 函数功能、性能等的描述 InsBufLine( buff, ln, cur_line ) cur_line = 函数名: / 函数名称 InsBufLine( buff, ln, cur_line ) cur_line = /* InsBufLine( buff, ln, cur_line ) SetWndSel(hwnd, sel) 以下为执行后的效果：/*函数名: / 函数名称描述: / 函数功能、性能等的描述调用: / 被本函数调用的函数清单被调用: / 调用本函数的函数清单访问表: / 被访问的表（此项仅对于牵扯到数据库操作的程序）修改表: / 被修改的表（此项仅对于牵扯到数据库操作的程序）输入: / 输入参数说明，包括每个参数的作用、取值说明及参数间关系。输出: / 对输出参数的说明。返回: / 函数返回值的说明修改记录: */我们可以根据自己的需要定制宏。4.2 如何使用1、先要建立一个工程文件。通过菜单Project-New Project，然后按照提示做即可。2、把宏文件（以em为后缀名的文件）加入工程，宏文件存放目录没有要求，这是关键的一步。3、为宏设置一个快捷方式，点击OPTIONS菜单，选择KEY ASSIGNMENTS;在COMMAND输入框中选择宏，例如：Macro: InsertFileHeader；点击Assign New Key按钮；按下自己喜欢的组合键，比如CTRL+ALT+H；4.3伪码转换代码功能为宏TransWholeFile和 TransSelected定义快捷键，可实现基于C语言的伪码转换为代码的功能。 TransWholeFile指转换整个文件，TransSelected指转换选中部分。4.4 附录文件文件中包含多种用途的宏，可以自己选择需要的。5.PC-lint集成5.1 设置方法PC-lint是我们常用的工具，也可以在source insight中集成PC-lint如果你在安装过程中选定了使用某个开发环境，安装程序会在你安装的目录下生成一个env-xxx.lnt的文件，例如选择了Source Insight就会有一个env-si.lnt文件。用编辑器打开该文件，在该文件开始的注释中说明了如何将PC-LINT功能集成在开发环境中，集成在Source Insight中的过程如下：1、从Options菜单中选择“Custom Commands”命令项。2、在Name栏中输入“PC-lint ”，原则上这个名称可以随便起，只要你能搞清楚它的含义就可以了。3、在Run栏中输入“c:lintlint-nt -u -ic:lint std_si env-si %f”其中c:lint是你PC-LINT的安装目录。请注意，std_si .lnt和env_si.lnt文件都在c:lint目录下，它的文件名可能为std.lnt或者env.lnt，我们根据实际情况填写。std_si文件中是存放PC-LINT的配置，包括路径等，在PC-LINT说明书中应有说明。4、在Output栏中选择“Iconic Window”、“Capture Output”。5、在Control栏中选择“Save Files First”。6、在Source Links in Output栏中选择“Parse Links in Output”、“File，then Line”。7、在Pattern栏中输入“( *) (0-9+)”。8、点Add键加入该命令。如下图5.1所示：图5.1 Custom Commands在Source Insight下打开要LINT的文件，打开Options菜单中的“Custom Commands”命令项，在“Command”栏中选择“PC-lint unit check”命令运行即可。注意到Run一栏的参数和上面图示中是不一样的，其他古怪参数也都放在c:lintstd_si.lnt中。请注意，不论你怎样配置参数一定不要忘记了将env-si.lnt包含在你的配置文件里，否则就无法进行错误信息和程序的自动对应了。为了使用方便，你还可以配置一下Menu按钮，将它加到系统菜单里，通过Options-Menu Assignments设置，也可Options-key Assignments设置快捷方式，方便使用。5.2 PC-lint多个文件1在Run栏中输入“c:lintlint-nt -v -ic:lint std_si env-si c:lintfilelist.lnt。其中v这个参数可以根据需要制定：2在filelist.lnt中记录文件列表的方法(1) 从Project菜单中选择open project命令项，打开文件所在的project。(2) 从Project菜单中选择add and remove project files命令项。(3) 从弹出的窗口的project files列表中选择要检查的文件，点击鼠标右键，选择copy list命令项，从弹出的窗口中选择copy selected Item(s)。(4) 打开filelist.lnt，将文件列表粘贴上去，这样在filelist.lnt中就记录了被检查文件的绝对路径了。5.3 Pc-lint错误与代码自动对应问题由于PC-lint的版本比较老，不是专门为windows环境开发的，不能够有效的支持长文件名和有空格的目录名。因此最好按照DOS的风格设置路径，这样可避免一些不必要、意想不到的麻烦。 如C:Program FilesMicrosoft Visual Studio* 用C:PROGRA1MICROS1*表示，改写std_si.lnt文件中新工程的路径，重新PC-lint编译，错误信息和源代码可以进行自动对应了。5.4 附录文件6.常用操作这一节将对Source Insight实际使用中的一些常用操作进行简要的介绍，希望通过学习本节的内容以后，你能对Source Insight的基本操作有初步的了解。6.1 Lookup ReferencesLookup References可以说是Source Insight实际使用中最常用的操作，它广泛地应用在各类查询中。选中某个变量、函数后选择菜单Search Lookup References或者使用快捷方式（CTRL+/）就可以使用这项功能，它可以查询项目中所有源文件，包括注释、采用#ifdef定义的非激活代码。6.1.1 选项说明执行Lookup References命令后，首先会弹出如图6.1对话框用来设置查询方式。图6.1 Lookup ReferencesFind References To输入你需要查询的标识符，比较常用的例如变量、宏、函数等等Search In采用下拉框的形式，下拉框中列举了常用的文件类型，你可以选择在某一类文件中查询，例如在C源文件中查询，缺省为查询项目中所有文件。Search Method提供了四种查询方法： Simple String Regular Expression 按照正则表达式的方式查询. Keyword Expression 关键字查询，有点类似于internet查询. Lookup Reference 按照引用关系进行查询，缺省查询方式.Lines of Context仅仅当查询方式为Keyword Expression时有效。Find word variations仅仅当查询方式为Keyword Expression时有效。它可以用来查询关键词开头的所有单词，例如关键词为“open”时，Source Insight同样会查询出 “opens”、 “opened”、“opening”类似的单词。Case Sensitive是否区分大小写。Whole Words Only 限制查询时严格匹配关键词，对于Lookup References方式永远有效。Skip Inactive Code如果选中，将忽略非激活代码的查找。Skip Comments如果选中，将忽略注释代码的查询。Search Only Comments 如果选中，将只是查询注释部分内容。Smart Reference Matching 将会启用Source Insight优化的匹配方式，例如当你采用某个结构体中的成员变量进行查询的时候，Source Insight也只会查询出与结构体变量相关的记录，不会查询出其他和这个成员变量重名的变量。Touch files and cause recompile. 这个选项很有用处，特别是项目的编译规则设置为依赖于时间时，如果选中的话，会把满足查询条件的文件的修改时间设置为现在的时间，因此下次编译时这些文件都会重新编译。6.1.2 实例定位是for循环中少循环一次的错误，搜索目标是形如for (i = 0; i udwSectionNum-1; .)的样式。同时为了减少搜索的复杂度并提高搜索结果的完整性，经过反复尝试，我采用了如下的策略：打开Source Insight的搜索对换框，选择“Search Method”下拉框中的“Regular Expression”，然后“Option”中仅选中“Case Sensitive”，最后输入搜索词：a-zA-Z+w*.*a-zA-Zw*-w*1;它的意思是，查找形如“变量1 Preferences General对话框中选择复选框Background project synchronization。执行菜单Project Synchronize Files后，你将看到图3.5对话框：Add new files automatically 当你执行Synchronize Files命令时，会将文件中新增的文件自动增加到你的Project中。Force all files to be re-parsed 如果选中，Source Insight将会在symbol database中更新所有文件的相关信息，否则只会更新最新的文件。Synchronize the current source file only如果选中，Source Insight将会在symbol database中更新正在编辑、浏览的文件。Suppress warning messages 如果选中，Source Insight将不会提示任何错误信息，例如某个文件不能打开或者访问。6.3 块拷贝按住Alt，再拖动鼠标，可以实现块拷贝，拷贝的块可以粘贴，也是块的方式，有些场合下，对编辑头文件很方便。6.4 Document TypesDocument Option允许你根据文件名或者扩展名定义它的编辑、显示的格式。Source Insight可以通过每个文件的文件名来自定义它的编辑、显示格式，因此你可以为不同的文件类型采用不同的格式用于区分，增加代码的可读性、美观性。执行菜单Options Document Option后，你将看到图6.2的对话框，你可以通过对话框的Add Type/Remove Type新增和删除某类文件格式。图6.2 Document Options例如，打开文件可能会发现Symbols窗口中无法处理*.inc和*.cpp文件，通过Options-Document Options中，将File filter修改为*.c;*.h,*.inc,*.cpp即可。此外，因公司编程规范中明确要求不能使用TAB键，通过Options-Document Options中，点中Expand tabs。同样地，你可以通过Options Style Properties来设置每种样式的具体格式，如图6.3所示。图6.3 Style Properties6.5 查看函数调用关系6.5.1 说明在实际应用中，你可以灵活地应用Relation Window查询函数（包括全局变量，宏定义、结构体等标识符）的调用关系和引用关系，它能帮助你快速地了解整个项目工程的程序结构。Relation window可以通过菜单View-Relation Window或者快捷工具栏中的Relation Window快捷键进行打开/关闭操作。Relation Window有两种视图方式，分别为大纲方式和图形方式，你可以通过按钮选择采用哪种方式显示：Relation Window主要包括3种关联类型： Contains 显示出当前标识符的内容，例如结构体变量会显示出它的成员变量. Calls 显示调用关系，常用于参看函数的调用关系，当选中一个函数后，会显示出该函数调用了哪些函数。 References 显示引用关系，常用于参看函数的引用关系，当选中一个函数后，会显示出该函数被哪些函数所引用。Relation Window下面一些常用的工具按钮，这些按钮在实际使用过程中是十分有用的。 Jump to Definition跳转光标到选定标识符（函数、变量、宏定义等等）的定义处。Symbol Info选择这个按钮将会弹出一个窗口显示选定的标识符的定义，这是检查变量、函数定义的一种比较快捷的方法。Look Reference使用Look Reference功能。Lock锁定Relation Window，这时候窗口中的显示将不会随着光标的变化自动更新，当然你可以点击Refresh按钮手工刷新。Refresh刷新Relation Window的显示。View Relation Outline切换Relation Window采用大纲形式显示结果。View Relation Horizontal Graph切换Relation Window采用图形的方式显示，显示采用从左到右排列的方式进行。View Relation Vertical Graph切换Relation Window采用图形的方式显示，显示采用从上到下排列的方式进行。Relation Window Properties显示Relation Window的属性页。6.5.2 查看调用关系打开Relation Window后，用鼠标光标定位要查看的函数，此时Relation Window中会自动显示该函数的调用关系：缺省情形下只会显示一层调用关系，如果要查看更多层次的调用关系，先选中函数，右键菜单选择Expand Special，可以设置你需要显示的层次.当然，你也可以通过选择不同的关联方式来显示该函数被哪些函数引用，在Relation窗口内选中函数，右键菜单选择View Functions中的References by functions，这样在Relation窗口中会显示该函数被哪些函数所引用。6.5.3 筛选功能此外，Relation Window还支持筛选功能，你可以通过它来显示定制显示，下面描述一下常用的两个选项：Exclude Symbols选择这个选项允许显示窗口中把某些标识符排除在外，如果某个标识符存在排除列表中，该标识符将不会在Relation Window被进一步展开显示.Exclude C Macros 选择这个选项，Source Insight将会忽略宏定义。6.5.4 跟踪缺省情形下，当你移动鼠标的时候，Relation Window中会自动跟踪光标下的标识符，并且自动实现该标识符的相关信息，当然你可以通过Symbol Tracking Options来进行修改。Off 选择这个选项可以关闭自动跟踪的功能。Track selected symbol (i.e. under cursor) 选择这个选项，Relation Window中会自动跟踪光标下的标识符Track the enclosing function or class 选择这个选现，Relation Window将会自动显示函数或者结构体的定义，当你编写函数的时候这个选项是十分有用的。 6.6 Smart RenameSmart Rename可以用来重命名标识符，它具备全项目工程查找/替换能力，你可以利用它对所有项目组文件的某个标识符（如变量、函数等等） 进行重命名操作，同样地，你也可以用来重命名函数局部变量、结构体的成员变量等等。Old Name需要替换的标识符，光标下的单词缺省会自动地显示在输入框中，你可以根据自己的需要进行更改，如果需要对结构的成员变量进行操作，则需要输入完整的标识符例如DocDraw.paintStruc。New Name输入新的标识符，对于结构的成员变量替换操作则只需要输入新的成员变量名，例如上面描述的DocDraw.paintStruc，只需要输入NewpaintStruc而不需要再输入DocDraw。Output Search Results选上该选项，则查询结果会显示在Search Results window中。Confirm Each Replacement选上该选项，每次进行替换时Source Insight会提醒你确认进行替换。Confirm Each File选上该选项，Source Insight将提醒你确认每个被修改过的文件。Smart Reference Matching选上该选项，采用Reference功能查找需要替换的标识符。Skip Inactive Code选上该选项，将会忽略非激活代码的查找/替换。Skip Comments选上该选项，将会忽略注释的查找/替换。Include Read-Only Files (keep buffers open)选上该选项，Source Insight将会对只读的文件保持打开的状态，允许你通过手工的方式来保存文件的修改。如果该选项没有被选上的话，Source Insight将忽略只读文件的查找。6.7 快捷方式6.7.1 Shift+F8功能：高亮显示某一函数或变量高亮显示是使用Source Insight浏览代码时非常常用的一个功能，当你按下Shift+F8后，光标下的标识符会呈现高亮颜色方便区分浏览，如下图ucMinute：6.7.2 F7功能：在整个工程中匹配关键字按下F7以后，Source Insight会弹出Browse Project Symbols对话框，对话框中会列出所有包含symbol关键