README.rst 15.8 KB
Newer Older
1
################################################
Matthew Brett's avatar
Matthew Brett committed
2
Utilities for building on Travis CI and AppVeyor
3
################################################
4

Hugo's avatar
Hugo committed
5
A set of scripts to automate builds of macOS and Manylinux1 wheels on the
6
`Travis CI <https://travis-ci.org/>`_ infrastructure, and also Windows
7
wheels on the `AppVeyor <https://ci.appveyor.com/>`_ infrastructure.
Matthew Brett's avatar
Matthew Brett committed
8

9
The Travis CI scripts are designed to build *and test*:
Matthew Brett's avatar
Matthew Brett committed
10

11
12
* Dual 32/64-bit architecture macOS wheels built for macOS 10.6+;
* 64-bit macOS wheels built for macOS 10.9+;
13
14
* 64-bit ``manylinuxX_x86_64`` wheels, both narrow and wide Unicode builds, where `X` is any valid Manylinux version, such as `1`, or `2010`.
* 32-bit ``manylinuxX_i686`` wheels, both narrow and wide Unicode builds.
Matthew Brett's avatar
Matthew Brett committed
15

Andrew Murray's avatar
Andrew Murray committed
16
You can currently build and test against Pythons 2.7, 3.5, 3.6, 3.7.
Matthew Brett's avatar
Matthew Brett committed
17
18

The small innovation here is that you can test against 32-bit builds, and both
19
20
wide and narrow Unicode Python 2 builds, which was not easy on the default
Travis CI configurations.
Matthew Brett's avatar
Matthew Brett committed
21

22
23
24
25
26
The AppVeyor setup is designed to build *and test*:

* 64-bit Windows ``win_amd64`` wheels;
* 32-bit Windows ``win32`` wheels.

Andrew Murray's avatar
Andrew Murray committed
27
You can currently build and test against Pythons 2.7, 3.5, 3.6, 3.7.
28

29
30
31
32
33
34
35
36
37
38
39
40
41
*****************
How does it work?
*****************

Multibuild is a series of bash scripts that define bash functions to build and
test wheels.

Configuration is by overriding the default build function, and defining a test
function.

The bash scripts are layered, in the sense that they loaded in the following
sequence:

Hugo's avatar
Hugo committed
42
43
macOS
=====
44

Matthew Brett's avatar
Matthew Brett committed
45
See ``multibuild/travis_osx_steps.sh``.
46

Matthew Brett's avatar
Matthew Brett committed
47
48
49
For build and test phases, these bash scripts get sourced one after the other,
so that functions and variables defined in later scripts can overwrite
functions and variables in earlier scripts:
50

Matthew Brett's avatar
Matthew Brett committed
51
52
* multibuild/common_utils.sh
* multibuild/osx_utils.sh
53
* env_vars.sh
54
* multibuild/configure_build.sh
Matthew Brett's avatar
Matthew Brett committed
55
56
* multibuild/library_builders.sh
* config.sh
57

58
59
See ``travis_osx_steps.sh`` to review source order.

Rob Buckley's avatar
Rob Buckley committed
60
The macOS build / test phases run on the macOS VM started by Travis CI.
Matthew Brett's avatar
Matthew Brett committed
61
62
Therefore any environment variable defined in the ``.travis.yml`` or bash
shell scripts listed above are available for your build and test.
63

64
macOS builds may be targeted either at macOS 10.6+
65
(dual arch 64 / 32 bit) or macOS 10.9+ (64b only). These depend on the
66
corresponding build of python from https://www.python.org/downloads/mac-osx/.
67
At the time of writing, 10.9+ / 64 bit builds are supported for Python
68
versions 3.6.5 / 2.7.15 and above. If you want to build for an older version
69
of Python, you'll have to target 10.6+ / dual arch.
70

71
72
73
The ``build_wheel`` function builds the wheel, and the ``install_run``
function installs the wheel and tests it.  Look in ``common_utils.sh`` for
default definitions of these functions.  See below for more details.
74

Matthew Brett's avatar
Matthew Brett committed
75
76
Manylinux
=========
77

