Oferece suporte a Windows usando Appveyor#

Status da página:

Obsoleto

Última revisão:

2015-12-03

Esta seção cobre como usar o serviço gratuito de integração contínua Appveyor para fornecer suporte a Windows para seu projeto. Isso inclui testar o código no Windows e construir binários direcionados para Windows para projetos que usam extensões C.

Contexto#

Muitos projetos são desenvolvidos em Unix por padrão, e fornecer suporte ao Windows pode ser um desafio, porque configurar um ambiente de teste adequado no Windows não é trivial e pode exigir a compra de licenças de software.

O serviço Appveyor é um serviço de integração contínua, muito parecido com o serviço Travis mais conhecido que é comumente usado para testes por projetos hospedados no GitHub. No entanto, ao contrário do Travis, os workers de construção no Appveyor são hosts Windows e têm os compiladores necessários instalados para construir extensões Python.

Os usuários do Windows normalmente não têm acesso a um compilador C e, portanto, dependem de projetos que usam extensões C distribuindo wheels binárias no PyPI para que a distribuição seja instalável via python -m pip install <dist>. Ao usar o Appveyor como um serviço de construção (mesmo que não seja para teste), é possível para projetos sem um ambiente Windows dedicado fornecer binários direcionados ao Windows.

Configurando#

Para usar o Appveyor para construir wheels de Windows para o seu projeto, você deve ter uma conta no serviço. As instruções sobre como configurar uma conta são fornecidas na documentação do Appveyor. O nível de conta grátis é perfeitamente adequado para projetos de código aberto.

O Appveyor fornece integração com GitHub e Bitbucket, portanto, desde que seu projeto esteja hospedado em um desses dois serviços, configurar a integração do Appveyor é simples.

Depois de configurar sua conta do Appveyor e adicionar seu projeto, o Appveyor construirá automaticamente seu projeto cada vez que ocorrer um commit. Esse comportamento será familiar para os usuários do Travis.

Adicionando suporte a Appveyor ao seu projeto#

Para definir como o Appveyor deve construir seu projeto, você precisa adicionar um arquivo appveyor.yml ao seu projeto. Os detalhes completos do que pode ser incluído no arquivo são cobertos na documentação do Appveyor. Este guia fornecerá os detalhes necessários para configurar a configuração dos wheels.

O Appveyor inclui por padrão todos os conjuntos de ferramentas do compilador necessários para construir extensões para Python. Para Python 2.7, 3.5+ e versões de 32 bits de 3.3 e 3.4, as ferramentas funcionam prontamente. Mas para as versões de 64 bits do Python 3.3 e 3.4, há uma pequena quantidade de configuração adicional necessária para permitir que os distutils saibam onde encontrar os compiladores de 64 bits. (De 3.5 em diante, a versão do Visual Studio usada inclui compiladores de 64 bits sem configuração adicional).

appveyor.yml#

 1environment:
 2
 3  matrix:
 4
 5    # For Python versions available on Appveyor, see
 6    # https://www.appveyor.com/docs/windows-images-software/#python
 7    # The list here is complete (excluding Python 2.6, which
 8    # isn't covered by this document) at the time of writing.
 9
10    - PYTHON: "C:\\Python27"
11    - PYTHON: "C:\\Python33"
12    - PYTHON: "C:\\Python34"
13    - PYTHON: "C:\\Python35"
14    - PYTHON: "C:\\Python27-x64"
15    - PYTHON: "C:\\Python33-x64"
16      DISTUTILS_USE_SDK: "1"
17    - PYTHON: "C:\\Python34-x64"
18      DISTUTILS_USE_SDK: "1"
19    - PYTHON: "C:\\Python35-x64"
20    - PYTHON: "C:\\Python36-x64"
21
22install:
23  # We need wheel installed to build wheels
24  - "%PYTHON%\\python.exe -m pip install wheel"
25
26build: off
27
28test_script:
29  # Put your test command here.
30  # If you don't need to build C extensions on 64-bit Python 3.3 or 3.4,
31  # you can remove "build.cmd" from the front of the command, as it's
32  # only needed to support those cases.
33  # Note that you must use the environment variable %PYTHON% to refer to
34  # the interpreter you're using - Appveyor does not do anything special
35  # to put the Python version you want to use on PATH.
36  - "build.cmd %PYTHON%\\python.exe setup.py test"
37
38after_test:
39  # This step builds your wheels.
40  # Again, you only need build.cmd if you're building C extensions for
41  # 64-bit Python 3.3/3.4. And you need to use %PYTHON% to get the correct
42  # interpreter
43  - "build.cmd %PYTHON%\\python.exe setup.py bdist_wheel"
44
45artifacts:
46  # bdist_wheel puts your built wheel in the dist directory
47  - path: dist\*
48
49#on_success:
50#  You can use this step to upload your artifacts to a public website.
51#  See Appveyor's documentation for more details. Or you can simply
52#  access your wheels from the Appveyor "artifacts" tab for your build.

