[Distutils] The "dist" command

[Greg Ward]

On 23 September 1999, Fred L. Drake, Jr. said:
>   Another possibility:  If a manifest exists, it must be complete; a
> file MANIFEST should be considered an explicit manifest if present at
> the root of the package and default behavior is used.

I'm not sure what you mean by "complete" -- if the defaults are sensible
(get all source files mentioned in or implied by 'packages',
'py_modules', and 'extensions', and toss in README and setup.py) then
the generated distribution will be "complete".  (Minus documentation,
test suite, etc.)

> If there is no
> manifest file, the default should be something like (using your
> syntax, or trying to):
> 
>          *  !*~ !*.bak !RCS !CVS
> 
> (Presuming, of course, that a directory that matches an exclusion rule 
> will not be recursed into.)

Hmm, that's a good idea.  If you were to state the rule explicitly under 
my currently proposed syntax, I think it would actually be

  . *  !*~ !*.bak !RCS !CVS

-- ie. the first "word" ('.' in this case) has to be a directory, under
which the following include/exclude patterns apply recursively.
Unfortunately, I don't think this will work under my proposed
algorithm.  Will have to think about it more tonight.

>  >   - obvious conflict: 'packages' includes 'foo' and manifest
>  >     includes '! foo/*.py' (can't imagine why you'd want this)
> 
>   Perhaps a warning should be issued, but there's no real need to
> protect against operator error.  The resulting dist would be broken
> because it was package improperly.  The warning should be enough to
> get the operator to fix the file selection.

I'm inclined not to worry about it because the distribution would be
broken -- you'll find out soon enough.

>  >   - subtle conflict:  'packages' includes 'foo' and manifest
>  >     includes '! foo/bar.py' (this could well be desired: eg. exclude
>  >     an experimental module from distribution)
> 
>   No conflict here unless the manifest says "! foo/__init__.py"; in
> that case, use a warning as discussed above.

Ditto -- broken distribution, you'll get a warning when you try to build
it (gee, is that build-time check for __init__.py implemented? well,
there's *supposed* to be one!).

>  > Other things we need to look for in creating a source distribution:
>  >   - make sure there's a README
> 
>   Warnings would be sufficient if anything at all is needed; things
> like README and INSTALL are largely policy rather than requirements at
> this level; do you want to have to consider each possible name for
> README?  I'd certainly consider calling it README.txt if it were
> reasonable to distribute the package to non-Unix systems.  Some people
> call it READ.ME, and others README.1st; how many flavors have to be
> automatically detected?  Let's shoot for as few special cases as
> possible.

Fred, I know I'm preaching to the choir with you, but anyone who doubts
the value of standards in these sort of things should spend a few
minutes at

    http://search.cpan.org/

This is a new web site created by Perl wizard Graham Barr.  Turns out
he knows about more than just networking and Perl internals; this is a
*slick* site.

Calling your readme file "README" is only the beginning.  I can give a
bit of leeway for README.txt (not to be friendly to Windows users, but
to Emacs users ;-), but anyone who tries READ.ME or README.1ST or
whatever should be ... ummm ... treated harshly.

While I'm on the pulpit, Eric Raymond's "Software Release Practice
HOWTO" is also recommended reading for the unconverted:

    http://metalab.unc.edu/mdw/HOWTO/Software-Release-Practice-HOWTO.html

>   The line:
> 
> Run 'python setup.py build install' to install this package.

Actually, it looks like "python setup.py install" is looking to be the
preferred way of doing things: if you supply both 'build' and 'install'
commands, *and* you want to build in a funny directory (ie. other than
./build), then you have to supply a --build-base option to both
commands.  Icky, but I can't think of a nice way around it.  (Anyone
with a better idea is welcome to read the source code *before* shooting
from the hip.)  

However, if you specify *just* the install command, you only need to
give it a --build-dir, and it does the right thing.  In other words,

    ./setup.py install --build-base=/tmp/pybuild

works, as does

    ./setup.py build --build-base=/tmp/pybuild \
               install --build-base=/tmp/pybuild

but, sadly,

    ./setup.py build install --build-base=/tmp/pybuild

does not.  (It builds in ./build, and then attempts to install from
/tmp/pybuild.)

Anyways, that's beside the point.  This sort of check is a frill, but
it's the sort of frill I enjoy doing because it's so damn *easy* with
/^P/ languages.

>  > A crazy idea that conflicts with having/requiring 'version' in setup.py:
> 
>   Version should be explicitly specified somewhere.

And I'm inclined to say, "It must be explicitly specified in setup.py"
rather than in any particular source file.  The only problem with this
is that you can't check what version of module foo you have installed
after the fact *unless* there's a database of installed modules.  Since
this is an near-essential feature anyways, I don't see that as such a
big drawback.  Anyways, if you want to know what version of module foo
is installed *without* a module database, then either the __version__
has to be in every bloody module from a distribution, or "the system"
has to know what distribution a module belongs to and what file is that
distribution's "main file" (ie. where the __version__ is)... and that
leads back to a module database again.

Anyone have a problem with requiring the version number be specified in
setup.py?  That means the __version__ attribute in modules has no real
meaning, since dependency checking would have to be done through the
module database.  Probably just as well, since the __version__ attribute
doesn't seem to be consistently used.

Oh yeah, I completely agree with you that all those checks -- README
exists, distribution meta-data supplied, etc. -- should only result in
warnings.  They're not fatal errors, but they are poor manners -- and
polite warnings are a good way to deal with poor manners.

        Greg
-- 
Greg Ward - software developer                    gward@cnri.reston.va.us
Corporation for National Research Initiatives    
1895 Preston White Drive                           voice: +1-703-620-8990
Reston, Virginia, USA  20191-5434                    fax: +1-703-620-0913