Re: pkg-autoloads.el vs. pkg-loaddefs.el

[Stefan Monnier]

> Further, `elpaa-batch-generate-autoloads' in ELPA/admin/elpa-admin.el
> hard-codes pkg-autoloads.el. And I got a report that in some Emacs
> packages distributed through ELPA (org-mode, tramp, hyperbole), both
> pkg-autoloads and pkg-loaddefs are generated.
[...]
> Finally, all the libraries in Emacs core are using name-loaddefs.el.
>
> I feel confused about where to use which name. There is apparent
> inconsistency in the above facts.

Here's how I see it:

`<pkg>-autoloads.el` is supposed to contain what would have gone into
`lisp/loaddefs.el` if the package were part of Emacs.  I.e. it should
contain the strict minimum necessary to expose the usual entry points to
the package: enough that users of the package usually don't need to do
things like add `require` or touch `auto-mode-alist` in their `.emacs`,
but not so much that users who *don't* use the package pay an undue cost.
ELPA packages can be installed without ever being used, just like
packages bundled with Emacs, and contrary to `lisp/loaddefs.el`,
`<pkg>-autoloads.el` are loaded at startup so the larger they are, the
slower Emacs starts up: it's really important to keep them minimal.

`<pkg>-loaddefs.el` is not "codified" in the same way, but in practice
it contains those autoloads *internal* to a package, i.e. loaded only
once we know the package is being used and typically used to avoid some
undesirable toplevel `require`s inside the package's files (e.g. to
avoid circular dependencies, or to load the different subparts of the
package more lazily).  It's fairly normal for such files to be
significantly larger than the corresponding `<pkg>-autoloads.el`.

I hope someone can work on providing better support for
`<pkg>-loaddefs.el`: Lars (IIRC) has done some of the work for that in
`loaddefs-gen.el`, but I think there's still some "glue" around that's
needed to make it easy for a package developer to start using such
a file (e.g. have `package-vc` and `elpa-admin.el` generate those
files, documenting how to do it, ...).


        Stefan