[Python-checkins] commit of r41717 - sandbox/trunk/setuptools/setuptools.txt

[phillip.eby]

Author: phillip.eby
Date: Fri Dec 16 21:15:01 2005
New Revision: 41717

Modified:
   sandbox/trunk/setuptools/setuptools.txt
Log:
Added "What Your Users Should Know" section, telling package developers
what information they should give to their users about dependencies,
network access, system packaging, and other common questions or 
concerns.


Modified: sandbox/trunk/setuptools/setuptools.txt
==============================================================================
--- sandbox/trunk/setuptools/setuptools.txt	(original)
+++ sandbox/trunk/setuptools/setuptools.txt	Fri Dec 16 21:15:01 2005
@@ -960,10 +960,9 @@
 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 @@
 ``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 @@
     no ``package_dir`` set, this option defaults to the current directory.
 
 
+.. _install command:
+
 ``install`` - Run ``easy_install`` or old-style installation
 ============================================================