78
The build phase is in a Manylinux Docker container, but the test phase is in
79
a clean Ubuntu 14.04 container.
80

81

Matthew Brett's avatar
Matthew Brett committed
82
83
Build phase
-----------
84

85
86
Specify the Manylinux version to build for with the `MB_ML_VER` environment variable.  The default version is `1`.  Versions that are currently valid are:

87
88
* `1` corresponding to manylinux1 (see [PEP 513](https://www.python.org/dev/peps/pep-0513);
* `2010`  corresponding to manylinux2010 (see [PEP
89
  571](https://www.python.org/dev/peps/pep-0571).
90
91
* `2014` corresponding to manylinux2014 (see [PEP
  599](https://www.python.org/dev/peps/pep-0599).
92
93
94

The environment variable specified which Manylinux docker container you are building in.

95
The `PLAT` environment variable can be one of `x86_64`, `i686` or `aarch64`, specifying 64-bit x86, 32-bit x86, and 64-bit ARM builds, respectively.  The default is `x86_64`.
96
97
98
99
100
101

At the time of writing, Manylinux2010 only supports 64-bit
builds, so `MB_ML_VER=2010` and `PLAT=i686` is an invalid
combination, and will generate an error when trying to find the
matching Docker image.

Matthew Brett's avatar
Matthew Brett committed
102
``multibuild/travis_linux_steps.sh`` defines the ``build_wheel`` function,
Hugo's avatar
Hugo committed
103
which starts up the Manylinux1 Docker container to run a wrapper script
Matthew Brett's avatar
Matthew Brett committed
104
105
106
107
108
``multibuild/docker_build_wrap.sh``, that (within the container) sources the
following bash scripts:

* multibuild/common_utils.sh
* multibuild/manylinux_utils.sh
109
* env_vars.sh
110
* multibuild/configure_build.sh
Matthew Brett's avatar
Matthew Brett committed
111
112
113
* multibuild/library_builders.sh
* config.sh

114
115
See ``docker_build_wrap.sh`` to review the order of script sourcing.

116
117
See the definition of ``build_multilinux`` in
``multibuild/travis_linux_steps.sh`` for the environment variables passed from
118
Travis CI to the Manylinux1 container.
Matthew Brett's avatar
Matthew Brett committed
119
120
121
122
123
124
125
126

Once in the container, after sourcing the scripts above, the wrapper runs the
real ``build_wheel`` function, which now comes (by default) from
``multibuild/common_utils.sh``.

Test phase
----------

Hugo's avatar
Hugo committed
127
Testing is in an Ubuntu 14.04 Docker container - see
Matthew Brett's avatar
Matthew Brett committed
128
``multibuild/docker_test_wrap.sh``.  ``multibuild/travis_linux_steps.sh``
Hugo's avatar
Hugo committed
129
defines the ``install_run`` function, which starts up the testing Docker
Matthew Brett's avatar
Matthew Brett committed
130
131
132
133
134
135
container with a wrapper script ``multibuild/docker_test_wrap.sh``.  The
wrapper script sources the following bash scripts:

* multibuild/common_utils.sh
* config.sh

136
137
See ``docker_test_wrap.sh`` for script source order.

Matthew Brett's avatar
Matthew Brett committed
138
139
140
141
142
See ``install_run`` in ``multibuild/travis_linux_steps.sh`` for the
environment variables passed into the container.

It then (in the container) runs the real ``install_run`` command, which comes
(by default) from ``multibuild/common_utils.sh``.
143
144
145
146
147

*********************************
Standard build and test functions
*********************************

Andrew Murray's avatar
Andrew Murray committed
148
The standard build command is ``build_wheel``.  This is a bash function.  By
Hugo's avatar
Hugo committed
149
default the function that is run on macOS, and in the Manylinux container for
Matthew Brett's avatar
Matthew Brett committed
150
151
152
the build phase, is defined in ``multibuild/common_utils.sh``.  You can
override the default function in the project ``config.sh`` file (see below).

153
154
155
156
157
158
159
160
If you are building a wheel from pypi, rather than from a source repository,
you can use the ``build_index_wheel`` command, again defined in
``multibuild/common_utils.sh``.

Typically, you can get away with leaving the default ``build_wheel`` /
``build_index_wheel`` functions to do their thing, but you may need to define
a ``pre_build`` function in ``config.sh``.  The default ``build_wheel`` and
``build_index_wheel`` functions will call the ``pre_build`` function, if
161
162
163
defined, before building the wheel, so ``pre_build`` is a good place to build
any required libraries.

Matthew Brett's avatar
Matthew Brett committed
164
The standard test command is the bash function ``install_run``.  The version
Hugo's avatar
Hugo committed
165
run on macOS and in the Linux testing container is also defined in
Matthew Brett's avatar
Matthew Brett committed
166
``multibuild/common_utils.sh``.  Typically, you do not override this function,
167
168
169
170
but you in that case you will need to define a ``run_tests`` function, to run
your tests, returning a non-zero error code for failure.  The default
``install_run`` implementation calls the ``run_tests`` function, which you
will likely define in ``config.sh``.  See the examples below for examples of
Andrew Murray's avatar
Andrew Murray committed
171
less and more complicated builds, where the complicated builds override more
172
of the default implementations.
173
174
175
176

********************
To use these scripts
********************
Matthew Brett's avatar
Matthew Brett committed
177

178
* Make a repository for building wheels on Travis CI - e.g.
Matthew Brett's avatar
Matthew Brett committed
179
180
181
182
183
184
185
186
187
188
189
190
191
192
  https://github.com/MacPython/astropy-wheels - or in your case maybe
  ``https://github.com/your-org/your-project-wheels``;

* Add this (here) repository as a submodule::

    git submodule add https://github.com/matthew-brett/multibuild.git

* Add your own project repository as another submodule::

    git submodule add https://github.com/your-org/your-project.git

* Create a ``.travis.yml`` file, something like this::

    env:
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
        global:
            - REPO_DIR=your-project
            # Commit from your-project that you want to build
            - BUILD_COMMIT=v0.1.0
            # pip dependencies to _build_ your project
            - BUILD_DEPENDS="Cython numpy"
            # pip dependencies to _test_ your project.  Include any dependencies
            # that you need, that are also specified in BUILD_DEPENDS, this will be
            # a separate install.
            - TEST_DEPENDS="numpy scipy pytest"
            - PLAT=x86_64
            - UNICODE_WIDTH=32
            - WHEELHOUSE_UPLOADER_USERNAME=travis-worker
            # Following generated with
            # travis encrypt -r your-org/your-project-wheels WHEELHOUSE_UPLOADER_SECRET=<the api key>
            # This is for Rackspace uploads.  Contact Matthew Brett, or the
            # scikit-learn team, for # permission (and the API key) to upload to
            # the Rackspace account used here, or use your own account.
            - secure:
                "MNKyBWOzu7JAUmC0Y+JhPKfytXxY/ADRmUIMEWZV977FLZPgYctqd+lqel2QIFgdHDO1CIdTSymOOFZckM9ICUXg9Ta+8oBjSvAVWO1ahDcToRM2DLq66fKg+NKimd2OfK7x597h/QmUSl4k8XyvyyXgl5jOiLg/EJxNE2r83IA="
Matthew Brett's avatar
Matthew Brett committed
213

214
215
216
217
218
219
220
    # You will likely prefer "language: generic" for travis configuration,
    # rather than, say "language: python". Multibuild doesn't use
    # Travis-provided Python but rather installs and uses its own, where the
    # Python version is set from the MB_PYTHON_VERSION variable. You can still
    # specify a language here if you need it for some unrelated logic and you
    # can't use Multibuild-provided Python or other software present on a
    # builder.
221
    language: generic
222
223
224
225
226
227

    # For CPython macOS builds only, the minimum supported macOS version and
    # architectures of any C extensions in the wheel are set with the variable
    # MB_PYTHON_OSX_VER: 10.9 (64-bit only) or 10.6 (64/32-bit dual arch).
    # All PyPy macOS builds are 64-bit only.

Andrew Murray's avatar
Andrew Murray committed
228
    # Required in Linux to invoke `docker` ourselves
Matthew Brett's avatar
Matthew Brett committed
229
230
    services: docker

231
232
233
    # Host distribution.  This is the distribution from which we run the build
    # and test containers, via docker.
    dist: xenial
Matthew Brett's avatar
Matthew Brett committed
234

Matthew Brett's avatar
Matthew Brett committed
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
    matrix:
      include:
        - os: linux
          env: MB_PYTHON_VERSION=2.7
        - os: linux
          env:
            - MB_PYTHON_VERSION=2.7
            - UNICODE_WIDTH=16
        - os: linux
          env:
            - MB_PYTHON_VERSION=2.7
            - PLAT=i686
        - os: linux
          env:
            - MB_PYTHON_VERSION=2.7
            - PLAT=i686
            - UNICODE_WIDTH=16
        - os: linux
          env:
            - MB_PYTHON_VERSION=3.5
        - os: linux
          env:
            - MB_PYTHON_VERSION=3.5
            - PLAT=i686
riddell1's avatar
riddell1 committed
259
260
261
262
263
264
265
        - os: linux
          env:
            - MB_PYTHON_VERSION=3.6
        - os: linux
          env:
            - MB_PYTHON_VERSION=3.6
            - PLAT=i686
Matthew Brett's avatar
Matthew Brett committed
266
267
268
        - os: osx
          env:
            - MB_PYTHON_VERSION=2.7
269
270
271
272
        - os: osx
          env:
            - MB_PYTHON_VERSION=2.7
            - MB_PYTHON_OSX_VER=10.9
Matthew Brett's avatar
Matthew Brett committed
273
274
275
        - os: osx
          env:
            - MB_PYTHON_VERSION=3.5
riddell1's avatar
riddell1 committed
276
277
278
        - os: osx
          env:
            - MB_PYTHON_VERSION=3.6
Kyle Stewart's avatar
Kyle Stewart committed
279
        - os: osx
280
          env:
281
            - MB_PYTHON_VERSION=3.7
282
            - MB_PYTHON_OSX_VER=10.9
Kyle Stewart's avatar
Kyle Stewart committed
283
284
285
        - os: osx
          language: generic
          env:
286
            - MB_PYTHON_VERSION=pypy-5.7
Matthew Brett's avatar
Matthew Brett committed
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311

    before_install:
        - source multibuild/common_utils.sh
        - source multibuild/travis_steps.sh
        - before_install

    install:
        # Maybe get and clean and patch source
        - clean_code $REPO_DIR $BUILD_COMMIT
        - build_wheel $REPO_DIR $PLAT

    script:
        - install_run $PLAT

    after_success:
        # Upload wheels to Rackspace container
        - pip install wheelhouse-uploader
        # This uploads the wheels to a Rackspace container owned by the
        # scikit-learn team, available at http://wheels.scipy.org.  See above
        # for information on using this account or choosing another.
        - python -m wheelhouse_uploader upload --local-folder
            ${TRAVIS_BUILD_DIR}/wheelhouse/
            --no-update-index
            wheels

Hugo's avatar
Hugo committed
312
  The example above is for a project building from a Git submodule.  If you
313
314
315
316
317
318
319
320
321
322
323
324
325
326
  aren't building from a submodule, but want to use ``pip`` to build from a
  source archive on https://pypi.org or similar, replace the first few lines
  of the ``.travis.yml`` file with something like::

    env:
        global:
            # Instead of REPO_DIR, BUILD_COMMIT
            - PROJECT_SPEC="tornado==4.1.1"

  then your ``install`` section could look something like this::

    install:
        - build_index_wheel $PROJECT_SPEC

327

Matthew Brett's avatar
Matthew Brett committed
328
329
330
331
332
* Next create a ``config.sh`` for your project, that fills in any steps you
  need to do before building the wheel (such as building required libraries).
  You also need this file to specify how to run your tests::

    # Define custom utilities
Hugo's avatar
Hugo committed
333
    # Test for macOS with [ -n "$IS_OSX" ]
Matthew Brett's avatar
Matthew Brett committed
334
335
336
337
338
339
340
341
342
343
344
345
346

    function pre_build {
        # Any stuff that you need to do before you start building the wheels
        # Runs in the root directory of this repository.
        :
    }

    function run_tests {
        # Runs tests on installed distribution from an empty directory
        python --version
        python -c 'import sys; import yourpackage; sys.exit(yourpackage.test())'
    }

347
348
  Optionally you can specify a different location for ``config.sh`` file with
  the ``$CONFIG_PATH`` environment variable.
349

350
* Optionally, create an ``env_vars.sh`` file to override the defaults for any
351
352
353
  environment variables used by
  ``configure_build.sh``/``library_builders.sh``. In Linux, the environment
  variables used for the build cannot be set in the ``.travis.yml`` file,
354
  because the build processing runs in a Docker container, so the only
355
356
357
358
359
360
361
362
  environment variables that reach the container are those passed in via the
  ``docker run`` command, or those set in ``env_vars.sh``.

  As for the ``config.sh`` file, you can specify a different location for the
  file by setting the ``$ENV_VARS_PATH`` environment variable.  The path in
  ``$ENV_VARS_PATH`` is relative to the repository root directory.  For
  example, if your repository had a subdirectory ``scripts`` with a file
  ``my_env_vars.sh``, you should set ``ENV_VARS_PATH=scripts/my_env_vars.sh``.
363

364
* Make sure your project is set up to build on Travis CI, and you should now
Matthew Brett's avatar
Matthew Brett committed
365
  be ready (to begin the long slow debugging process, probably).
366

367
368
* For the Windows wheels, create an ``appveyor.yml`` file, something like:

Andrew Murray's avatar
Andrew Murray committed
369
  - https://github.com/MacPython/numpy-wheels/blob/master/.appveyor.yml
370
371
372
  - https://github.com/MacPython/astropy-wheels/blob/master/appveyor.yml
  - https://github.com/MacPython/nipy-wheels/blob/master/appveyor.yml
  - https://github.com/MacPython/pytables-wheels/blob/master/appveyor.yml
373

374
375
  Note the Windows test customizations etc are inside ``appveyor.yml``,
  and that ``config.sh`` and ``env_vars.sh`` are only for the
376
  Linux/Mac builds on Travis CI.
377

Matthew Brett's avatar
Matthew Brett committed
378
* Make sure your project is set up to build on AppVeyor, and you should now
379
  be ready (for what could be another round of slow debugging).
Matthew Brett's avatar
Matthew Brett committed
380

Hugo's avatar
Hugo committed
381
382
If your project depends on NumPy, you will want to build against the earliest
NumPy that your project supports - see `forward, backward NumPy compatibility
Andrew Murray's avatar
Andrew Murray committed
383
<https://stackoverflow.com/questions/17709641/valueerror-numpy-dtype-has-the-wrong-size-try-recompiling/18369312#18369312>`_.
384
See the `astropy-wheels Travis file
Matthew Brett's avatar
Matthew Brett committed
385
<https://github.com/MacPython/astropy-wheels/blob/master/.travis.yml>`_ for an
Hugo's avatar
Hugo committed
386
example specifying NumPy build and test dependencies.
Matthew Brett's avatar
Matthew Brett committed
387
388
389
390
391
392
393
394
395

Here are some simple example projects:

* https://github.com/MacPython/astropy-wheels
* https://github.com/scikit-image/scikit-image-wheels
* https://github.com/MacPython/nipy-wheels
* https://github.com/MacPython/dipy-wheels

Less simple projects where there are some serious build dependencies, and / or
Hugo's avatar
Hugo committed
396
macOS / Linux differences:
Matthew Brett's avatar
Matthew Brett committed
397
398
399
400

* https://github.com/MacPython/matplotlib-wheels
* https://github.com/python-pillow/Pillow-wheels
* https://github.com/MacPython/h5py-wheels
401
402
403
404
405
406
407
408

**********************
Multibuild development
**********************

The main multibuild repository is always at
https://github.com/matthew-brett/multibuild

409
410
We try to keep the ``master`` branch stable and do testing and development
in the ``devel`` branch.  From time to time we merge ``devel`` into ``master``.
411

412
413
In practice, you can check out the newest commit from ``devel`` that works
for you, then stay at it until you need newer features.