[#loading-modes]
== Loading modes

In Eldev the project’s package and its <<local-sources,local-source
dependencies>> have _loading modes_.  This affects exactly how the
package (that of the project or of its local-source dependency)
becomes loadable by Emacs.

Default loading mode is called `as-is`.  It means the directory where
the project (or local sources of its dependency) is located is simply
added to Emacs varible `load-path` and normal Emacs loading should be
able to find required features from there on.  This is the fastest
mode, since it requires no preparation and in most cases is basically
what you want during development.

However, users won’t have your project loaded like that.  To emulate
the way that most of the people will use it, you can use loading mode
`packaged`.  In this mode, Eldev will first build a package out of
your project (or local-source dependency), then install and activate
it using Emacs’ packaging system.  This is quite a bit slower than
`as-is`, because it involves several preparation steps.  However, this
is almost exactly the way normal users will use your project after
e.g. installing it from MELPA.  For this reason, this mode is
recommended for <<continuous-integration,continuous integration>> and
other forms of automated testing.

Other modes include `byte-compiled` and `source`.  In these modes
loading is performed just as in `as-is` mode, but before that Eldev
either byte-compiles everything or, vice-versa, removes `.elc` files.

{since-1-4} Loading mode `compiled-on-demand` is useful primarily to
larger projects that include some computation-intensive code which
needs to be byte-compiled to run in reasonable time.  In this mode,
only when a project file is loaded, e.g. via `require` form, it is
byte-compiled if needed.  In contrast, in mode `byte-compiled` _all_
Elisp files are byte-compiled before a command (e.g. `test`) even gets
to start working.  This makes the mode useful during work on the
project “core” because 1) compilation time is reduced; 2) you can test
or otherwise use the core without even updating higher-level files to
be successfully compilable first.  However, as a drawback, compilation
can run “in the middle” of project’s real code, which can occasionally
cause unforeseen troubles, as well as screw up
<<profiling,profiling>>.

{since-1-7} Mode `noisy-compiled-on-demand` is basically the same,
with the only exception that Eldev prints a message (the same as
during normal compilation) when it decides to recompile something.  In
comparison, `compiled-on-demand` will only write to _stderr_ and only
if there are compilation warnings or errors.  Since having “random”
text inserted in normal program output is potentially disrupting,
especially if said output is processed by another tool, this is not
the default and you have to actively choose between
`compiled-on-demand` and `noisy-compiled-on-demand`.

When using <<evaluating,commands `exec` and `eval`>> with
`compiled-on-demand` mode, you may want to use option `-R`
(`--dont-require`) and then manually `require` only the necessary
features, to reduce the set of files that have to be (re)compiled.

So, after discussing various loading modes, let’s have a look at how
exactly you tell Eldev which one to use.

For the project itself, this is done from the command line using
global option `--loading` (or `-m`) with its argument being the name
of the mode.  Since this is supposed to be used quite frequently,
there are also shortcut options to select specific modes: `--as-is`
(or `-a`), `--packaged` (`-p`), `--source` (`-s`), `--byte-compiled`
(`-c`) and `--compiled-on-demand` (`-o`).  For example, the following
command will run unit-tests in the project, having it loaded as an
Emacs package:

    $ eldev -p test

Remember, that as everything in Eldev, this can be customized.
E.g. if you want to run your project byte-compiled by default, add
this to your `Eldev-local`:

[source]
----
(setf eldev-project-loading-mode 'byte-compiled)
----

For dependencies built from sources local to your machine the mode can
be chosen when calling `eldev-use-local-sources`.  For example:

[source]
----
(eldev-use-local-sources "~/barlib" 'packaged)
----

As mentioned above, loading mode defaults to `as-is`.

There are a few other loading modes useful only for certain projects.
You can always ask Eldev for a full list:

    $ eldev --list-modes

[#indirect-builds]
=== Indirect build information

When a loading mode require Eldev to do something in order to prepare
the project or its <<local-sources,local-source dependencies>> for
loading, it tries to do so silently in that only stderr is normally
displayed.  The purpose is to prevent secondary and partially
unpredictable (more precisely, depending on previous builds) output
from interfering with normal output.  For example, if you run

    $ eldev eval "(some-project-function)"

it might be confusing if the first line of output is instead

    ELC      some-file.el

if the loading mode is `byte-compiled` and `some-file.elc` doesn’t
exist or is out-of-date.  In particular, if such output is then parsed
using some automated tool, this could lead to unexpected errors.

{since-1-10} However, if this is not a concern in your case, you may
want to set variable `eldev-display-indirect-build-stdout` to t.  This
is especially useful if your project’s loading mode is `built` and it
involves some custom non-trivial build steps, like e.g. compilation of
a helper non-Elisp program.

Unlike with some other settings, the main project ignores values in
its local-source dependencies.  Instead,
`eldev-display-indirect-build-stdout` as defined in the main project
affects both the project itself and all local sources at once: only
the main project “knows” if it is important to avoid indirect build
output for it or not.

[#source-directory]
=== Project source directory

{since-1-8} Usually Elisp projects contain their source files directly
in the root directory.  For smaller projects with one or a few files
this is the most convenient setup.  Eldev assumes this is as the
default and effectively just adds project directory to `load-path`
when making project’s features available for loading in Emacs.

However, some bigger projects instead collect the source files in a
subdirectory, to avoid having too many entries at the top, which could
distract from other root contents, or simply make the root directory
view so large that “README” text after it is buried somewhere deep
down.  One example of such a project is {uri-magit}[Magit].

It’s easy to configure Eldev to understand such a layout.  Simply add
the following to project’s file `Eldev`:

[source]
----
(setf eldev-project-source-dirs "lisp")
----

As the name of the variable implies, you can also have _several_
subdirectories if you want.  For example, for project resources:

[source]
----
(setf eldev-project-source-dirs '("lisp" "resources"))
----

Directory names are not fixed and can be anything.  Another option
could be `src`, for example.

[#autoloads]
=== Autoloads

{since-0-6} Autoloaded functions of installed Elisp packages can be
accessed without a `require` form.  To simplify development, Eldev
provides the same functionality for projects regardless of loading
mode, as long as file `PACKAGE-autoloads.el` exists.  This might look
like an unwieldy requirement, but luckily there is
<<autoloads-plugin,a plugin>> for building the file and keeping it
up-to-date as necessary.  The reason this is not enabled by default is
that many projects — especially those not providing user-visible
functionality, or those that consist of a single file — don’t have any
autoloading functions or other forms.

Dependencies built from <<local-sources,local sources>> also have
their autoloads activated regardless of loading mode.  If the
autoloads file is kept up-to-date using <<autoloads-plugin,the
plugin>>, Eldev will take care to do this as needed in these
dependencies too.
