Merge pull request pypa#191 from pfmoore/appveyor-revision

Revise and simplify Appveyor usage instructions

Author: pfmoore

source/appveyor.rst

@@ -1,12 +1,14 @@
-=================================================
-Building Binary Wheels for Windows using Appveyor
-=================================================
+=================================
+Supporting Windows using Appveyor
+=================================
 
 :Page Status: Incomplete
-:Last Reviewed: 2014-09-27
+:Last Reviewed: 2015-12-03
 
 This section covers how to use the free `Appveyor`_ continuous integration
-service to build Windows-targeted binary wheels for your project.
+service to provide Windows support for your project. This includes testing
+the code on Windows, and building Windows-targeted binaries for projects
+that use C extensions.
 
 .. contents:: Contents
    :local:
@@ -15,19 +17,23 @@ service to build Windows-targeted binary wheels for your project.
 Background
 ==========
 
-Windows users typically do not have access to a C compiler, and therefore are
-reliant on projects that use C extensions distributing binary wheels on PyPI in
-order for the distribution to be installable via ``pip install dist``.
-However, it is often the case that projects which are intended to be
-cross-platform are developed on Unix, and so the project developers *also* have
-the problem of lack of access to a Windows compiler.
+Many projects are developed on Unix by default, and providing Windows support
+can be a challenge, because setting up a suitable Windows test environment is
+non-trivial, and may require buying software licenses.
 
 The Appveyor service is a continuous integration service, much like the
 better-known `Travis`_ service that is commonly used for testing by projects
 hosted on `Github`_. However, unlike Travis, the build workers on Appveyor are
 Windows hosts and have the necessary compilers installed to build Python
 extensions.
 
+Windows users typically do not have access to a C compiler, and therefore are
+reliant on projects that use C extensions distributing binary wheels on PyPI in
+order for the distribution to be installable via ``pip install <dist>``. By
+using Appveyor as a build service (even if not using it for testing) it is
+possible for projects without a dedicated Windows environment to provide
+Windows-targeted binaries.
+
 Setting Up
 ==========
 
@@ -52,6 +58,13 @@ In order to define how Appveyor should build your project, you need to add an
 in the file are covered in the Appveyor documentation. This guide will provide
 the details necessary to set up wheel builds.
 
+Appveyor includes by default all of the compiler toolchains needed to build
+extensions for Python. For Python 2.7, 3.5+ and 32-bit versions of 3.3 and 3.4,
+the tools work out of the box. But for 64-bit versions of Python 3.3 and 3.4,
+there is a small amount of additional configuration needed to let distutils
+know where to find the 64-bit compilers. (From 3.5 onwards, the version of
+Visual Studio used includes 64-bit compilers with no additional setup).
+
 appveyor.yml
 ------------
 
@@ -65,54 +78,59 @@ The ``appveyor.yml`` file must be located in the root directory of your
 project. It is in ``YAML`` format, and consists of a number of sections.
 
 The ``environment`` section is the key to defining the Python versions for
-which your wheels will be created. Appveyor comes with Python 2.7, 3.3 and 3.4
-installed, in both 32-bit and 64-bit builds. The example file builds for all of
-these environments.
-
-The ``install`` section installs any additional software that the project may
-require. The supplied code installs ``pip`` (if needed) and ``wheel``. Projects
-may wish to customise this code in certain circumstances (for example, to install
-additional build packages such as ``Cython``, or test tools such as ``tox``).
+which your wheels will be created. Appveyor comes with Python 2.6, 2.7, 3.3,
+3.4 and 3.5 installed, in both 32-bit and 64-bit builds. The example file
+builds for all of these environments except Python 2.6. Installing for Python
+2.6 is more complex, as it does not come with pip included. We don't support
+2.6 in this document (as Windows users still using Python 2 are generally able
+to move to Python 2.7 without too much difficulty).
+
+The ``install`` section uses pip to install any additional software that the
+project may require. The only requirement for building wheels is the ``wheel``
+project, but projects may wish to customise this code in certain circumstances
+(for example, to install additional build packages such as ``Cython``, or test
+tools such as ``tox``).
 
 The ``build`` section simply switches off builds - there is no build step needed
 for Python, unlike languages like ``C#``.
 
-The ``test_script`` section is technically not needed. The supplied file runs
-your test suite using ``setup.py test``. You may wish to use another test tool
-such as ``tox`` or ``py.test``. Or you could skip the test (but why would you,
-unless your tests are expected to fail on Windows?) by replacing the script with
-a simple ``echo Skipped`` command.
+The main sections that will need to be tailored to your project are ``test_script``
+and ``after_test``.
+
+The ``test_script`` section is where you will run your project's tests. The
+supplied file runs your test suite using ``setup.py test``. If you are only
+interested in building wheels, and not in running your tests on Windows, you
+can replace this section with a dummy command such as ``echo Skipped Tests``.
+You may wish to use another test tool, such as ``nose`` or ``py.test``. Or you
+may wish to use a test driver like ``tox`` - however if you are using ``tox``
+there are some additional configuration changes you will need to consider,
+which are described below.
 
