使用AppVeyor支持Windows

页面状态

不完整

上次审阅时间

2015-12-03

本节介绍如何使用免费 Appveyor 持续集成服务，为您的项目提供Windows支持。这包括在Windows上测试代码，以及为使用C扩展的项目构建面向Windows的二进制文件。

背景

默认情况下，许多项目是在Unix上开发的，提供Windows支持可能是一个挑战，因为设置合适的Windows测试环境非常重要，可能需要购买软件许可证。

Appveyor服务是一个持续的集成服务，与已知的类似 Travis 通常由托管在上的项目用于测试的服务 Github . 但是，与Travis不同，Appveyor上的构建工作人员是Windows主机，并且安装了必要的编译器来构建Python扩展。

Windows用户通常没有访问C编译器的权限，因此依赖于使用C扩展的项目，这些项目在Pypi上分发二进制车轮，以便通过 pip install <dist> . 通过将Appveyor用作生成服务（即使不将其用于测试），对于没有专用Windows环境的项目来说，提供面向Windows的二进制文件是可能的。

设置

为了使用Appveyor为您的项目构建Windows轮子，您必须拥有该服务的帐户。有关设置帐户的说明，请参见 the Appveyor documentation . 对于开源项目来说，免费的账户层是完全足够的。

Appveyor提供与 Github 和 Bitbucket ，只要您的项目托管在这两个服务之一上，那么设置Appveyor集成就很简单。

一旦设置了Appveyor帐户并添加了项目，Appveyor将在每次提交时自动构建项目。Travis的用户将熟悉这种行为。

向项目添加Appveyor支持

为了定义Appveyor应该如何构建项目，需要添加 appveyor.yml 文件到项目。文件中可以包含的全部细节在Appveyor文档中介绍。本指南将提供设置车轮构造所需的详细信息。

默认情况下，Appveyor包含为python构建扩展所需的所有编译器工具链。对于3.3和3.4的python 2.7、3.5+和32位版本，这些工具是现成的。但是对于64位版本的python 3.3和3.4，有少量的额外配置需要让distutils知道在哪里可以找到64位编译器。（从3.5版开始，使用的Visual Studio版本包括64位编译器，无需额外设置）。

appveyor.yml

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
environment:

  matrix:

    # For Python versions available on Appveyor, see
    # https://www.appveyor.com/docs/windows-images-software/#python
    # The list here is complete (excluding Python 2.6, which
    # isn't covered by this document) at the time of writing.

    - PYTHON: "C:\\Python27"
    - PYTHON: "C:\\Python33"
    - PYTHON: "C:\\Python34"
    - PYTHON: "C:\\Python35"
    - PYTHON: "C:\\Python27-x64"
    - PYTHON: "C:\\Python33-x64"
      DISTUTILS_USE_SDK: "1"
    - PYTHON: "C:\\Python34-x64"
      DISTUTILS_USE_SDK: "1"
    - PYTHON: "C:\\Python35-x64"
    - PYTHON: "C:\\Python36-x64"

install:
  # We need wheel installed to build wheels
  - "%PYTHON%\\python.exe -m pip install wheel"

build: off

test_script:
  # Put your test command here.
  # If you don't need to build C extensions on 64-bit Python 3.3 or 3.4,
  # you can remove "build.cmd" from the front of the command, as it's
  # only needed to support those cases.
  # Note that you must use the environment variable %PYTHON% to refer to
  # the interpreter you're using - Appveyor does not do anything special
  # to put the Python version you want to use on PATH.
  - "build.cmd %PYTHON%\\python.exe setup.py test"

after_test:
  # This step builds your wheels.
  # Again, you only need build.cmd if you're building C extensions for
  # 64-bit Python 3.3/3.4. And you need to use %PYTHON% to get the correct
  # interpreter
  - "build.cmd %PYTHON%\\python.exe setup.py bdist_wheel"

artifacts:
  # bdist_wheel puts your built wheel in the dist directory
  - path: dist\*

#on_success:
#  You can use this step to upload your artifacts to a public website.
#  See Appveyor's documentation for more details. Or you can simply
#  access your wheels from the Appveyor "artifacts" tab for your build.

此文件可从下载 here .

这个 appveyor.yml 文件必须位于项目的根目录中。它在里面 YAML 格式，并由多个部分组成。

这个 environment 节是定义要为其创建轮子的Python版本的关键。Appveyor在32位和64位版本中都安装了python 2.6、2.7、3.3、3.4和3.5。示例文件为除Python2.6之外的所有这些环境构建。为python 2.6安装更加复杂，因为它不包括pip。在本文档中，我们不支持2.6（因为仍然使用python 2的Windows用户通常能够轻松地迁移到python2.7）。

这个 install 第节使用PIP安装项目可能需要的任何其他软件。制造车轮的唯一要求是 wheel 项目，但项目可能希望在某些情况下自定义此代码（例如，安装其他生成包，如 Cython 或测试工具，如 tox ）

这个 build 部分只关闭构建——与类似的语言不同，Python不需要构建步骤。 C# .

需要为您的项目定制的主要部分是 test_script 和 after_test .

这个 test_script 部分是运行项目测试的位置。提供的文件使用 setup.py test . 如果您只对构建轮子感兴趣，而不想在Windows上运行测试，那么可以用一个虚拟命令（如 echo Skipped Tests . 您可能希望使用其他测试工具，例如 nose 或 py.test . 或者您可能希望使用类似的测试驱动程序 tox -但是，如果您正在使用 tox 您需要考虑一些额外的配置更改，如下所述。

