集成与构建指南.doc

集成与构建指南

XXX项目

修订历史

日 期
版本
作者
审核
说 明
2004-2-6
V1.0
胡协刚

初稿
2004-2-14
V1.1
胡协刚

根据潘学会的反馈进行修订
2004-2-16
V1.2
胡协刚

增加持续集成的内容

目 录
1 概述 5
2 术语说明 5
3 角色与职责 6
4 集成环境 6
4.1 集成网络部署 7
4.2 编译环境 7
4.2.1 msvc6 7
4.2.2 bcc55 8
4.3 构建工具 8
4.4 持续集成工具 9
4.5 软件配置管理客户端 9
4.6 用户私有构建场所 9
4.7 主机克隆 10
5 构建基础知识 10
5.1 Ant构建脚本 10
5.1.1 Ant项目配置文件 10
5.1.2 Ant配置文件示例 10
5.1.3 Ant执行示例 12
5.2 CruiseControl执行脚本 13
5.2.1 CruiseControl项目配置文件 13
5.2.2 CruiseControl配置文件示例 14
5.2.3 Ant封装（wrapper）配置文件示例 15
5.2.4 cruisecontrol执行示例 15
6 集成构建基本流程 16
6.1 概述 16
6.2 集成过程说明 16
6.3 持续集成过程说明 17
7 构件的集成原则 18
7.1 生产者与消费者 18
7.2 源码目录组织原则 19
8 各类构件集成的实施方案 20
8.1 第三方开发包的实施方案 20
8.2 项目构件的实施方案 23
8.3 项目系统集成发布的实施方案 25
8.4 批量构建步骤 26

第27页，共27页

集成与构建指南

1 概述
软件开发的目标是得到满足需求的可运行的交付工件，即通常是得到由源码等中间工件编译、链接并集成而生成的一个建造（build）。然而构建集成却是一项看似简单实际上充满了陷阱的工作，特别是在团队开发的场景下，将牵涉到将不同成员开发的源码等集成一体，解决各类冲突与依赖等复杂情况，这个过程还直接依赖于软件配置管理流程的支持。一个合格的集成员需要掌握多项知识和技能，本文档将帮助集成员等相关角色理解一个完整的构建集成过程，引导他们迅速地掌握本项目的构建工作。
本文档主要内容包括：
² 描述如何创建满足项目集成与构建活动的工作环境
² 简要介绍构建工具的相关知识
² 描述实施—〉单元测试—〉提交—〉集成—〉冒烟测试的基本流程
² 深入说明自动化持续集成的流程
² 提供对第三方开发包、项目构件等的源码结构组织和集成的指南

2 术语说明
Ÿ 冒烟测试
用于快速验证一个系统集成的工作版本被成功地构建的一组测试。它们必须是低成本的测试（比如自动化的测试），目标是保证一个相对稳定的、值得展开后续重量级测试的工作版本被发布给测试员使用。
Ÿ 持续集成
是对日构建的进一步扩展。在专门工具的支持下，通过实施自动化的构建、测试，使得项目的源码可以在专用构建机上持续地进行集成构建与测试，即在既定周期（可以短到30秒）中，新提交的源码将被自动地集成，相关人员随即获得编译和测试结果。

3 角色与职责
参与构建集成过程的角色如下：

角色
相关职责描述
备注
集成员
Ÿ 制定集成与构建计划
Ÿ 编制集成的自动化构建脚本
Ÿ 指导或帮助实施员编制私有构件的自动化构建脚本
Ÿ 执行集成，解决编译与链接冲突，调试构建脚本等
Ÿ 建立工作基线

实施员
Ÿ 编制私有构件面向集成的自动化构建脚本
Ÿ 提交构件源码等中间工件（delivery）
Ÿ 重设开发基线（rebase）

配置管理员
Ÿ 配置集成用工作视图（view）
Ÿ 分配存取权限

环境工程师
Ÿ 制定项目组的开发环境配置方案
Ÿ 建立项目的开发、集成与测试软件环境
Ÿ 解决软件开发环境和工具使用中出现的问题

