TeamCity : Build 基本配置

前文中我们在 TeamCity 中创建了一个项目 HelloApp，并在这个项目中创建了一个名为 HelloAppDailyBuild 的Build 用来编译 demo 程序。本文我们将详细介绍 Build 中的基本配置。下图是 Build 基本配置的概览：

Name

Build 配置的名称。

Build configuration ID

Build configuration ID: 在系统中标识该 Build 配置，自动生成的规则是：项目名称 +下划线 + build 配置名称。
比如要导航到一个 build 配置的页面， URL为：
http://xxxx/viewType.html?buildTypeId=HelloApp_HelloAppDailyBuild
最后一个参数就是 Build configuration ID。这个ID非常重要，我们使用 urls, REST API 向服务器请求信息时，都要使用它。在服务器上，它还作为一些配置文件的目录名称。

Description

作为描述信息，Description 会显示在 build name 的后面：

Build number format

我们可以为 build number 指定一个格式。不同的用户总是有不同的需求，如果您想要 build number 显示为一个自增的整数，就可以把 build number 指定为 %build.counter%。build.counter 是由 TeamCity 来维护的，您也可以手动指定它。设置为 %build.counter% 的 build number format 看起来是这个样子：

我们还可以指定为：
%build.vcs.number.<VCS_root_name>%
或者
%property.name%
这些都是 TeamCity 维护的一些变量。一个完整的例子看起来像这个样子 :
1.0.%build.counter%.%build.vcs.number.My_Project_svn%
注意，最好是保持 build number 的唯一性。所以应该把 build counter 加入到 build number format 中。
如果想用日期做 build number 该怎么办，如果还要显示 build 在每天中的序号呢？遗憾的是默认情况下我们没办法完成这样的需求，但是 TeamCity 提供了很好的扩展能力。我们可以写一个插件了实现这样的功能：

Build counter

Build 次数的计数器，您也可以手动设置它。但您做好清楚的知道自己在干什么。

Artifact paths

收集 build 产物需要通过指定 Artifact paths 来完成。我们可以把产物的路径分为两类：准确的路径和通过模式匹配获得的路径。

准确的路径

如果您知道 build 产物的准确路径，就可以直接写产物的路径。
还可以通过 teamcity 的工具进行选择：

通过模式匹配来指定路径

可以通过新行或者逗号来分隔不同的模式匹配规则如：

[+:]source [=> target]

这个规则把满足条件的文件加入到产物中。

-:source [=> target] 

这条规则则是把满足条件的文件从产物中移除。

方括号围起来的参数是可选的。规则根据右面的部分进行分组，根据出现的顺序依次起作用，如：

+:**/* => target_directory
-:**/folder1 => target_directory

表示除了 folder1 下的内容，把其他所有内容加入到产物中。

下面是详细的格式 :

file_name|directory_name|wildcard [ => target_directory|target_archive ]

file_name 指定产物文件相对于 build checkout directory 的路径。
directory_name 指定某个目录相对于 build checkout directory 的路径。目录下的所有文件和子目录都会被作为产物。产物中文件在目录中的结构保持不变。但是目录 directory_name 本身并不包含在产物中。
wildcard(通配符) 收集符合 Ant-like 的通配符匹配的文件作为产物 (仅支持 "*" 和 "**")。通配符要出现在相对于 build checkout directory 的路径中。符合条件的文件在产物中的路径会保持原来的路径结构。
还可以在收集产物的规则中使用参数。参数可以是 TeamCity 内置的变量也可以是用户自己定义的变量。

=> 后面的部分是可选的。=> 后面跟的目录名可以用来指定产物文件所存放的目录。
如果没有设置目标目录，那么产物会被放置在 build 产物的根目录下。
注意，目标路径不能是绝对路径。非相对的路径会在build时产生错误。
target_directory 收集的产物文件会被放到这个目录下。
target_archive 把产物打包后归档文件的路径。支持的归档文件格 式有 .zip，.7z，.jar，.tar.gz，.tgz。

下面是一些常用的例子：

install.zip
// 把 build checkout directory 目录下的所有文件放入压缩包 install.zip 作为产物。

dist
// 收集 build checkout directory\dist 目录下的所有内容作为产物。

target/*.jar
// 收集 build checkout directory\target 目录下的所有 jar 文件作为产物。

target/**/*.txt => docs
// 收集 build checkout directory\target 目录及其子目录下所有的 .txt 文件 作为产物。并把这些文件全部放入目标目录 docs 中。

reports => reports, distrib/idea*.zip
// 把 build checkout directory\reports 目录中的内容放入产物中的 reports 目录下。
// 把 build checkout directory\distrib 目录下符合 idea*.zip 条件的文件放到产物的根目录下。

// 我们还可以指定产物在 zip 归档文件中的位置，如：
results\result1\Dir1\Dir2 => archive.zip!results/result1/Dir1
// Dir2 目录中的内容将添加到归档文件中的 results/result1/Dir1 目录下。

// 产物中相同的归档文件名称可以被使用多次，如:
+:*/*.html => report.zip
+:*/*.css => report.zip!/css/
-:*/*.txt => report.zip

Build options

Build options 为我们提供了另外一些功能。

Hanging Build Detection

探测挂起的 build，TeamCity 能够探测可能是被挂起的 builds。
什么样的 build 被认为是被挂起的 build 呢？当一个 build 的执行时间明显的超过了系统估计的平均执行时间，并且在超过预估时间后 build 也没有发出过消息，此时就认为 build 处于挂起状态。TeamCity 会把已经运行过的 build 时间取平均值，从而估算出平均运行时间。当我们订阅通知时 TeamCity 系统的通知时，可以把 挂起作为一个条件。这样当挂起发生时我们就会收到通知。

Allow Triggering Personal Builds

这个功能允许用户使用未提交到代码库的代码做build，但是需要开发工具的支持。

Enable Status Widget

启用状态部件,这个选项让我们可以获得最后一次 build 的信息，而不需要要使用认证信息。需要注意的是，除了最后一次 build 的信息，我们其实还可以获得任何一次 build 的信息。但是仅限于获得 success/failure/internal error/cancelled 这几种信息。
我们可以通过不同的方式来获得信息，比如 HTML status widget 和 REST API。
下面我们看一下如何把 Build 信息嵌入到您的网页上。
先启用 “enable status widget”:

创建一个 html 网页，在 head 中加入：

<style type="text/css">
@import "<TeamCity_server_URL>/css/status/externalStatus.css";
</style>

在 body 中加入：

<script type="text/javascript" src="<TeamCity_server_URL>/externalStatus.html?js=1&buildTypeId=xxx">
</script>

请用您的 TeamCity 服务器地址更换上面字符串中的占位符，并且用有意义的 Build configuration ID 替换 xxx。然后在浏览器中打开看看：

Limit Number of Simultaneously Running Builds

设置一个 build 可以同时运行的最大数。
主要是防止所有的 build agent 同时被一个 build 全部用光。