keas.build 0.4.1

安装keas.build的发布版本

您可以使用 easy_install 获取最新版本

$ easy_install keas.build

安装keas.build的开发版本

检出代码

$ svn checkout svn://svn.zope.org/repos/main/keas.build/trunk keas.build
$ cd keas.build

运行引导脚本和buildout

$ python bootstrap.py
$ ./bin/buildout

运行 build-package 脚本

一旦安装完成，您应该能够运行 build-package 脚本。（开发安装中位于 ./bin/build-package）

$ build-package
Usage: build-package [options]

Options:
  -h, --help            show this help message and exit
  -c FILE, --config-file=FILE
                        The file containing the configuration of the project.
  -q, --quiet           When specified, no messages are displayed.
  -v, --verbose         When specified, debug information is created.
  -d, --use-defaults    When specified, no user input is required and the defaults are used.
  -o, --offline-mode    When set, no server commands are executed.
  -n, --next-version    When set, the system guesses the next version to generate.
  -b BRANCH, --use-branch=BRANCH
                        When specified, this branch will be always used.
  -i BRANCHES --independent-branches=BRANCH1 BRANCH2,
                        When specified, the system guesses the next version from all this branches.
  --no-upload           When set, the generated configuration files are not uploaded.
  --no-branch-update    When set, the branch is not updated with a new version after a release is created.

假设

首先，我们需要从keas.build对软件包布局方式的一些假设开始。当同时开发多个软件包时，通常有道理使您的子版本仓库布局如下：

SVNROOT/packages/
    branches/
        Twollo-0.x/
            ...
        Twollo-1.x/
            twollo.integration/
            twollo.rest/
            twollo.utils/
            twollo.web/
    tags/
        twollo.integration-1.2/
        twollo.integration-1.3/
        twollo.web-1.7/
        twollo.web-1.8/
        twollo.web-1.9/
        ...
    trunk/
        twollo.integration/
        twollo.rest/
        twollo.utils/
        twollo.web/

需要注意的是，每个软件包都没有自己的分支/标签/树干/目录，而只有一个整个“项目”的集合。

定义项目配置文件

在您真正使用 build-package 脚本之前，您必须定义一个配置文件。项目配置文件使用INI [1] 文件格式。每个项目配置文件都必须有一个 [build] 部分。Twollo的项目配置文件可能看起来像这样：

# Twollo.cfg

[build]
name = Twollo  #this has nothing to do with the twollo package namespace
version = +
template = Twollo-Release-Template.cfg
package-index = https://build.twollo.com/eggs/
package-index-username = someuser
package-index-password = somepass
buildout-server = https://build.twollo.com/buildouts/
buildout-server-username = someuser
buildout-server-password = somepass
svn-repos = https://svn.twollo.com/svn/packages/
svn-repos-username = somesvnuser
svn-repos-password = somepass
packages = twollo.integration
           twollo.web
           twollo.rest
           twollo.utils

让我们逐一介绍 Twollo.cfg 的 [build] 部分中的每个设置。

• 项目名称 - 这是项目的名称。可以是您想要的任何名称，与组成项目的软件包无关。名称将成为生成构建配置文件的一部分。

• 版本 - 在发布新版本的项目时使用的版本。版本号将成为生成构建配置文件文件名的一部分。

  • 使用 + 作为版本号将简单地增加项目从已发布的版本中的版本号。

• 模板 - 这是用于所有部署的基础构建配置文件。当创建新的项目发布时，[versions]部分将自动更新为twollow.*每个软件包的正确版本。稍后详述。

• 标签布局 - 从flat或subfolder中选择

  • flat 标签将在svn中以/path/tags/package-version创建。这是默认设置。

  • subfolder 标签将在svn中以/path/tags/package/version创建。

• 上传类型 - 从internal或setup.py中选择

  • internal 使用以下凭据将软件包上传到启用了WebDAV的Web服务器。这是默认设置。（实际上执行了python setup.py sdist并上传了结果）

  • setup.py 执行python setup.py sdist register upload，该命令应该负责上传，因此不会执行其他操作。

• 包索引 - 应将每个twollow.*软件包生成的eggs上传到启用了WebDAV的Web服务器的URL。如果upload-type为internal，则用于上传。还用于检查/获取软件包的现有版本。

• 包索引用户名 - 访问WebDAV服务器的用户名

• 包索引密码 - 访问WebDAV服务器的密码

• buildout上传类型 - 从webdav、local或mypypi中选择

  • webdav 使用WebDAV协议将生成的构建文件上传到由buildout-server指定的URL。

  • local 仅生成构建文件，不上传它们。如果提供了buildout-server，则构建文件将复制到该文件夹。

  • mypypi 将生成的构建文件上传到由buildout-server指定的URL。该URL应指向mypypi上传页面。（例如：http://yourhost/++projects++/）