Este arquivo pode ser baixado daqui.

O arquivo appveyor.yml deve estar localizado no diretório raiz do seu projeto. Está no formato YAML e consiste em várias seções.

A seção environment é a chave para definir as versões Python para as quais seus wheels serão criados. O Appveyor vem com Python 2.6, 2.7, 3.3, 3.4 e 3.5 instalados, em compilações de 32 e 64 bits. O arquivo de exemplo é criado para todos esses ambientes, exceto Python 2.6. A instalação do Python 2.6 é mais complexa, pois não vem com o pip incluído. Não oferecemos suporte ao 2.6 neste documento (já que os usuários do Windows que ainda usam o Python 2 geralmente são capazes de migrar para o Python 2.7 sem muita dificuldade).

A seção install usa pip para instalar qualquer software adicional que o projeto possa exigir. O único requisito para a construção de wheels é o projeto wheel, mas os projetos podem desejar personalizar este código em certas circunstâncias (por exemplo, para instalar pacotes de construção adicionais, como Cython, ou ferramentas de teste como tox).

A seção build simplesmente desativa as construções – não há etapa de construção necessária para Python, ao contrário de linguagens como C#.

As principais seções que precisarão ser adaptadas ao seu projeto são test_script e after_test.

A seção test_script é onde você executará os testes do seu projeto. O arquivo fornecido executa seu conjunto de testes usando setup.py test. Se você está interessado apenas em construir wheels, e não em executar seus testes no Windows, você pode substituir esta seção por um comando fictício, como echo Skipped Tests. Você pode querer usar outra ferramenta de teste, como nose ou py.test. Ou você pode desejar usar um driver de teste como o tox – entretanto, se você estiver usando o tox, existem algumas alterações de configuração adicionais que você precisará considerar, que são descritas abaixo.

O after_test é executado uma vez que seus testes foram concluídos, e então é onde os wheels devem ser construídos. Presumindo que seu projeto usa as ferramentas recomendadas (especificamente, setuptools) então o comando setup.py bdist_wheel irá construir seus wheels.

Observe que os wheels só serão construídos se seus testes forem bem-sucedidos. Se você espera que seus testes falhem no Windows, você pode pulá-los conforme descrito acima.

Script de suporte#

O arquivo appveyor.yml depende de um único script de suporte, que configura o ambiente para usar o compilador SDK para compilações de 64 bits no Python 3.3 e 3.4. Para projetos que não precisam de um compilador, ou que não oferecem suporte a 3.3 ou 3.4 em Windows 64 bits, apenas o arquivo appveyor.yml é necessário.

build.cmd é um script em lote do Windows que executa um único comando em um ambiente com o compilador apropriado para a versão Python selecionada. Tudo que você precisa fazer é definir a única variável de ambiente DISTUTILS_USE_SDK para um valor de 1 e o script faz o resto. Ele configura o SDK necessário para compilações de 64 bits de Python 3.3 ou 3.4, portanto, não defina a variável de ambiente para quaisquer outras compilações.

Você pode simplesmente baixar o arquivo em lote e incluí-lo em seu projeto inalterado.

Acesso aos wheels construídos#

Quando sua construção for concluída, os wheels construídos estarão disponíveis no painel de controle do Appveyor para o seu projeto. Eles podem ser encontrados acessando a página de status de construção de cada construção por vez. No topo da saída de construção, há uma série de links, um dos quais é “Artifacts” (Artefatos). Essa página incluirá uma lista de links para os wheels dessa versão Python / arquitetura. Você pode baixar esses wheels e enviá-los para PyPI como parte de seu processo de lançamento.

Notas adicionais#

Testando com tox#

Muitos projetos usam a ferramenta Tox para executar seus testes. Ele garante que os testes sejam executados em um ambiente isolado usando os arquivos exatos que serão distribuídos pelo projeto.

