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
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
|
:orphan:
.. _quickstart-mac:
================================================
Development environment quickstart guide (macOS)
================================================
This quickstart guide will cover:
* setting up and maintaining a development environment, including installing
compilers and SciPy build dependencies
* creating a personal fork of the SciPy repository on GitHub
* using git to manage a local repository with development branches
* performing an in-place build of SciPy
* creating a virtual environment that adds this development version of SciPy to
the Python path
in macOS.
Its companion videos `Anaconda SciPy Dev: Part I (macOS)`_ and
`Anaconda SciPy Dev: Part II (macOS)`_ show many of the steps being performed.
This guide may diverge slightly from the videos over time, with the goal of keeping
this guide the simplest, up-to-date procedure.
.. note::
This guide does not present the only way to set up a development environment;
there are many valid choices of Python distribution, C/Fortran compiler, and
installation options. The steps here can often be adapted for other choices,
but we cannot provide documentation tailored for them.
This guide assumes that you are starting without an existing Python 3 installation.
If you already have Python 3, you might want to uninstall it first to avoid
ambiguity over which Python version is being used at the command line.
.. _quickstart-mac-build:
Building SciPy
--------------
*Consider following along with the companion video* `Anaconda SciPy Dev: Part I (macOS)`_
#. Download, install, and test the latest release of the `Anaconda Distribution of Python`_.
In addition to the latest version of Python 3, the Anaconda distribution includes
dozens of the most popular Python packages for scientific computing, the Spyder
integrated development environment (IDE), the ``conda`` package manager, and tools
for managing virtual environments.
#. Install Apple Developer Tools. An easy way to do this is to `open a terminal
window <https://blog.teamtreehouse.com/introduction-to-the-mac-os-x-command-line>`_,
enter the command ``xcode-select --install``, and follow the prompts. Apple
Developer Tools includes `git <https://git-scm.com/>`_, the software we need to
download and manage the SciPy source code.
#. Browse to the `SciPy repository on GitHub <https://github.com/scipy/scipy>`_
and `create your own fork <https://help.github.com/en/articles/fork-a-repo>`_.
You'll need to create a GitHub account if you don't already have one.
#. Browse to your fork. Your fork will have a URL like
`https://github.com/mdhaber/scipy <https://github.com/mdhaber/scipy>`_,
except with your GitHub username in place of "mdhaber".
#. Click on the big, green "Clone or download" button, and copy the ".git" URL to
the clipboard. The URL will be the same as your fork's URL, except it will end in ".git".
#. Create a folder for the SciPy source code in a convenient place on your computer.
`Navigate to it in the terminal
<https://blog.teamtreehouse.com/introduction-to-the-mac-os-x-command-line>`_.
#. Enter the command ``git clone`` followed by your fork's .git URL. Note that
this creates in the terminal's working directory a ``scipy`` folder containing
the SciPy source code.
#. In the terminal, navigate to the ``scipy`` root directory (e.g., ``cd scipy``).
#. Install `Homebrew`_. Enter into the terminal
|br| ``/usr/bin/ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)"`` |br|
or follow the installation instructions listed on the `Homebrew website <https://brew.sh>`_.
Homebrew is a package manager for macOS that will help you download ``gcc``,
the software we will use to compile C, C++, and Fortran code included in SciPy.
#. Use Homebrew to install ``gcc`` by entering the command ``brew install gcc``.
#. In the terminal, ensure that all of SciPy's build dependencies are up to
date: ``conda install pybind11``, then ``conda update cython numpy pytest
pybind11``.
#. (Optional) Check your present working directory by entering ``pwd`` at the
terminal. You should be in the root ``/scipy`` directory, not in a directory
ending ``/scipy/scipy``.
#. Do an in-place build: enter ``python3 setup.py build_ext --inplace``. |br|
This will compile the C, C++, and Fortran code that comes with SciPy.
We installed ``python3`` with Anaconda. ``setup.py`` is a script in the root
directory of SciPy, which is why you have to be in the SciPy root directory to
call it. ``build_ext`` is a command defined in ``setup.py``, and ``--inplace``
is an option we'll use to ensure that the compiling happens in the SciPy
directory you already have rather than the default location for Python packages.
By building in-place, you avoid having to re-build SciPy before you can test
changes to the Python code.
#. Test the build: enter ``python3 runtests.py -v``. ``runtests.py`` is another
script in the SciPy root directory. It runs a suite of tests that make sure
SciPy is working as it should, and ``-v`` activates the ``--verbose`` option
to show all the test output.
If the tests were successful, you now have a working development build of SciPy!
You could stop here, but you would only be able to use this development build
from within the SciPy root directory. This would be inconvenient, for instance,
if you wrote a script that performs an ``import`` of something you changed in
SciPy but wanted to save it elsewhere on your computer. Without taking
additional steps to add this version of SciPy to the |PYTHONPATH|_ ,
this script would ``import`` from the version of SciPy distributed with
Anaconda rather than the development version you just built.
(See `here <https://chrisyeh96.github.io/2017/08/08/definitive-guide-python-imports.html>`__
for much more information about how Python imports modules.)
.. _quickstart-mac-install:
Installing SciPy
----------------
*Consider following along with the companion video* `Anaconda SciPy Dev: Part II (macOS)`_
Currently we have *two* versions of SciPy: the latest release as installed by
Anaconda, and the development version we just built. Ideally, we'd like to be
able to switch between the two as needed. `Virtual environments <https://medium.freecodecamp.org/why-you-need-python-environments-and-how-to-manage-them-with-conda-85f155f4353c>`_
can do just that. With a few keystrokes in the terminal or even the click of an
icon, we can enable or disable our development version. Let's set that up.
#. In a terminal window, enter ``conda list``. |br| This shows a list of all
the Python packages that came with the Anaconda distribution of Python. Note
the latest released version of SciPy is among them; this is not the cutting-edge
development version you just built and can modify.
#. Enter ``conda create --name scipydev``. |br| This tells ``conda`` to
create a virtual environment named ``scipydev``. Note that ``scipydev`` can
be replaced by any name you'd like to refer to your virtual environment.
#. You're still in the base environment. Activate your new virtual environment
by entering ``conda activate scipydev``. |br| If you're working with an old
version of ``conda``, you might need to type ``source activate scipydev``
instead (see `here <https://stackoverflow.com/questions/49600611/python-anaconda-should-i-use-conda-activate-or-source-activate-in-linux)>`__.
#. (Optional) Enter ``conda list`` again. Note that the new virtual environment
has no packages installed. If you were to open a Python interpreter now, you
wouldn't be able to import ``numpy``, ``scipy``, etc.
#. Enter ``conda install cython numpy pytest spyder pybind11``. |br| Note
that we're only installing SciPy's build dependencies (and Spyder so we can
use the IDE), but not SciPy itself.
#. Enter ``conda develop /scipy``, where ``scipy`` is to be replaced with the
full path of the SciPy root directory. |br| This will allow us to ``import``
the development version of SciPy in Python regardless of Python's working
directory. *Note: this step replace the steps shown in*
`Anaconda SciPy Dev: Part II (macOS)`_ *that modify the ``PYTHONPATH``
environment variable when the ``scipydev`` virtual environment is activated.
You can ignore that part of the video from 0:38 to 1:38; this is much simpler!*
#. In a new terminal window, test your setup. If you activate your virtual
environment (e.g., ``conda activate scipydev``) and run Python code that imports
from SciPy, any changes you make to the SciPy code should be reflected when
the code runs. After deactivating the virtual environment (``conda deactivate``),
Python imports from the version of SciPy installed by Anaconda. You can also
check which version of SciPy you're using by executing in Python::
import scipy
print(scipy.__version__)
If you have successfully imported a development version of SciPy, the word
``dev`` will appear in the output, e.g.::
1.4.0.dev0+be97f1a
.. _Anaconda SciPy Dev\: Part I (macOS): https://youtu.be/1rPOSNd0ULI
.. _Anaconda SciPy Dev\: Part II (macOS): https://youtu.be/Faz29u5xIZc
.. _Anaconda Distribution of Python: https://www.anaconda.com/distribution/
.. _Homebrew: https://brew.sh/
.. |PYTHONPATH| replace:: ``PYTHONPATH``
.. _PYTHONPATH: https://docs.python.org/3/using/cmdline.html#environment-variables
.. |br| raw:: html
<br>
|
