[Distutils] INSTALL file

[Greg Ward]

On 22 April 2000, Harry Henry Gebel said:
> I thought some people might find a generic INSTALL file like the one
> supplied with programs that use ./configure, here is one I prepared that
> gives a few lines with the most-common-case installation instructions and
> gives the complete ./setup.py help output.

To be honest, I've never been a big fan of the "standard installation
instructions" modus operandi.  Like the 19k of the GPL, once you've read
the 15k of the standard Autconf INSTALL file, it's really just a waste
to carry it around everywhere.

One way of looking at it is this.  There are two kinds of software
packages in the world: those that build trivially from source, and those
that do not.  For those that do, the build/install instructions are
this:

    python setup.py install

with a proviso about needing privilege to write to the Python library
directory on Unix and a reference to the "Installing Python Modules"
manual for detail.

For those that do not build trivially, the developer will always have to 
write custom build/install instructions.

In the first case, a separate file devoted to build/install is
redundant, since building and installing is painless and trivial, and
anyways there's a nice manual to explain the process if you need to do
anything out of the ordinary.

In the second case, generic build/install instructions are worse than
useless, since the poor user has to figure out what parts of the INSTALL 
file still apply, how to augment that information with information from
the README (assuming the developer even bothered to document the
peculiarities of his package, which is not always a given), etc.

And, as long as I'm bitching...

> The simplest way to compile this package is:
> 
>   1. `cd` to the directory containing the package's source code.

Not necessarily.  Strictly speaking, the source code to the Distutils is
in (eg.) Distutils-0.8/distutils, and you need to be in the
Distutils-0.8 directory; similarly for NumPy and PyXML, and no doubt
many others.  The key is: be in the directory where the setup script
lives.

>   2. Type `./setup.py build` to build the package.

This will only work on Unix, and only if the developer chmod +x'd the
setup script.  (I do this, since I prefer to type "./setup.py" to
"python setup.py".  But I always document it as "python setup.py", since
the standard incantation must be the same on all major platforms.)

>   3. Type `su` to become the superuser

Again, Unix-specific.

>   5. You can remove the compiled extension modules and other installation
>      related files from the source code directory by typing
>      `./setup clean --all clean`. 

Actually, "setup.py clean -a" is enough (-a == --all, of course).

But this isn't really relevant, since I think the right thing to do is
refer people to the "Installing Python Modules" manual.

        Greg
-- 
Greg Ward - geek                                        gward@ase.com
http://starship.python.net/~gward/
Whatever became of eternal truth?