pkg-autoloads.el vs. pkg-loaddefs.el

pkg-autoloads.el vs. pkg-loaddefs.el

[Ihor Radchenko]

Hello,

According to 43.1 Packaging Basics section of Elisp manual, package
autoloads are saved into pkg-autoloads.el file.

However, on master, there is also `generated-autoload-file' variable
that can override the file name where to write the autoloads. So,
pkg-autoloads.el is not always the file where autoloads are written.

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.

-- 
Ihor Radchenko // yantar92,
Org mode contributor,
Learn more about Org mode at <https://orgmode.org/>.
Support Org development at <https://liberapay.com/org-mode>,
or support my work at <https://liberapay.com/yantar92>

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

[Stefan Monnier via Emacs development discussions.]

> 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