Question regarding load-path handling for ELPA packages

[Xiyue Deng]

(I'm not sure whether this is the right mailing list for this kind of
question.  Please help redirect if possible.)

Hi,

I would like to understand how package.el handles `load-path' of
installed ELPA packages.  As I observe from load-path after ELPA
packages are initialized, it looks like only the package installation
root path is added to `load-path', but not any of the nested directory.

For example, if an addon `elpafoo` has a nested `elpabar' directory, as
in the following example:

,----
| ~/.config/emacs/elpa/elpafoo/
| ~/.config/emacs/elpa/elpafoo/elpafoo.el
| ~/.config/emacs/elpa/elpafoo/elpabar
| ~/.config/emacs/elpa/elpafoo/elpabar/elpabar.el
`----

For such a package, both `elpafoo.el' and `elpabar/elpabar.el' will be
byte-compiled, but only `~/.config/emacs/elpa/elpafoo' is added to
`load-path', not `~/.config/emacs/elpa/elpafoo/elpabar'.

I was trying to find in package.el source where this is handled but
cannot seem to have a definite answer.  So I wonder whether my current
understanding is correct?  Is this going to be the case forward?  And if
possible which code path is handling this logic?

To give a little more background (probably long), I was studying dh-elpa
which is Debian's tool that handles Emacs addons in a similar fashion as
how ELPA packages are handled, which among other things handles the byte
compiling of the source files to generate *.elc files.  Up to now,
dh-elpa doesn't support nested directories, so if an addon has *.el in a
nest directory they won't be byte-compiled.  This has been working well
up-to-now, but I noticed that some ELPA packages (e.g. auctex) have
nested directories and handled like I mentioned above, which dh-elpa
ignores.  I tried to add nested directory handling, which handles the
package installation under `/usr/share/emacs/site-lisp/elpa' and somehow
all nested directories are added to `load-path' as well (it's adding
this directory to package-directory-list but I'm not sure whether this
is the reason of the nested directories being added to `load-path').
Normally this should not be a problem, but for the case of auctex, it
has some source files under `style/' named `url.el', `array.el', etc.,
which collide with system packages and they don't have any `(provide
'foo)' declared in the source files.  So in my Emacs installation, in
which I use eglot-ensure in all prog-mode, eglot was broken as it tries
to load those alternative url.el, array.el and so on instead of the ones
shipped in Emacs, and as they don't have the corresponding `provide', it
causes error and Emacs will stop processing further.

Sorry this is getting a lot longer that it was supposed to be.  So in
the end I have the following questions:

* For ELPA package installed through package.el, should only the
installation root path be added to `load-path'?
  - Or recursively add nested directories will also be considered in the
  future?

* If it happens to be the latter case, is there any guidelines for
packages to avoid potential name collision?

* Would someone kindly provide some pointer to how `load-path' is being
handled as my rusty Elisp is preventing me to fully understand this.

Thanks for reading this unexpectedly (maybe unnecessarily) long post,
and looking forward to any insights.

-- 
Xiyue Deng