Skip to content

Be more opinionated for setting up a dev env. #15961

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Dec 22, 2019
Merged

Be more opinionated for setting up a dev env. #15961

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 3 additions & 1 deletion INSTALL.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -159,7 +159,9 @@ FreeType and Qhull
Matplotlib depends on `FreeType <https://www.freetype.org/>`_ (>= 2.3), a
font rendering library, and on `Qhull <http://www.qhull.org/>`_ (>= 2015.2),
a library for computing triangulations. By default, Matplotlib downloads and
builds its own copy of FreeType, and uses its own copy of Qhull.
builds its own copy of FreeType (this is necessary to run the test suite,
because different versions of FreeType rasterize characters differently), and
uses its own copy of Qhull.

To force Matplotlib to use a copy of FreeType or Qhull already installed in
your system, create a :file:`setup.cfg` file with the following contents:
Expand Down
70 changes: 21 additions & 49 deletions doc/devel/contributing.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -53,28 +53,8 @@ Thank you for your help in keeping bug reports complete, targeted and descriptiv
Retrieving and installing the latest version of the code
========================================================

When developing Matplotlib, sources must be downloaded, built, and installed into
a local environment on your machine.

Follow the instructions detailed :ref:`here <install_from_source>` to set up your
environment to build Matplotlib from source.

.. warning::

When working on Matplotlib sources, having multiple versions installed by
different methods into the same environment may not always work as expected.

To work on Matplotlib sources, it is strongly recommended to set up an alternative
development environment, using the something like `virtual environments in python
<http://docs.python-guide.org/en/latest/dev/virtualenvs/>`_, or a
`conda environment <https://docs.conda.io/projects/conda/en/latest/user-guide/tasks/manage-environments.html>`_.

If you choose to use an already existing environment, and not a clean virtual or
conda environment, uninstall the current version of Matplotlib in that environment
using the same method used to install it.

If working on Matplotlib documentation only, the above steps are *not* absolutely
necessary.
When developing Matplotlib, sources must be downloaded, built, and installed
into a local environment on your machine.

We use `Git <https://git-scm.com/>`_ for version control and
`GitHub <https://github.com/>`_ for hosting our main repository.
Expand All @@ -88,19 +68,24 @@ and navigate to the :file:`matplotlib` directory. If you have the proper privile
you can use ``git@`` instead of ``https://``, which works through the ssh protocol
and might be easier to use if you are using 2-factor authentication.

Installing Matplotlib in developer mode
---------------------------------------

It is strongly recommended to set up a clean `virtual environment`_. Do not
use on a preexisting environment!

Building Matplotlib for image comparison tests
----------------------------------------------
A new environment can be set up with ::

Matplotlib's test suite makes heavy use of image comparison tests, meaning
the result of a plot is compared against a known good result. Unfortunately,
different versions of FreeType produce differently formed characters, causing
these image comparisons to fail. To make them reproducible, Matplotlib is, by
default, built with a special local copy of FreeType.
python3 -mvenv /path/to/devel/env

and activated with one of the following::

Installing Matplotlib in developer mode
---------------------------------------
source /path/to/devel/env/bin/activate # Linux/macOS
/path/to/devel/env/Scripts/activate.bat # Windows cmd.exe
/path/to/devel/env/Scripts/Activate.ps1 # Windows PowerShell

Whenever you plan to work on Matplotlib, remember to activate the development
environment in your shell!

To install Matplotlib (and compile the C-extensions) run the following
command from the top-level directory ::
Expand All @@ -115,28 +100,15 @@ reflected the next time you import the library. If you change the
C-extension source (which might happen if you change branches) you
will need to run ::

python setup.py build
python setup.py build_ext --inplace

or re-run ``python -mpip install -ve .``.

Alternatively, if you do ::

python -mpip install -v .

all of the files will be copied to the installation directory however,
you will have to rerun this command every time the source is changed.
Additionally you will need to copy :file:`setup.cfg.template` to
:file:`setup.cfg` and edit it to contain ::

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

So is this not needed anymore?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Not if you always use an editable install.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Are pip and setuptools now smart enough to handle changes to extension code in editable mode? My sense is that editable mode works great for changes to existing python modules, but not beyond that.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

C files are mentioned above and still have the note "rebuild if you edit one of them".

[test]
local_freetype = True
tests = True

In either case you can then run the tests to check your work
environment is set up properly::
You can then run the tests to check your work environment is set up properly::

pytest
python -mpytest

.. _virtual environment: https://docs.python.org/3/library/venv.html
.. _pytest: http://doc.pytest.org/en/latest/
.. _pep8: https://pep8.readthedocs.io/en/latest/
.. _Ghostscript: https://www.ghostscript.com/
Expand Down Expand Up @@ -260,7 +232,7 @@ tools:
* Code with a good unittest coverage (at least 70%, better 100%), check with::

python -mpip install coverage
pytest --cov=matplotlib --showlocals -v
python -mpytest --cov=matplotlib --showlocals -v

* No pyflakes warnings, check with::

Expand Down