4 集成环境
为了将源码等中间工件编译、链接生成的一个建造（build），必须使用相应的编译工具；而实现构建的自动化，则需要类似make等构建工具的支持；实施持续集成还依赖CruiseControl这类专门工具；另外由于集成通常在团队协同的环境下开展，软件配置管理工具将在此间充当重要角色。
推荐的安装顺序是：克隆主机—〉安装配置管理工具客户端—〉建立用户视图—〉准备用户私有构建场所—〉配置编译环境—〉配置构建环境—〉执行初次构建
4.1 集成网络部署

4.2 编译环境
4.2.1 msvc6
本项目的首要IDE用的是MS Visual Studio 98，编译器相应的用msvc6。
项目中使用了msvc6的基础库和mfc库的全集（包括unicode部件，在安装时注意要使用定制方式来选择）。
为了正常使用msvc6，注意正确设置相应的Path等环境变量，虽然安装程序能自动设置它们，但通过克隆的机器可能丢失。
环境变量示例：
Path=C:\WINNT\system32;C:\WINNT;C:\Development_Tools\Building-Utils\apache-ant-1.6.0\bin;C:\Development_Tools\Microsoft Visual Studio\Common\Tools\WinNT;C:\Development_Tools\Microsoft Visual Studio\Common\MSDev98\Bin;C:\Development_Tools\Microsoft Visual Studio\Common\Tools;C:\Development_Tools\Microsoft Visual Studio\VC98\bin; C:\Development_Tools\Microsoft Visual Studio\Common\MSDev98\bin
另外可以直接运行下列批命令来自动设置（仅对克隆的机器有效）：
D:\Development_Home\Tools.Configs\path.bat
4.2.2 bcc55
为了支持第三方使用Borland IDE，需要配置Bcc55编译器。
4.3 构建工具
常见的构建工具，C/C++有Make，Bjam，cpptasks for Ant；Java有Ant，C#有NAnt。考虑到Ant具备使用方便、功能全面、XML格式可读性强、容易掌握等优点，本项目选用Ant作为首要的构建工具。
典型构建工具环境的配置为：
jsdk1.4.x——Java运行环境
apache-ant-1.6.0——Ant工具
安装路径示例：
C:\Development_Tools\Building-Utils\apache-ant-1.6.0
cpptasks1.0beta——支持Ant进行 C/C++构建的扩展
安装路径示例：
C:\Development_Tools\Building-Utils\apache-ant-1.6.0\lib\ cpptasks.jar
ant-contrib-0.6——支持Ant使用控制逻辑的扩展
安装路径示例：
C:\Development_Tools\Building-Utils\apache-ant-1.6.0\lib\ ant-contrib-0.6.jar
envset——项目组自行开发的一个WinNT环境变量设置小程序
安装路径示例：
C:\Development_Tools\Building-Utils\apache-ant-1.6.0\bin\ envset.exe
注意：
为了支持cpptasks ，ant-contrib的使用，必须在Ant构建脚本中加入以下声明：
<!-- task and type extension -->
<taskdef resource="cpptasks.tasks"/>
<typedef resource="cpptasks.types"/>
<taskdef resource="net/sf/antcontrib/antcontrib.properties"/>
4.4 持续集成工具
主流的持续集成工具有CruiseControl，提供了Java与两个版本。我们通过对Java版本进行相应配置，实现了C/C++项目的持续集成。
在集成服务器上的安装路径示例：
C:\Development_Tools\Building-Utils\cruisecontrol-2.1.5
为了支持C/C++项目，需要加入cpptasks、ant-contrib，可以通过修改CruiseControl.bat文件来实现，示例如下：
set EXTLIBDIR=%ANT_HOME%\lib
%EXTLIBDIR%\ant-contrib-0.6.jar;%EXTLIBDIR%\cpptasks.jar;
4.5 软件配置管理客户端
本项目选用ClearCase作为软件配置管理的工具。开发工作站、测试工作站和集成服务器都将安装ClearCase客户端，其安装配置参见其它ClearCase相关文档。
视图路径示例：
D:\Shared_Views\PCHL_V1_Dev
4.6 用户私有构建场所
各构建主机上需要创建类似D:\Development_Home\的目录，作为工作用户私有的开发场所，开发人员可以将\PCHL_Supports\Environments\Development\ Development_Home.zip（可以从ClearCase的PCHL_Working流下找到）解压直接生成此目录集，其中D:\Development_Home\Building.Workspace子目录将用于自动构建。Development_Home.zip包内还包含CruiseControl持续集成的相关配置文件。
4.7 主机克隆
为了提高工作效率，项目组的开发工作站可以通过克隆的方式进行快速安装。环境工程师针对项目组日常开发、管理、协同等工作需要，制作了完整的系统盘（C主分区）映像，包括开发工具、CASE工具、其它常用工具等，上述构建用工具软件均包含在内。
映像有Windows2000Professional与Windows2000Server两个版本，源路径示例：
\\back1-svr\ghost_imgs\w2ksrv_x\w2ksrv.GHO
使用者可以用支持网络连接的引导CD启动系统，执行ghost，然后进行克隆。

