p01.build 0.8.1

示例

以一个名为MyServer的Web应用程序为例

• p01.cdn - 如CSS和JavaScript文件之类的CDN资源

• p01.core - 提供您的应用程序模型的软件包

• p01.web - p01.core 包的Web前端，并使用 p01.cdn 资源

使用 p01.build，您将能够一致地管理这些Python包及其任何数量的部署配置的生命周期

• 允许您定义一个项目，该项目是一组相互依赖的蛋包，通常一起发布。

• 在必要时自动部署每个包的新蛋包发布。

• 将新蛋包上传到私有蛋包仓库（见 mpypi）。

• 生成带有正确组合蛋包的版本化buildout配置文件。

• 将buildout配置文件上传到私有配置服务器。（mypypi内置了对此类上传的支持）

• 将依赖的buildout配置文件上传到私有配置服务器（通过检查extends=链，mypypi支持此类上传）

安装

使用 easy_install 安装 deploy 脚本

$ easy_install p01.build

您还可以安装 p01.build 的开发者版本

检出代码

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

运行引导脚本和buildout

$ python bootstrap.py
$ ./bin/buildout

发布

一旦您有了可用的开发者版本，您应该能够运行 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. This is important to set if
                        you release from different branches. It will prevent
                        that a package get used which was released from
                        another branch !!!
  --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.
  -s PATH, --storage-path=PATH
                        Store the generated files in that folder and not in
                        the global root directory. This is just for provide
                        a clean setup and prevent to put all the generated config files

入门

假设；首先，我们需要从 p01.build 对包布局方式的假设开始。当同时开发多个包时，通常有意义的是将您的子版本库布局如下

SVNROOT/MyServer/packages/
    branches/
        Branch-0.x/
            ...
        Branch-1.x/
            p01.cdn/
            p01.core/
            p01.web/
    tags/
        p01.cdn-0.5.0/
        p01.core-0.5.0/
        p01.core-0.5.1/
        p01.web-0.5.0/
        p01.web-0.5.1/
        p01.web-0.5.2/
        ...
    trunk/
        p01.cdn/
        p01.core/
        p01.web/

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

项目设置

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

# MyServer.cfg

[build]
name = MyServer  # this has nothing to do with the package namespace
version = +
template = release.cfg
tag-layout = subfolder
upload-type = setup.py
package-index = https://pypi.projekt01.ch/private
package-index-username = username
package-index-password = password
buildout-server = https://pypi.projekt01.ch/++projects++/
buildout-server-username = username
buildout-server-password = password
svn-repos = https://svn.projekt01.ch/svn/myserver/packages/
svn-repos-username = somesvnuser
svn-repos-password = somepass
svn-trust-server-cert = 1
packages = p01.cdn
           p01.core
           p01.web

让我们来了解一下 MyServer.cfg 的 build 部分的每个设置。

• name - 这是项目的名称。它可以是你想要的任何东西，与构成项目的包无关。名称将是生成buildout配置文件的组成部分。

• version - 这是创建项目新发布时要使用的版本。版本号将成为生成buildout配置文件文件名的组成部分。

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

• template - 这是用于所有部署的基础buildout配置文件。当创建新的项目发布时，[versions] 部分将自动更新为 p01.* 每个包的正确版本。关于这一点稍后会有更多介绍。

• tag-layout - 选择 flat 或 subfolder

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

  • subfolder 标签将在svn中创建为 /tags/package/version

• upload-type - 选择 internal 或 setup.py

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

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

• upload-format - 使用作为 -formats 参数的 setup.py 发布格式选项。从 zip、gztar、bztar、ztar 或 tar 中选择。注意，只允许一个格式选项。

• package-index - 生成 eggs 的每个 p01.* 包应上传到的启用 WebDAV 的 Web 服务器 URL。[2] 仅当 upload-type 是 internal 时才使用。还用于检查/获取包的现有版本。

• package-index-username - 访问 WebDAV 服务器的用户名

• package-index-password - 访问 WebDAV 服务器的密码

• buildout-upload-type - 从 webdav、local 或 mypypi 中选择

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

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

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

• buildout-server - 应上传生成的 buildout 文件的启用 WebDAV 的 Web 服务器 URL。如果 buildout-upload-type 是 local，则这是本地文件系统上的路径。Buildout 文件将被复制到该文件夹。如果没有提供，则在发布包后将停止进程。

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

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

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

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

• svn-repos-password - URL 仓库的密码

• svn-trust-server-cert - 信任 svn 服务器证书

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

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

定义发布模板

正如我们在上一节中看到的，MyServer.cfg 指的是名为 release.cfg 的文件。这只是一个基本 buildout 配置。除了这个之外，我们还可以定义不同的配置数据，如定义在阶段和生成部分中。这些部分可以用作产品部署中的附加（共享）变量。对于 MyServer 项目，它可能看起来像这样

# release.cfg

[buildout]
extends = http://download.zope.org/zope3.4/3.4.0/versions.cfg
parts = test
find-links = https://pypi.projekt01.ch/private

[test]
recipe = zc.recipe.testrunner
eggs = p01.cdn
       p01.core
       p01.web

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

[zope3]
location =

[stage]
memcached = 127.0.0.1:11211

