Skip to content
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

Jump to bottom

DOC: instructions on installing matplotlib for dev #7229

Merged
merged 4 commits into from
Oct 12, 2016
+48 −20
Merged

DOC: instructions on installing matplotlib for dev #7229

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
c657aa6
DOC: instructions on installing matplotlib for dev
eyurtsev Jan 1, 2015
5cce862
DOC fix build
NelleV Oct 7, 2016
78dc157
ENH added pip install -e . to installation guide
NelleV Oct 8, 2016
6c2748b
DOC better installation guidelines
NelleV Oct 11, 2016
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
16 changes: 0 additions & 16 deletions doc/devel/gitwash/git_development.rst
View file
Open in desktop

This file was deleted.

2 changes: 1 addition & 1 deletion doc/devel/gitwash/index.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -11,6 +11,6 @@ Contents:
git_intro
git_install
following_latest
git_development
setting_up_for_development
git_resources
patching
27 changes: 27 additions & 0 deletions doc/devel/gitwash/matplotlib_for_dev.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,27 @@
.. _matplotlib-for-dev:

=================================================
Installing matplotlib from source for development
=================================================

After obtaining a local copy of the matpotlib source code (:ref:`set-up-fork`),
navigate to the matplotlib directory and run the following in the shell:

::

python setup.py develop
Copy link
Member

Choose a reason for hiding this comment

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

We should probably move to pip install -v -e . as Nathaniel advocates?

Copy link
Member Author

Choose a reason for hiding this comment

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

Can you point me towards that discussing? I missed it.

Copy link
Member

Choose a reason for hiding this comment

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

Most of my discussions with @njsmith about this have been in person.

Copy link
Member Author

Choose a reason for hiding this comment

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

Do you mind explain the logic? It is not a standard way to setup a work environment and the command is unclear and confusing (considering the main use of pip is to download and install from pypi, not local source code).
I've just checked quickly (numpy, scipy, sklearn, etc) and none suggest doing so.

Copy link

Choose a reason for hiding this comment

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

pip install -e just calls setup.py develop, so it doesn't matter much in practice right now. But the general movement is that setup.py is being deprecated and should always be called through pip, because in the hopefully-not-too-distant future pip will know how to invoke non-distutils-based build systems.

As a side note I hesitate to recommend setup.py develop or pip install -e because they kinda inherently screw up your virtualenv (you end up with skew between what pip thinks is installed, what python files you actually have installed, and what compiled files you have installed), but these kinds of installs are really popular anyway so I guess this is a losing battle...

Copy link
Member

Choose a reason for hiding this comment

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

you end up with skew between what pip thinks is installed, what python files you actually have installed, and what compiled files you have installed

What do you mean? An editable install only places a *.egg-link into site-packages, and that's all that it knows is installed, which seems to be fully consistent.

Copy link

Choose a reason for hiding this comment

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

@QuLogic: Try e.g. checking out the matplotlib 1.5 branch, doing an editable install, and then after that switch to the master branch for more hacking: git checkout master. Now pip thinks your virtualenv has 1.5 (check out the metadata files in the .egg-info directory -- these only get regenerated if you re-do the editable install), but it actually has a mix of master's .py files and 1.5's extension modules. Rebuild the extension modules alone, and now you have a consistent installation of master (2.x) but pip still thinks it's 1.5. Then pip install some package that depends on matplotlib (>=2.0) and pip will freak out and try to uninstall your dev version, because it isn't good enough, even though it is, etc. You can make it work, but it's intrinsically flaky and you have to be constantly aware of all the weird pitfalls.

@NelleV:

I used to reinstall matplotlib every time, but it has become a pain now that the git hash is appended to the version.

I assume you're referring to the thing where pip refuses to install "matplotlib 2.1.dev1+git123" if you already have "matplotlib 2.1.dev1+git456"? Yeah :-(. This is an incredibly frustrating bug that will eventually be fixed :-(. (The pip maintainers at least have finally come around to consensus that it is a bug that needs fixing, but unfortunately the patch got tangled up in the bikeshed around fixing pip install -U and is temporarily stalled out.)

Copy link
Member

Choose a reason for hiding this comment

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

but it actually has a mix of master's .py files and 1.5's extension modules.

Yes, it fails to load then, and as noted in another PR, you need to re-install to update modules whose source files have changed.

Rebuild the extension modules alone

How would you only rebuild the modules? With setup.py build_ext? But then you've side-stepped pip anyway.

Copy link

Choose a reason for hiding this comment

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

@QuLogic: I'm not saying you can't make it work if you do the right thing. But in general the only wholly reliable way to make it work is to re-run the editable install after every time you change the source; then there are a bunch of special cases where it also works. If you're willing to pay the cognitive overhead to learn and keep track of all those special cases, that's cool, I'm not going to stop you :-). I'm just explaining why I hesitate to recommend it. If you don't want to keep track of that stuff and want to be confident things work reliably, then you'll be re-running the install after every edit so you might as well use a regular install instead of an editable install and avoid the traps entirely :-). (Modulo hopefully-fixed-soon issue @NelleV points to where pip install . often fails for no good reason when pip install -e . succeeds.)

(You can also imagine in-between things, like a script that continuously runs pip install . every time you change a file.)

Copy link
Member

Choose a reason for hiding this comment

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

A vast majority of the work that needs to be done on mpl is in the pure-python layers, so a source install can be very convenient.


or::

pip install -v -e .

This installs matplotlib for development (i.e., builds everything and places
the symbolic links back to the source code). This command has to be called
everytime a `c` file is changed. Note that changing branches may change the
`c`-code.

When working on bleeding edge packages, setting up a
`virtual environment
<http://docs.python-guide.org/en/latest/dev/virtualenvs/>`_ or a `conda
environment <http://conda.pydata.org/docs/using/envs.html>`_ is recommended.

17 changes: 17 additions & 0 deletions doc/devel/gitwash/setting_up_for_development.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,17 @@
.. _setting_up_for_development:

==========================
Setting up for development
==========================

Contents:

.. toctree::
:maxdepth: 2

forking_hell
set_up_fork
matplotlib_for_dev
configure_git
development_workflow
dot2_dot3
6 changes: 3 additions & 3 deletions doc/devel/release_guide.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,8 +1,8 @@
.. _release-guide:

**************************
Doing a matplotlib release
**************************
*************
Release Guide
*************

A guide for developers who are doing a matplotlib release.

Expand Down