5 构建基础知识
5.1 Ant构建脚本
自动化构建的核心是表达构件间依赖关系和构建步骤的脚本，Make工具使用makefile，而Ant使用了基于XML格式的缺省文件名为Build.Xml的配置文件。
5.1.1 Ant项目配置文件
Ant配置文件描述了一个构建项目（project），它由一些属性定义（property）和一个目标树（target tree）组成；目标代表了一个期望的构建结果（例如生成一个链接好的可执行文件），并表述了其依赖的其它目标，常见的构建目标有初始化（Init）、编译（Compile）、单元测试（Test）、安装（Install）、清除（Clean）等；每个目标包含了实现它而将要执行的任务（task），Ant支持的任务种类非常丰富，例如源码编译、文件拷贝、执行命令行操作等。Ant还提供一种非常重要的任务就是执行其它的项目配置文件，使得多个构建项目的批处理成为可能。
5.1.2 Ant配置文件示例
下面是一个Ant项目的配置文件示例：

<?xml version="1.0"?>
<project name="Improve-Install" default="InstallAll" basedir=".">
<description >
Build file for all Improve library project
</description>

<!-- task and type extension -->
<taskdef resource="cpptasks.tasks"/>
<typedef resource="cpptasks.types"/>

<taskdef resource="net/sf/antcontrib/antcontrib.properties"/>

<!-- Properties -->
<property environment="sys_env"/>
<property name="proj.root" location="..\."/>
<target name="-Init">
<condition property="cc" value="${mswin32-compiler}">
<os family="windows"/>
</condition>
<condition property="cc" value="gcc">
<os family="unix"/>
</condition>
<echo message="${ant.project.name}: Init Complete"/>
</target>

<target name="Clean" depends="-Init"
description="Clean the temporal building space">
<!-- Delete all files in temporal build space -->
<delete includeEmptyDirs="true" >
<fileset dir="${tgt.bin}" includes="objs/*, objs_d/*" defaultexcludes="false"/>
</delete>
<delete includeEmptyDirs="true" >
<fileset dir="${tgt.lib}" includes="objs/*, objs_d" defaultexcludes="false"/>
</delete>
<echo message="${ant.project.name}: Clean buildspace Complete"/>
</target>

<target name="AutoBuild" depends="-Init, -Prep" description="AutoBuild all source to get bin out">
<mkdir dir="${tgt.lib}\objs_d"/>
<mkdir dir="${tgt.lib}\objs"/>
<if>
<equals arg1="${cc}" arg2="msvc"/>
<then>
<cc name="${cc}" objdir="${tgt.lib}\objs_d" outfile="${tgt.lib}\improve_debug" outtype="static"
exceptions="true" multithreaded="true" runtime="dynamic" debug="true">
<compiler extends="${cc}-compiler">
<includepath path="${tgt.interface}"/>
<includepath path="${getenv.BOOST_ROOT}\include"/>
<includepath path="${getenv.CPPUNIT_ROOT}\include"/>
<defineset >
<define name="WIN32"/>
<define name="_WINDOWS"/>
</defineset>
<compilerarg value="/W3"/>
<compilerarg value="/GR"/>
<compilerarg value="/O2"/>
</compiler>
<linker extends="${cc}-linker">
<linkerarg value="/machine:I386"/>
<!--fileset dir="${getenv.LIBS_ROOT}\lib" includes="3d_party.*"/-->
</linker>
<fileset dir="${tgt.src}">
<include name="**/*.cpp"/>
<include name="**/*.c"/>
<exclude name="exception_ex.*"/>
</fileset>
</cc>