[production]
memcached = 10.0.0.1:11211

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

定义多个部署配置

每次您发布一个项目时，您可能需要为可能的所有部署环境生成不同的构建配置文件。例如，您可能有三个不同的环境：开发、预发布和生产。这些被称为变体。每个环境可能需要应用程序在不同的端口上运行、不同的日志级别，或者有其他细微的差异。

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

# MyServer.cfg

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

[Stage]
template = instance.cfg
vars = stage
port = 9082
logdir = /opt/myserver/stage/logs
install-dir = /opt/myserver/stage
loglevel = info
cache-size = 1000

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

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

# instance.cfg

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

[database]
recipe = zc.recipe.filestorage

[server]
recipe = zc.zope3recipes:instance
application = server-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/server.log
    </logfile>
  </eventlog>

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

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

发布项目

一旦您创建了所有必要的配置文件，您就可以发布您的第一个项目。这就是build-package脚本的用武之地。第一次运行build-package脚本时，您需要传入的唯一选项将是配置文件。

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

$ build-package -c MyServer.cfg --quiet
Version for `p01.cdn` : 1.0.0
The release p01.cdn-1.0.0 does not exist.
Do you want to create it? yes/no [yes]: yes
Version for `p01.core` : 1.0.0
The release p01.core-1.0.0 does not exist.
Do you want to create it? yes/no [yes]: yes
Version for `p01.web` : 1.0.0
The release p01.web-1.0.0 does not exist.
Do you want to create it? yes/no [yes]: yes

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

您还可以使用-d标志来使build-package在创建新发布之前不提示您。

如果您需要从特定的分支创建新发布，您可以使用-b选项。例如，如果对MyServer-1.x分支进行了错误修复，我们可以使用以下方法创建新发布，使用此分支的代码

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

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

使用-n和-d在以版本号结束的分支上时有一些注意事项，即您需要确保包版本与分支版本匹配。例如，有一个分支：branches/myserver-1.9将假定包如p01.core-1.9.x和p01.web-1.9.x等。在发布主分支的包时也应注意到这一点。很可能会在主分支上驱动开发，并为稳定分支进行分支。在这种情况下，分支上的包版本应保持一致。

安装已发布的项目

p01.build 还附带一个非常简单的安装脚本，可用于快速安装已发布项目的任何版本。

$ deploy --help
Usage: deploy [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.
  --directory=FOLDER    Override installation target folder
  -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.
  --timeout=TIMEOUT     Socket timeout passed on to buildout.

例如，要安装 MyServer 项目的最新 Stage 版本，您将运行：

$ deploy -u https://pypi.projekt01.ch/++projects++/ -p MyServer -V Stage –latest

创建辅助脚本

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

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

[uploads]
recipe = p01.recipe.setup:mkdir
path = ${buildout:directory}/parts/uploads

[build-myserver]
recipe = zc.recipe.egg
eggs = p01.build
scripts = build=build-myserver
initialization =
    sys.argv[1:1] = ['-c', 'MyServer.cfg',
                     '-o', '${buildout:directory}/parts/uploads']

可能性是无限的！

0.8.1 (2021-01-22)

• bugfix: 修复导致发布过程损坏的错别字

0.8.0 (2021-01-22)

• 增加了对 python3 的支持

0.7.1 (2018-09-04)

• feature: 增加了 svn-trust-server-cert 选项，用于信任 svn 服务器证书

0.7.0 (2018-05-13)

• bugfix: 调整 BeautifulSoup 依赖项，切换到 beautifulsoup4

0.6.0 (2018-02-10)

• feature: 增加了 uploadFormat 构建选项，用于构建 zip 或 tar.gz 发布文件。除了项目设置文件中的 uploadType 选项外，使用新的 uploadFormat 选项。使用 zip、gztar、bztar、ztar 或 tar 之一。注意，只允许一个格式选项。

0.5.1 (2015-08-26)

• feature: 增加了 -s、–storage-path 选项，它定义了一个目录，在该目录中我们在上传到 pypi、webdav 等之前存储创建的文件。这防止所有文件都生成在包根目录中。

• cleaup code，get rid of pkg_resources.parse_version deprecation message. Ported the parse_version method for now.

• 删除 p01/build/install.py 并将代码移动到 p01/build/deploy.py。将 deploy 的入口点切换到 deploy.py

0.5.0 (2015-04-15)

• bugfix: 将给定的构建配置部分内容按原样解析，并且仅使用 rstrip 继续行。这允许在脚本内容等部分中使用任何内容，而不会出现任何意图问题。解析概念与 zc.buildout > 2.0 中使用的类似且兼容。

• 此软件包提供了一个基于软件包版本的产品构建、发布和安装系统，该系统基于 zc.buildout。核心概念取自 keas.build，并提供相同的配置语法。主要区别在于，我们不将安装脚本设置为 install，因为在 ubuntu 上使用 gnu install 脚本调用（pycairo、python waf install）存在冲突，该脚本由 popen 脚本（p01.recipe.setup:popen）使用。此实现将安装脚本作为 deploy 入口点提供。您只需在服务器上使用 easy_install p01.build 安装部署脚本即可。有关更多信息，请参阅 p01/build/README.txt。

• keas.build 0.4.1 的初始分支