-The ``after_test`` command is where the wheels are built. Assuming your project
-uses the recommended tools (specifically, ``setuptools``) then the
-``setup.py bdist_wheel`` command will build your wheels.
+The ``after_test`` runs once your tests have completed, and so is where the
+wheels should be built. Assuming your project uses the recommended tools
+(specifically, ``setuptools``) then the ``setup.py bdist_wheel`` command
+will build your wheels.
 
 Note that wheels will only be built if your tests succeed. If you expect your
 tests to fail on Windows, you can skip them as described above.
 
 
-Support scripts
----------------
+Support script
+--------------
 
-The ``appveyor.yml`` file relies on two support scripts. The code assumes that
-these will be placed in a subdirectory named ``appveyor`` at the root of your
-project.
+The ``appveyor.yml`` file relies on a single support script, which sets up the
+environment to use the SDK compiler for 64-bit builds on Python 3.3 and 3.4.
+For projects which do not need a compiler, or which don't support 3.3 or 3.4 on
+64-bit Windows, only the ``appveyor.yml`` file is needed.
 
-`appveyor/run_with_compiler.cmd <https://raw.githubusercontent.com/pypa/python-packaging-user-guide/master/source/code/run_with_compiler.cmd>`__
+`build.cmd <https://raw.githubusercontent.com/pypa/python-packaging-user-guide/master/source/code/build.cmd>`__
 is a Windows batch script that runs a single command in an environment with the
-appropriate compiler for the selected Python version.
+appropriate compiler for the selected Python version. All you need to do is to
+set the single environment variable ``DISTUTILS_USE_SDK`` to a value of ``1``
+and the script does the rest. It sets up the SDK needed for 64-bit builds of
+Python 3.3 or 3.4, so don't set the environment variable for any other builds.
 
-`appveyor/install.ps1 <https://raw.githubusercontent.com/pypa/python-packaging-user-guide/master/source/code/install.ps1>`__ is a Powershell
-script that downloads and installs any missing Python versions, installs
-``pip`` into the Python ``site-packages`` and downloads and installs the latest
-``wheel`` distribution. Steps that are not needed are omitted, so in practice,
-the Python install will never be run (it is present for advanced users who want
-to install additional versions of Python not supplied by Appveyor) and the
-``pip`` install will be omitted for Python 3.4, where pip is installed as
-standard.
-
-You can simply download these two files and include them in your project
-unchanged.
+You can simply download the batch file and include it in your project unchanged.
 
 
 Access to the built wheels
@@ -128,6 +146,57 @@ wheels and upload them to PyPI as part of your release process.
 Additional Notes
 ================
 
+Testing with tox
+----------------
+
+Many projects use the `Tox`_ tool to run their tests. It ensures that tests
+are run in an isolated environment using the exact files that will be distributed
+by the project.
+
+In order to use ``tox`` on Appveyor there are a couple of additional considerations
+(in actual fact, these issues are not specific to Appveyor, and may well affect
+other CI systems).
+
+1. By default, ``tox`` only passes a chosen subset of environment variables to the
+   test processes. Because ``distutils`` uses environment variables to control the
+   compiler, this "test isolation" feature will cause the tests to use the wrong
+   compiler by default.
+
+   To force ``tox`` to pass the necessary environment variables to the subprocess,
+   you need to set the ``tox`` configuration option ``passenv`` to list the additional
+   environment variables to be passed to the subprocess. For the SDK compilers, you
+   need
+
+        - ``DISTUTILS_USE_SDK``
+        - ``MSSdk``
+        - ``INCLUDE``
+        - ``LIB``
+
+    The ``passenv`` option can be set in your ``tox.ini``, or if you prefer to avoid
+    adding Windows-specific settings to your general project files, it can be set by
+    setting the ``TOX_TESTENV_PASSENV`` environment variable. The supplied ``build.cmd``
+    script does this by default whenever ``DISTUTILS_USE_SDK`` is set.
+
+2. When used interactively, ``tox`` allows you to run your tests against multiple
+   environments (often, this means multiple Python versions). This feature is not as
+   useful in a CI environment like Travis or Appveyor, where all tests are run in
+   isolated environments for each configuration. As a result, projects often supply
+   an argument ``-e ENVNAME`` to ``tox`` to specify which environment to use (there
+   are default environments for most versions of Python).
+
+    However, this does *not* work well with a Windows CI system like Appveyor, where
+    there are (for example) two installations of Python 3.4 (32-bit and 64-bit)
+    available, but only one ``py34`` environment in ``tox``.
+
+    In order to run tests using ``tox``, therefore, projects should probably use the
+    default ``py`` environment in ``tox``, which uses the Python interpreter that
+    was used to run ``tox``. This will ensure that when Appveyor runs the tests, they
+    will be run with the configured interpreter.
+
+    In order to support running under the ``py`` environment, it is possible that
+    projects with complex ``tox`` configurations might need to modify their ``tox.ini``
+    file. Doing so is, however, outside the scope of this document.
+
 Automatically uploading wheels
 ------------------------------
 
