Why is subdirs.el special?
--------------------------

When you start Emacs, any file in load-path that is named subdirs.el
is automatically executed.  Usually what a subdirs.el does is add
subdirectories.  Take a look at yours in your site-lisp/subdirs.el

That's why subdirectories of site-lisp automatically become part of
the load-path when you start Emacs.  Two subdirs.els, strategically
placed in site-lisp and /VERSION/lisp, figure them out and load them.

That makes site-lisp an appealing place to put Elisp packages.  But
there is more subdirs.el could do for you.  For instance, it could add
to Info-default-directory-list and autoloads.

As I write this, package maintainers generally don't use subdirs.el.
Perhaps they mostly don't know about it.  I hope my package
write-subdirs-el will help change that.

write-subdirs-el
----------------

I recently wrote a package called write-subdirs-el.  It does the work
of creating subdirs.el files for you.  

For maintainers, this means that you can provide easy installation of
complex packages with a single command.  It will handle setting
load-path, finding info files, and doing autoloads.  If you have
requirements beyond that, you can easily add a little code.

For users, this means that when maintainers haven't done that, you can
do it yourself with one easy command.  

I have a vision of a thousand elisp packages that require no more
setup than being placed in site-lisp.  (And sometimes a command-line
"make").  And I imagine a thousand package maintainers who can provide
easy installation for their users with little or no more work then
typing M-x tehom-wse-entry.


Security of subdirs.el
----------------------

Has the security of subdirs.el been overlooked?  I haven't seen any
discussion of it.

Don't get me wrong.  I trust most package maintainers.  I know the
maintainers of most packages I use, and they're all nice guys.  No
exceptions yet.

Still, there's something a little bit scary about the fact that emacs
will run any subdirs.el in load-path.  A little experiment shows the
danger.

I created, in a directory in my load-path: 

A trivial file called stupid-file
A subdirs.el containing:
    (delete-file "./stupid-file")

Then I started (another) emacs.  When it had started, stupid-file was
gone.  subdirs.el had erased it.  Good thing it was nothing important.
And it's a good thing no-one has slipped me a malicious
subdirs.el... yet.  I'll watch for that file when I install a package
from now on!

One possible fix, secure but more constricting, would be to bind
`obarray' to another obarray when subdirs.el are being run, and intern
only obviously safe functions in it.

Another possible fix, less secure, would be to disable certain
commands when auto-running subdirs.el's.  This would include at least
anything that makes changes to disk (`delete-file',
`delete-directory', what else?), anything that gives commands to a
foreign interpreter (`run-lisp', `run-octave', `run-scheme',
`run-prolog', what else?), `enable-command' itself.  What else?


How it works internally
-----------------------

(Aka the boring stuff at the end)

load-path/subdirs.el all works in a funny way between
normal-top-level-add-to-load-path and normal-top-level:
normal-top-level-add-to-load-path carefully adds directory names to
the end of load-path, so that even directories that are added by
subdirs.el will have their own subdirs.els processed by
normal-top-level.

This gets even weirder if subdirs.el tries to manage itself: A
subdirs.el that adds its own directory to load-path would get
processed twice, once initially, once when it's found in load-path.
That's bad, because all subdirs.els have to carefully guard against
the case of double execution.  It would be much better to impose no
special hazards on subdirs.el

And unfortch, subdirs.els can't just chop themselves out of the
load-path, because normal-top-level thinks it knows load-path and
could become confused.  We could remove stuff when we're all done, but
that adds more complexity.

So what I did is create a variant of
normal-top-level-add-to-load-path, called
tehom-normal-top-level-add-to-load-path, that tries to assure that a
subdirs.el is run only once.

It assumes that if both subdirs.el and .nosearch are seen, that means
that the directory will not be put in load-path, but other things
should be done, eg placing subdirectories into load-path.  In that
case, it executes subdirs.el immediately.

If it sees only subdirs.el, it assumes that subdirs.el handles that
directory tree and doesn't explore it.  In that case it doesn't
directly execute subdirs.el, it adds it to the load-path, which will
cause it to be executed later.  It's OK if subdirs.el foolishly tries
to add its own directory to load-path, because at that point it will
have already been seen and thus wouldn't get added.

In all other cases, it behaves the same as
normal-top-level-add-to-load-path.


----------------