diff options
| -rwxr-xr-x | setuptools.txt | 87 |
1 files changed, 85 insertions, 2 deletions
diff --git a/setuptools.txt b/setuptools.txt index f68244fa..f7a85c4e 100755 --- a/setuptools.txt +++ b/setuptools.txt @@ -960,10 +960,9 @@ There are several options to control the precise behavior of the ``develop`` command; see the section on the `develop`_ command below for more details. -Distributing a ``setuptools``-based package +Distributing a ``setuptools``-based project =========================================== - Using ``setuptools``... Without bundling it! --------------------------------------------- @@ -997,6 +996,88 @@ you can specify the exact version and base download URL as parameters to the ``use_setuptools()`` function. See the function's docstring for details.) +What Your Users Should Know +--------------------------- + +In general, a setuptools-based project looks just like any distutils-based +project -- as long as your users have an internet connection and are installing +to ``site-packages``, that is. But for some users, these conditions don't +apply, and they may become frustrated if this is their first encounter with +a setuptools-based project. To keep these users happy, you should review the +following topics in your project's installation instructions, if they are +relevant to your project and your target audience isn't already familiar with +setuptools and ``easy_install``. + +Network Access + If your project is using ``ez_setup``, you should inform users of the need + to either have network access, or to preinstall the correct version of + setuptools using the `EasyInstall installation instructions`_. Those + instructions also have tips for dealing with firewalls as well as how to + manually download and install setuptools. + +Custom Installation Locations + You should inform your users that if they are installing your project to + somewhere other than the main ``site-packages`` directory, they should + first install setuptools using the instructions for `Custom Installation + Locations`_, before installing your project. + +Your Project's Dependencies + If your project depends on other projects that may need to be downloaded + from PyPI or elsewhere, you should list them in your installation + instructions, or tell users how to find out what they are. While most + users will not need this information, any users who don't have unrestricted + internet access may have to find, download, and install the other projects + manually. (Note, however, that they must still install those projects + using ``easy_install``, or your project will not know they are installed, + and your setup script will try to download them again.) + + If you want to be especially friendly to users with limited network access, + you may wish to build eggs for your project and its dependencies, making + them all available for download from your site, or at least create a page + with links to all of the needed eggs. In this way, users with limited + network access can manually download all the eggs to a single directory, + then use the ``-f`` option of ``easy_install`` to specify the directory + to find eggs in. Users who have full network access can just use ``-f`` + with the URL of your download page, and ``easy_install`` will find all the + needed eggs using your links directly. This is also useful when your + target audience isn't able to compile packages (e.g. most Windows users) + and your package or some of its dependencies include C code. + +Subversion or CVS Users and Co-Developers + Users and co-developers who are tracking your in-development code using + CVS, Subversion, or some other revision control system should probably read + this manual's sections regarding such development. Alternately, you may + wish to create a quick-reference guide containing the tips from this manual + that apply to your particular situation. For example, if you recommend + that people use ``setup.py develop`` when tracking your in-development + code, you should let them know that this needs to be run after every update + or commit. + + Similarly, if you remove modules or data files from your project, you + should remind them to run ``setup.py clean --all`` and delete any obsolete + ``.pyc`` or ``.pyo``. (This tip applies to the distutils in general, not + just setuptools, but not everybody knows about them; be kind to your users + by spelling out your project's best practices rather than leaving them + guessing.) + +Creating System Packages + Some users want to manage all Python packages using a single package + manager, and sometimes that package manager isn't ``easy_install``! + Setuptools currently supports ``bdist_rpm``, ``bdist_wininst``, and + ``bdist_dumb`` formats for system packaging. If a user has a locally- + installed "bdist" packaging tool that internally uses the distutils + ``install`` command, it should be able to work with ``setuptools``. If + it doesn't, please report the problem via the `mailing list`_ so that + either the "bdist" tool in question or setuptools can be modified to + resolve the issue. + + Packaging tools that build binary distributions by running ``setup.py + install`` on the command line or as a subprocess can be made to work with + setuptools by using the ``--single-version-externally-managed`` option, + combined with the standard ``--root`` or ``--record`` options. + See the `install command`_ documentation below for more details. + + Managing Multiple Projects -------------------------- @@ -1773,6 +1854,8 @@ Other ``egg_info`` Options no ``package_dir`` set, this option defaults to the current directory. +.. _install command: + ``install`` - Run ``easy_install`` or old-style installation ============================================================ |