1"Development Mode"
2==================
3
4Under normal circumstances, the ``distutils`` assume that you are going to
5build a distribution of your project, not use it in its "raw" or "unbuilt"
6form.  However, if you were to use the ``distutils`` to build a distribution,
7you would have to rebuild and reinstall your project every time you made a
8change to it during development.
9
10Another problem that sometimes comes up with the ``distutils`` is that you may
11need to do development on two related projects at the same time.  You may need
12to put both projects' packages in the same directory to run them, but need to
13keep them separate for revision control purposes.  How can you do this?
14
15Setuptools allows you to deploy your projects for use in a common directory or
16staging area, but without copying any files.  Thus, you can edit each project's
17code in its checkout directory, and only need to run build commands when you
18change a project's C extensions or similarly compiled files.  You can even
19deploy a project into another project's checkout directory, if that's your
20preferred way of working (as opposed to using a common independent staging area
21or the site-packages directory).
22
23To do this, use the ``setup.py develop`` command.  It works very similarly to
24``setup.py install``, except that it doesn't actually install anything.
25Instead, it creates a special ``.egg-link`` file in the deployment directory,
26that links to your project's source code.  And, if your deployment directory is
27Python's ``site-packages`` directory, it will also update the
28``easy-install.pth`` file to include your project's source code, thereby making
29it available on ``sys.path`` for all programs using that Python installation.
30
31In addition, the ``develop`` command creates wrapper scripts in the target
32script directory that will run your in-development scripts after ensuring that
33all your ``install_requires`` packages are available on ``sys.path``.
34
35You can deploy the same project to multiple staging areas, e.g. if you have
36multiple projects on the same machine that are sharing the same project you're
37doing development work.
38
39When you're done with a given development task, you can remove the project
40source from a staging area using ``setup.py develop --uninstall``, specifying
41the desired staging area if it's not the default.
42
43There are several options to control the precise behavior of the ``develop``
44command; see the section on the :ref:`develop <develop>` command below for more details.
45
46Note that you can also apply setuptools commands to non-setuptools projects,
47using commands like this::
48
49   python -c "import setuptools; with open('setup.py') as f: exec(compile(f.read(), 'setup.py', 'exec'))" develop
50
51That is, you can simply list the normal setup commands and options following
52the quoted part.
53