<echo message="${ant.project.name}: AutoBuild Complete"/>
</target>

<target name="Test" depends="-Init, TestBuild" description="Perform acception testing">
<exec executable="test_main_debug.exe" dir="${tgt.bin}"
failonerror="true" vmlauncher="false" os="Windows 2000">
<env key="Path" path="${getenv.Path};${getenv.CPPUNIT_ROOT}\lib;${getenv.BOOST_ROOT}\lib"/>
</exec>
<echo message="test_main.exe Debug Version Testing Pass"/>
<exec executable="test_main.exe" dir="${tgt.bin}"
failonerror="true" vmlauncher="false" os="Windows 2000">
<env key="Path" path="${getenv.Path};${getenv.CPPUNIT_ROOT}\lib;${getenv.BOOST_ROOT}\lib"/>
</exec>
<echo message="test_main.exe Release Version Testing Pass"/>
<echo message="${ant.project.name}: Testing Complete"/>
</target>

<target name="InstallAll"
depends="CleanAll, AutoBuild, Install, Test"
description="Make a clean (re)install and test">
<echo message="${ant.project.name}: Install/Reinstall Complete"/>
</target>

</project>

在此Ant配置文件中定义了项目将引用的一些property，例如环境变量、项目的根目录路径、指定的编译器等；项目的缺省构建目标为InstallAll，它通过依赖定义，使得初始化（Init）、清除（CleanAll）、编译（AutoBuild）、安装（Install）、测试（Test）等目标依次执行；AutoBuild目标执行的cc任务，将对源码进行编译，并通过includepath设置了编译头文件的查找路径，通过linker段指定了需链接的库3d_party.lib。
本项目中各Ant配置文件的具体配置和使用，请参见Ant用户手册等参考资料，和阅读Ant配置文件本身内容。
5.1.3 Ant执行示例
Ant在命令行下执行的示例：

5.2 CruiseControl执行脚本
持续集成的过程由缺省文件名为config.xml的配置文件来定义。config.xml中确定了构建周期间隔，以及检测配置库状态、调用Ant配置文件进行构建等步骤的内容。为了实现自动化持续集成，还应编制Ant封装（wrapper）配置文件，它在调用原始Ant构建脚本（相当于将原始Ant脚本封装在内）的基础上，添加用于持续集成的更新源码目录等步骤。
5.2.1 CruiseControl项目配置文件
CruiseControl项目配置文件描述了一个集成项目（project），它由引导段（bootstrappers）、检测修改集段（modificationset）、调度段（schedule）、日志记录段（log）、发布段（publishers）、插件定义段（plugin）组成。引导段用来设置持续集成流程开始执行时相关的初始化任务，例如更新源码管理中的指定文件；检测修改集段则指定了需要检测的已置于配置管理下的目标源码，以便在检测到有源码更新后启动后续的构建步骤，例如clearcase中的某分支下、某视图中的一个目录；调度段是持续集成流程的核心部分，在此确定了构建周期间隔、休眠时段，并描述了构建的目标，目标通常指向一个Ant封装配置文件；日志记录段指定了将向发布步骤提供数据的各项日志记录；发布段则设置了对构建结果进行发布和通知的内容，例如指定报告的E-mail地址等；插件定义段用来指定CruiseControl各项功能实现对应的插件类。
5.2.2 CruiseControl配置文件示例
下面是一个CruiseControl项目的配置文件示例：