Para usar o tox no Appveyor, há algumas considerações adicionais (na verdade, esses problemas não são específicos do Appveyor e podem afetar outros sistemas de CI).

  1. Por padrão, tox apenas passa um subconjunto escolhido de variáveis de ambiente para os processos de teste. Como distutils usa variáveis de ambiente para controlar o compilador, este recurso de “isolamento de teste” fará com que os testes usem o compilador errado por padrão.

    Para forçar o tox passar as variáveis de ambiente necessárias para o subprocesso, você precisa definir a opção de configuração passenv do tox para listar as variáveis de ambiente adicionais a serem passadas para o subprocesso. Para os compiladores SDK, você precisa

    • DISTUTILS_USE_SDK

    • MSSdk

    • INCLUDE

    • LIB

    A opção passenv pode ser definida em seu tox.ini, ou se você preferir evitar adicionar configurações específicas do Windows aos seus arquivos de projeto gerais, pode ser definida configurando a variável de ambiente TOX_TESTENV_PASSENV. O script build.cmd fornecido faz isso por padrão sempre que DISTUTILS_USE_SDK é definida.

  2. Quando usado interativamente, tox permite que você execute seus testes em vários ambientes (frequentemente, isso significa várias versões do Python). Este recurso não é tão útil em um ambiente de CI como Travis ou Appveyor, onde todos os testes são executados em ambientes isolados para cada configuração. Como resultado, os projetos geralmente fornecem um argumento -e NOMEENV para tox para especificar qual ambiente usar (há ambientes padrão para a maioria das versões do Python).

    No entanto, isso não funciona bem com um sistema de CI no Windows como o Appveyor, onde há (por exemplo) duas instalações de Python 3.4 (32 bits e 64 bits) disponíveis, mas apenas um ambiente py34 no tox.

    Para executar testes usando o tox, portanto, os projetos provavelmente devem usar o ambiente padrão py no tox, que usa o interpretador Python que foi usado para executar tox . Isso garantirá que, quando o Appveyor executar os testes, eles serão executados com o interpretador configurado.

    Para oferecer suporte à execução no ambiente py, é possível que projetos com configurações complexas de tox precisem modificar seu arquivo tox.ini. Fazer isso está, no entanto, fora do escopo deste documento.

Enviando automaticamente wheels#

É possível solicitar que o Appveyor envie automaticamente os wheels. Há uma etapa deployment disponível no appveyor.yml que pode ser usada para, por exemplo, copiar os artefatos construídos para um site FTP ou uma instância do Amazon S3. A documentação sobre como fazer isso está incluída nos guias do Appveyor.

Alternativamente, seria possível adicionar um passo twine upload à construção. O appveyor.yml fornecido não faz isso, pois não está claro se é desejável enviar novos wheels após cada commit (embora alguns projetos possam desejar fazer isso).

Dependências externas#

Os scripts fornecidos construirão com sucesso qualquer distribuição que não dependa de bibliotecas externas de terceiros para a construção.

É possível adicionar etapas à configuração appveyor.yml (normalmente na seção “install”) para baixar e/ou construir bibliotecas externas necessárias para a distribuição. E se necessário, é possível adicionar configuração extra para a construção para fornecer a localização dessas bibliotecas para o compilador. No entanto, esse nível de configuração está além do escopo deste documento.

Scripts de suporte#

Para referência, o script de suporte de configuração do SDK está listado aqui:

appveyor-sample/build.cmd

 1@echo off
 2:: To build extensions for 64 bit Python 3, we need to configure environment
 3:: variables to use the MSVC 2010 C++ compilers from GRMSDKX_EN_DVD.iso of:
 4:: MS Windows SDK for Windows 7 and .NET Framework 4
 5::
 6:: More details at:
 7:: https://github.com/cython/cython/wiki/CythonExtensionsOnWindows
 8
 9IF "%DISTUTILS_USE_SDK%"=="1" (
10    ECHO Configuring environment to build with MSVC on a 64bit architecture
11    ECHO Using Windows SDK 7.1
12    "C:\Program Files\Microsoft SDKs\Windows\v7.1\Setup\WindowsSdkVer.exe" -q -version:v7.1
13    CALL "C:\Program Files\Microsoft SDKs\Windows\v7.1\Bin\SetEnv.cmd" /x64 /release
14    SET MSSdk=1
15    REM Need the following to allow tox to see the SDK compiler
16    SET TOX_TESTENV_PASSENV=DISTUTILS_USE_SDK MSSdk INCLUDE LIB
17) ELSE (
18    ECHO Using default MSVC build environment
19)
20
21CALL %*