@@ -145,32 +214,28 @@ External dependencies
 ---------------------
 
 The supplied scripts will successfully build any distribution that does not
-rely on 3rd party external libraries for the build. It would be possible for an
-individual project to add code to the ``install.ps1`` script to make external
-libraries available to the build, but this is of necessity specific to
-individual projects.
+rely on 3rd party external libraries for the build.
+
+It is possible to add steps to the ``appveyor.yml`` configuration (typically
+in the "install" section) to download and/or build external libraries needed by
+the distribution. And if needed, it is possible to add extra configuration for
+the build to supply the location of these libraries to the compiler. However,
+this level of configuration is beyond the scope of this document.
 
-Should projects develop scripts showing how to do this, references will be
-added to this guide at a later date.
 
 Support scripts
 ---------------
 
-For reference, the two support scripts are listed here:
+For reference, the SDK setup support script is listed here:
 
-``code/run_with_compiler.cmd``
+``code/build.cmd``
 
-.. literalinclude:: code/run_with_compiler.cmd
+.. literalinclude:: code/build.cmd
    :language: bat
    :linenos:
 
-``code/install.ps1``
-
-.. literalinclude:: code/install.ps1
-   :language: powershell
-   :linenos:
-
 .. _Appveyor: http://www.appveyor.com/
 .. _Travis: https://travis-ci.org/
 .. _Github: https://github.org/
 .. _Bitbucket: https://bitbucket.org/
+.. _Tox: http://tox.testrun.org

source/code/appveyor.yml

@@ -1,67 +1,51 @@
 environment:
 
-  global:
-    # SDK v7.0 MSVC Express 2008's SetEnv.cmd script will fail if the
-    # /E:ON and /V:ON options are not enabled in the batch script intepreter
-    # See: http://stackoverflow.com/a/13751649/163740
-    WITH_COMPILER: "cmd /E:ON /V:ON /C .\\appveyor\\run_with_compiler.cmd"
-
   matrix:
 
-    # Pre-installed Python versions, which Appveyor may upgrade to
-    # a later point release.
-    # See: http://www.appveyor.com/docs/installed-software#python
+    # For Python versions available on Appveyor, see
+    # http://www.appveyor.com/docs/installed-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_VERSION: "2.7.x" # currently 2.7.9
-      PYTHON_ARCH: "32"
-
     - PYTHON: "C:\\Python33"
-      PYTHON_VERSION: "3.3.x" # currently 3.3.5
-      PYTHON_ARCH: "32"
-
     - PYTHON: "C:\\Python34"
-      PYTHON_VERSION: "3.4.x" # currently 3.4.3
-      PYTHON_ARCH: "32"
-
+    - PYTHON: "C:\\Python35"
     - PYTHON: "C:\\Python27-x64"
-      PYTHON_VERSION: "2.7.x" # currently 2.7.9
-      PYTHON_ARCH: "64"
-      WINDOWS_SDK_VERSION: "v7.0"
-
     - PYTHON: "C:\\Python33-x64"
-      PYTHON_VERSION: "3.3.x" # currently 3.3.5
-      PYTHON_ARCH: "64"
-      WINDOWS_SDK_VERSION: "v7.1"
-
+      DISTUTILS_USE_SDK: "1"
     - PYTHON: "C:\\Python34-x64"
-      PYTHON_VERSION: "3.4.x" # currently 3.4.3
-      PYTHON_ARCH: "64"
-      WINDOWS_SDK_VERSION: "v7.1"
-
-    # Also build on a Python version not pre-installed by Appveyor.
-    # See: https://github.com/ogrisel/python-appveyor-demo/issues/10
-
-    - PYTHON: "C:\\Python266"
-      PYTHON_VERSION: "2.6.6"
-      PYTHON_ARCH: "32"
-
-init:
-  - "ECHO %PYTHON% %PYTHON_VERSION% %PYTHON_ARCH%"
+      DISTUTILS_USE_SDK: "1"
+    - PYTHON: "C:\\Python35-x64"
 
 install:
-  - "powershell appveyor\\install.ps1"
+  # We need wheel installed to build wheels
+  - "%PYTHON%\\python.exe -m pip install wheel"
 
 build: off
 
 test_script:
-  - "%WITH_COMPILER% %PYTHON%/python setup.py test"
+  # 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 evrsion you want to use on PATH.
+  - "build.cmd %PYTHON%\\python.exe setup.py test"
 
 after_test:
-  - "%WITH_COMPILER% %PYTHON%/python setup.py bdist_wheel"
+  # 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:
-#  - TODO: upload the content of dist/*.whl to a public wheelhouse
+#  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.

source/code/build.cmd

@@ -0,0 +1,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/64BitCythonExtensionsOnWindows
+
+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 %*