<?xml version="1.0"?>
<cruisecontrol>
<project name="peripheral_api_project">
<bootstrappers>
<currentbuildstatusbootstrapper file="currentbuild.txt"/>
</bootstrappers>
<modificationset quietperiod="30">
<clearcase branch="PCHL_V1_Dev" recursive="true"
viewpath="d:/Shared_Views/PCHL_V1_Dev/PCHL_Components/protocols_api/peripheral"/>
</modificationset>
<schedule interval="60">
<ant buildfile="proj.xml" target="cleanbuild" multiple="5"/>
<ant buildfile="proj.xml" target="masterbuild" multiple="1"/>
<pause starttime="1900" endtime="2359"/>
<pause starttime="0000" endtime="0659"/>
<pause day="saturday" starttime="0000" endtime="2359"/>
<pause day="sunday" starttime="0000" endtime="2359"/>
</schedule>
<log dir="logs/peripheral_api_project" encoding="ISO-8859-1">
<merge dir="d:/Shared_Views/PCHL_V1_Dev/PCHL_Components/protocols_api/peripheral/bin/test-results"/>
</log>
<publishers>
<currentbuildstatuspublisher file="currentbuild.txt"/>
<email mailhost="" returnaddress="xghu@" defaultsuffix=""
buildresultsurl="http://pchl1-tstn:8080/cruisecontrol/buildresults" logdir="logs/peripheral_api_project"
css="C:/Development_Tools/Building-Utils/cruisecontrol-2.1.5/reporting/jsp/css/cruisecontrol.css"
xsldir="C:/Development_Tools/Building-Utils/cruisecontrol-2.1.5/reporting/jsp/xsl">
<always address="xghu@"/>
<failure address="xghu@"/>
<map alias="huxg" address="xghu@"/>
</email>
</publishers>
<plugin name="currentbuildstatusbootstrapper"
classname="net.sourceforge.cruisecontrol.bootstrappers.CurrentBuildStatusBootstrapper"/>
<plugin name="clearcasebootstrapper"
classname="net.sourceforge.cruisecontrol.bootstrappers.ClearCaseBootstrapper"/>
<plugin name="clearcase" classname="net.sourceforge.cruisecontrol.sourcecontrols.ClearCase"/>
<plugin name="ant"
classname="net.sourceforge.cruisecontrol.builders.AntBuilder"/>
<plugin name="pause"
classname="net.sourceforge.cruisecontrol.PauseBuilder"/>
<plugin name="email"
classname="net.sourceforge.cruisecontrol.publishers.HTMLEmailPublisher"/>
<plugin name="currentbuildstatuspublisher"
classname="net.sourceforge.cruisecontrol.publishers.CurrentBuildStatusPublisher"/>
<plugin name="labelincrementer"
classname="net.sourceforge.cruisecontrol.labelincrementers.DefaultLabelIncrementer"/>
</project>
</cruisecontrol>

5.2.3 Ant封装（wrapper）配置文件示例
下面是一个Ant封装（wrapper）配置文件示例：

<?xml version="1.0"?>
<project name="peripheral_api_cc" default="masterbuild">
<property file="proj.properties"></property>
<property name="proj.dir" location="${proj.path}"/>
<target name="update" description="Update packages from ClearCase">
<ccupdate log="clearcase.log" overwrite="true" viewpath="${proj.dir}"/>
</target>
<target name="clean" description="Clean all build products">
<ant dir="${proj.dir}/build" target="CleanAll"/>
</target>
<target name="build">
<ant dir="${proj.dir}/build" target="AutoBuild"/>
</target>
<target name="rununittests" depends="build">
<ant dir="${proj.dir}/build" target="Test"/>
</target>
<target name="smoketest" depends="build">
</target>
<target name="masterbuild" depends="update,rununittests,smoketest"
description="Cruise control master build"/>
<target name="cleanbuild" depends="clean,masterbuild"
description="Cruise control clean build"/>
</project>

注意本Ant项目配置文件中主要添加了update目标，用来将proj.properties文件中定义的 proj.path=d:/Shared_Views/PCHL_V1_Dev/PCHL_Components/protocols_api/peripheral目录下的所有内容进行更新。
5.2.4 cruisecontrol执行示例
cruisecontrol在命令行下执行的示例：