• buildout-server - 应将生成的构建文件上传到启用了WebDAV的Web服务器的URL。如果buildout-upload-type为local，则这是本地文件系统上的路径。构建文件将复制到该文件夹。如果未提供，则在发布软件包后停止处理。

• buildout-server用户名 - 访问WebDAV服务器的用户名

• buildout-server密码 - 访问WebDAV服务器的密码

• svn-repos - 存储所有源代码（包括发布标签）的subversion仓库的URL。

• svn-repos-username - 用于URL仓库的用户名。使用命令行选项 --force-svnauth 可强制所有svn操作使用此凭据。否则将使用缓存的身份验证。

• svn-repos-password - 用于URL仓库的密码。

• hash-config-files - 根据文件内容添加哈希到相关的配置文件名。

• packages - 项目中包含的软件包列表。这些是在svn仓库中的软件包，并且应该与其他软件包一起发布。

定义发布模板

如前一小节所示，Twollo.cfg 指的是名为 Twollo-Release-Template.cfg 的文件。这只是一个基本的构建配置。除了这些，我们还可以定义不同的配置数据，如定义阶段和生成部分。这些部分可以在产品部署中用作额外的（共享）变量。对于Twollo项目，它可能看起来像这样

# Twollo-Release-Template.cfg

[buildout]
extends = http://download.zope.org/zope3.4/3.4.0/versions.cfg
parts = test
find-links = https://build.twollo.com/eggs/

[test]
recipe = zc.recipe.testrunner
eggs = twollo.web
       twollo.integration
       twollo.utils
       twollo.rest

[twollo-app]
recipe = zc.zope3recipes:app
servers = zserver
site.zcml = <include package="twollo.web" file="app.zcml" />
eggs = twollo.web

[zope3]
location =

[stage]
memcached = 127.0.0.1:11211

[production]
memcached = 10.0.0.1:11211

当Twollo项目发布新版本时，会在配置文件中添加一个 [versions] 部分，其中包含所有正确的 twollow.* 版本。

定义多个部署配置

每次发布项目时，您可能希望为可能拥有的所有不同的部署环境生成不同的buildout配置文件。例如，您可能有三个不同的环境：开发、测试和质量保证（QA）、生产。这些被称为变体。每个环境可能需要应用在不同的端口上运行，具有不同的日志级别，或者有其他小的差异。

我们可以通过向 Twollo.cfg 文件添加额外的部分来轻松生成额外的配置变体

# Twollo.cfg

[Development]
template = Twollo-Instance-Template.cfg
vars = stage
port = 9080
logdir = /opt/twollo/dev/logs
install-dir = /opt/twollo/dev
loglevel = debug
cache-size = 1000

[QA]
template = Twollo-Instance-Template.cfg
vars = stage
port = 9082
logdir = /opt/twollo/qa/logs
install-dir = /opt/twollo/qa
loglevel = info
cache-size = 1000

[Production]
template = Twollo-Instance-Template.cfg
vars = production
port = 8080
logdir = /var/log/twollo
install-dir = /opt/twollo/
loglevel = warn
cache-size = 200000

然后我们可以有一个单独的 Twollo-Instance-Template.cfg 文件，它使用python的内置字符串模板来访问在 Twollo.cfg 中设置的变量。对于Twollo项目，它可能看起来像这样

# Twollo-Instance-Template.cfg

[buildout]
parts += twollo
directory = %(install-dir)s

[database]
recipe = zc.recipe.filestorage

[twollo]
recipe = zc.zope3recipes:instance
application = twollo-app
zope.conf =

  <product-config memcached>
    memcached %(memcached)s
  </product-config>

  <zodb>
    cache-size %(cache-size)s
    <filestorage>
      path ${database:path}
    </filestorage>
  </zodb>

  <server>
    type WSGI-HTTP
    address %(port)s
  </server>

  <eventlog>
    level %(loglevel)s
    <logfile>
      formatter zope.exceptions.log.Formatter
      path %(logdir)s/twollo.log
    </logfile>
  </eventlog>

  <accesslog>
    <logfile>
      level info
      path %(logdir)s/twollo-access.log
    </logfile>
  </accesslog>

如你所见，Twollo.cfg使用了额外的变量（阶段、生产），这使得在发布模板中定义大量共享属性并将其用于实例模板变得非常简单。请注意，Python配置解析器的副作用是，您将继承通过（buildout）扩展加载的模板中定义的重复部分中的参数。