这个 after_test 一旦你的测试完成，就可以运行，轮子也应该在哪里构建。假设您的项目使用推荐的工具（特别是， setuptools ）然后 setup.py bdist_wheel 命令会建立你的轮子。

请注意，只有在测试成功时才会构建轮子。如果您期望您的测试在Windows上失败，您可以按照上面的描述跳过它们。

支持脚本

这个 appveyor.yml 文件依赖于一个支持脚本，该脚本将环境设置为使用基于python 3.3和3.4的64位版本的sdk编译器。对于不需要编译器或在64位Windows上不支持3.3或3.4的项目，只有 appveyor.yml 需要文件。

build.cmd 是一个Windows批处理脚本，在具有所选Python版本的适当编译器的环境中运行单个命令。您所需要做的就是设置单个环境变量 DISTUTILS_USE_SDK 达到一定的价值 1 剩下的就由脚本来完成了。它为64位的Python3.3或3.4版本设置了所需的SDK，因此不要为任何其他版本设置环境变量。

您可以简单地下载批处理文件并将其包含在项目中，而不必更改。

进入内置车轮

当构建完成时，构建的轮子将从项目的Appveyor控制面板中可用。依次转到每个生成的“生成状态”页可以找到它们。在构建输出的顶部有一系列链接，其中一个是“工件”。该页面将包含一个指向该Python版本/体系结构车轮的链接列表。您可以下载这些轮子，并将它们作为发布过程的一部分上传到pypi。

附加说明

毒性试验

许多项目使用 Tox 运行测试的工具。它确保测试在一个独立的环境中运行，使用项目将分发的精确文件。

为了使用 tox 在Appveyor上有几个额外的考虑因素（实际上，这些问题并不特定于Appveyor，可能会影响其他CI系统）。

  1. 默认情况下， tox 只将选定的环境变量子集传递给测试进程。因为 distutils 使用环境变量控制编译器，此“测试隔离”功能将导致测试默认使用错误的编译器。

    强制 tox 要将必要的环境变量传递给子进程，需要设置 tox 配置选项 passenv 列出要传递给子进程的其他环境变量。对于SDK编译器，您需要

    • DISTUTILS_USE_SDK

    • MSSdk

    • INCLUDE

    • LIB

    这个 passenv 选项可以在 tox.ini 或者，如果希望避免将特定于Windows的设置添加到常规项目文件中，可以通过设置 TOX_TESTENV_PASSENV 环境变量。提供的 build.cmd 脚本在默认情况下执行此操作 DISTUTILS_USE_SDK 被设置。

  2. 交互使用时， tox 允许您在多个环境下运行测试（这通常意味着多个Python版本）。在Travis或Appveyor这样的CI环境中，此功能没有那么有用，因为在这些环境中，所有测试都在每个配置的独立环境中运行。因此，项目经常提供一个论据 -e ENVNAME 到 tox 指定要使用的环境（大多数Python版本都有默认环境）。

    然而，这确实是 not 与Appveyor这样的Windows CI系统一起工作良好，其中（例如）有两个可用的python 3.4（32位和64位）安装，但只有一个 py34 环境 tox .

    为了运行测试，请使用 tox 因此，项目可能应该使用默认值 py 环境 tox ，它使用用于运行的python解释器 tox . 这将确保当Appveyor运行测试时，它们将使用配置的解释器运行。

    为了支持在 py 环境，有可能是复杂的项目 tox 配置可能需要修改 tox.ini 文件。但是，这样做不在本文档的范围内。

自动上载车轮

可以请求Appveyor自动上传车轮。有一个 deployment 步骤在中可用 appveyor.yml 它可以用于（例如）将构建的工件复制到FTP站点或AmazonS3实例。有关如何做到这一点的文档包含在Appveyor指南中。

或者，可以添加 twine upload 单步执行生成。提供的 appveyor.yml 不这样做，因为不清楚每次提交之后是否需要上载新的轮子（尽管有些项目可能希望这样做）。

外部依赖

提供的脚本将成功构建任何不依赖第三方外部库进行构建的分发。

可以将步骤添加到 appveyor.yml 配置（通常在“安装”部分）以下载和/或构建分发所需的外部库。如果需要，可以为构建添加额外的配置，以向编译器提供这些库的位置。但是，这一级别的配置超出了本文档的范围。

支持脚本

此处列出了SDK安装支持脚本以供参考：

appveyor-sample/build.cmd

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
@echo off
:: To build extensions for 64 bit Python 3, we need to configure environment
:: variables to use the MSVC 2010 C++ compilers from GRMSDKX_EN_DVD.iso of:
:: MS Windows SDK for Windows 7 and .NET Framework 4
::
:: More details at:
:: https://github.com/cython/cython/wiki/CythonExtensionsOnWindows

IF "%DISTUTILS_USE_SDK%"=="1" (
    ECHO Configuring environment to build with MSVC on a 64bit architecture
    ECHO Using Windows SDK 7.1
    "C:\Program Files\Microsoft SDKs\Windows\v7.1\Setup\WindowsSdkVer.exe" -q -version:v7.1
    CALL "C:\Program Files\Microsoft SDKs\Windows\v7.1\Bin\SetEnv.cmd" /x64 /release
    SET MSSdk=1
    REM Need the following to allow tox to see the SDK compiler
    SET TOX_TESTENV_PASSENV=DISTUTILS_USE_SDK MSSdk INCLUDE LIB
) ELSE (
    ECHO Using default MSVC build environment
)

CALL %*