6 集成构建基本流程
6.1 概述
在构建开始前，构架师应当确定项目初步的基本源码包组织结构，和包之间的依赖关系等，并定义项目统一的构建目录结构。构架师还应指导集成员制定集成构建计划，以确定集成的内容、构建周期和日程表。在项目构建阶段初期，构架师应密切参与或直接承担集成的工作，从而为项目源码结构确定演进的方向；其后还应给予足够的关注，并经常性地修订和维护源码目录结构，以便在整体上把握项目源码和最终交付工件。
随后的每个构建周期都包含：实施—〉单元测试—〉提交—〉集成—〉冒烟测试的基本过程。
6.2 集成过程说明
实施员在私有的开发工作站上，按照项目统一的源码结构组织其单元开发目录，完成源码和单元测试代码的编制，并在集成员的指导或帮助下编制私有构件的自动化构建脚本（为了编码和调试方便，实施员通常选择GUI集成环境进行编译，这种IDE内部格式的编译项目既不标准，也不适于集成构建使用，因此维护额外的构建脚本是必要的），在构建成功后向集成流（Stream）提交成果（delivery）；在结束提交之前，实施员应尽可能在本机尝试集成构建，以验证构建脚本、单元测试代码与源码可用，之后完成提交。
集成员在集成服务器获取各实施员提交的构件源码，先根据需要调整各源码结构以解决构件间的编译冲突，再编制或修改集成构建脚本，加入集成构造目标（target），并增添对新增单元构建脚本的调用，以实施统一的批量编译、链接，最终生成集成构造；为了实现并验证集成目标，可能需要修改源码，增加或修改用于集成测试的代码，和进行集成调试等，这可由集成员或实施员来完成此项工作；集成员开始执行干净的集成构建（为了实现持续集成，可以配置操作系统任务，定时在夜间自动执行构建任务），生成可执行交付工件（也包括静态或动态链接库等）；为了验证构建步骤成功，随后需要执行冒烟测试，其原则是尽可能利用已有的测试代码，通过在构建脚本中调用它们，实现自动化的冒烟测试（对于GUI目标系统而言，实现自动化较为困难，往往依靠手工完成冒烟测试）。
集成员或配置管理员为构建成功的一个构造建立基线；测试员将在测试工作站上对此基线进行集成测试；实施员则可能在各自的开发工作站上，重设开发基线于此基线上（rebase），以在新的基础上继续后续开发工作。
6.3 持续集成过程说明
集成员通过配置CruiseControl工具，可以将部分较为简单、不需要人工干预和希望经常重复执行的集成工作交给工具来自动完成。集成员可以配置多个持续集成项目，包括若干个多人同时在开发的子构件、最终发布的集成包等。
CruiseControl在活动时段，循环执行各构建周期，包含：引导初始化—〉检测源码变化—〉集成构建—〉单元测试—〉发布构建和测试结果等步骤。
每当实施员在私有开发工作站上，将源码检入（Checkin）、加入源码控制（Add to Source Control）、或者向集成流（Stream）提交成果（delivery）时，CruiseControl在随后的构建周期循环中，将通过检测源码变化步骤检测到这一变化，CruiseControl此时会等待预定的间隔，看看是否有新的源码变化出现，避免实施员批量检入或加入源码控制时遗漏后续变更；CruiseControl开始调用Ant封装（wrapper）配置文件执行构建，它首先更新目标源码目录下的所有内容（调用ClearCase ccupdate指令），以同步变化的源码，再进行编译、链接，完成预定的冒烟测试，并将结果记录到相应的日志中；CruiseControl在构建完成后，通过e-mail将成功或失败的结果通知提交源码变更的实施员、以及指定的其他人员，并生成构建报告网页，相关人员通过e-mail接受通知的同时，也可以登陆CruiseControl的发布网页来浏览构建报告详细信息。

7 构件的集成原则
7.1 生产者与消费者
不同构件的开发者之间通常处于一种生产者与消费者的关系，即生产者交付工件提供给消费者使用。生产者交付的工件类型有：原始（Original）工件（源码、构建脚本、配置文件等），中间（Derived）工件（Obj文件、lib库等），最终产品（Product）工件