发布项目

一旦创建了所有必要的配置文件，您就可以进行第一次项目发布。这正是 build-package 脚本发挥作用的地方。第一次运行 build-package 脚本时，您需要传递的唯一选项是配置文件。

build-package 脚本将提示您为Twollo.cfg项目将发布的每个软件包的版本信息。您与脚本的第一次交互可能看起来像这样

$ build-package -c Twollo.cfg --quiet
Version for `twollo.integration` : 1.0.0
The release twollo.integration-1.0.0 does not exist.
Do you want to create it? yes/no [yes]: yes
Version for `twollo.rest` : 1.0.0
The release twollo.rest-1.0.0 does not exist.
Do you want to create it? yes/no [yes]: yes
Version for `twollo.utils` : 1.0.0
The release twollo.utils-1.0.0 does not exist.
Do you want to create it? yes/no [yes]: yes
Version for `twollo.web` : 1.0.0
The release twollo.web-1.0.0 does not exist.
Do you want to create it? yes/no [yes]: yes

下次发布时，您可以为 build-package 设置 -n 标志以自动猜测下一个应发布的版本。它首先查找给定软件包的所有发布标签，并找到给定软件包主干的最后更改修订版。如果自上次发布以来给定软件包有任何代码更改，它将自动增加最不重要的版本号。如果没有发生更改，它将选择最新的现有发布。

您还可以使用 -d 标志让 build-package 在创建新版本之前不提示您。

如果您需要从一个特定的分支创建新版本，您可以使用 -b 选项。例如，如果Twollo-1.x分支已经进行了错误修复，我们可以使用以下方式使用此分支的代码创建一个新版本：

$ build-package -c Twollo.cfg -nb Twollo-1.x

当计算新包的版本时，即使您已经创建了2.x版本，它们也将沿着1.x线进行版本控制，这是通过分析分支名称来实现的。

在使用 -n 和 -d 在以版本号结尾的分支上时，需要注意的一个问题是您需要拥有与分支版本匹配的包版本。例如，拥有一个分支：branches/twollo-1.9 将意味着像 twollow.web-1.9.x 和 twollow.utils-1.9.x 等包。您在从主干发布包时也应了解这一点。很可能您将在主干上驱动开发，并为稳定版分支出来。在这种情况下，分支上的包版本应保持一致。

安装已发布的项目

keas.build 还附带了一个非常简单的安装脚本，可以用于快速安装已发布项目的任何变体

$ install --help
Usage: install [options]

Options:
  -h, --help            show this help message and exit
  -u URL, --url=URL     The base URL at which the releases can be found.
  -p PROJECT, --project=PROJECT
                        The name of the project to be installed.
  -V VARIANT, --variant=VARIANT
                        The variant of the project to be installed.
  -v VERSION, --version=VERSION
                        The version of the project to be installed.
  -l, --latest          When specified, the latest version will be chosen.
  --username=USER       The username needed to access the site.
  --password=PASSWORD   The password needed to access the site.
  -b PATH, --buildout-path=PATH
                        The path to the buildout executable.
  --quiet               When specified, no messages are displayed.
  --verbose             When specified, debug information is created.

例如，要安装 Twollo 项目的最新 QA 版本，您将运行

$ install -u https://build.twollo.com/buildouts/ -p Twollo -V QA –latest

创建辅助脚本

有时很难记住构建项目所需的所有命令行选项。幸运的是，创建一些仅为您设置一些默认值的辅助脚本非常简单。

例如，要创建一个 build-twollo 脚本，您将以下内容添加到构建配置文件中

[build-twollo]
recipe = zc.recipe.egg
eggs = keas.build
scripts = build=build-twollo
initialization =
    sys.argv[1:1] = ['-c', 'Twollo.cfg']

作为另一个示例，您可以创建一个 install-twollo-dev 脚本，它将自动安装最新的开发版本

[install-twollo-dev]
recipe = zc.recipe.egg
eggs = keas.build
scripts = install=install-twollo-dev
initialization =
    sys.argv[1:1] = ['-u', 'http://build.twollo.com/buildouts/',
                     ' --username', 'someuser', '--password', 'somepass',
                     '-p', 'Twollo', '-V', 'Development', '--latest']

可能性是无限的！

0.4.1 (2013-11-28)

• 错误修复：防止生成不良的构建选项键/值分隔符。使用 += 而不是用于例如构建部分选项的 + =。否则，由于 buildout 2.0，它将失败。

0.4.0 (2013-11-24)

• 功能：在部署模板部分实现了新的 vars 参数。新的 vars 参数可以用来定义发布模板部分。如果已定义，构建过程将应用此部分的所有参数，就像它们是项目部分的一部分一样。这允许在一个项目定义中继承大量的参数，而不是在每一个项目中定义它们。如果您有一个阶段和许多生产变体，并且实例使用配置数据（如数据库设置）并且您需要共享它们，这很有用。对于此类用例，您可以简单地定义一个阶段和一个生产部分，并定义所有共享参数，并在产品部署设置中使用正确的 vars 部分定义。请参阅 index.txt 中的 memcached 示例。

  注意，这个新的产品部署模板 vars 参数可能成为您现有设置的问题，如果您使用与您的部分模板中定义的部分名称相似的值作为 vars 参数。

0.3.1 (2013-09-25)

• 改进：添加了 default-package-version 命令行选项，以避免在新的包上交互式提问。

0.3.0 (2012-12-27)

• 功能：添加了 -i –independent-branches 选项。此选项将强制检查最后一个发布是否是从我们正在发布的同一个分支发布的。如果您在一个与主干独立的分支中开发新的软件生成，则需要这样做。keas.build 的早期版本只能处理分支发布作为错误修复发布，并且没有确保我们不混合主干和分支发布。现在，通过使用 -i 选项，我们强制所有发布的包都将基于当前的主干或分支（-b trunk，branch）创建或重用。

• 增加了更多日志信息，以便在查找或跳过下一个版本时更简单地了解正在发生的事情

0.2.2 (2011-08-29)

• 改进：添加了 current-datetime、current-date、current-time 变量

0.2.1 (2011-04-07)

• 修复 RawConfigParser 使用问题，它通过将所有选项值转换为小写来破坏选项值。

0.2.0 (2011-04-06)

• 将版本升级到 ZTK 1.1

• 改进：将 SVN 仓库信息添加到项目配置文件中。是的，我知道这可以在任何时候检查，但添加这个可以节省很多时间。

• 改进：添加 hash-config-files 选项

0.1.8 (2010-05-11)

• 修复：不要使用 python setup.py 进行注册

• 修复：升级 setuptools 和 zc.buildout 版本

• 修复：0.1.7 版本的 tar.gz 文件已损坏

0.1.7 (2010-04-26)

• BUGFIX：依赖配置文件收集破坏了主配置文件中的版本限制

• 改进：在检查包版本时支持类似 PYPI 的简单索引

• 改进：检查依赖配置，将所有内容上传到服务器。

• 改进：添加 --force-version 选项。

• 改进：将版本添加到 SVN 日志注释中。这使生活更轻松（至少在使用 TortoiseSVN 时如此）

• 改进：添加 --force-svnauth 选项。

• 改进：将 --directory 选项添加到 install。

0.1.6 (2009-11-2)

• 改进：在确定分支的发布版本时，支持以 .x 结尾的分支名称，如 MyProject-0.3.x

0.1.5 (2009-10-16)

• 改进：在安装时，将用户名和密码添加到 buildout 获取的 .cfg 文件的 URL 中。希望 buildout 不会留下密码。

• 改进（？）或修复：删除用于 SSH 部署的 twisted 依赖项

• 改进：删除对 lxml 的依赖。现在我们只使用 Python 内置的 xml 库。

• 改进：添加 buildout-upload-type 选项。请参阅文档以获取更多信息

• 错误修复：多行模板选项值在解析时崩溃

• 错误修复：re 不喜欢来自 BeautifulSoup 的非文本参数

• 改进：将 --timeout 选项添加到安装中

• 改进：添加了 mypypi buildout 文件上传支持

• 错误修复：回滚到完整源树的检出

0.1.4 (2009-10-01)

• 错误修复：安装器脚本在缺少末尾 / 的 -u 选项时崩溃

• 错误修复：安装器脚本在找不到任何变体时崩溃

• 改进：构建包时不再检出整个分支，只是为了更新 setup.py 文件中的新版本号。相反，只检出顶级目录。

• 错误修复：当变体配置缺少模板所需的信息时，项目构建脚本会崩溃。现在会打印出有用的错误消息，并且直到所有文件都成功创建后，不会上传任何文件。

• 错误修复：在命令行上按下 Ctrl+c 时，不再会导致 KeyboardInterrupt 跟踪信息被打印出来。

• 错误修复：在运行安装程序时，如果 buildout 命令提示用户输入，安装程序将不再消耗提示。

0.1.3 (2009-09-30)

• 首次公开发布。

0.1.1（内部版本）

• 错误修复：如果指定了没有发布的项目变体，构建脚本现在会优雅地退出并显示人类可读的错误消息。

0.1.0（内部版本）

• 首次发布。