Eldev

Here is a non-exhaustive list of projects that use Eldev and can serve as examples. I intentionally list only my own projects, even if there are others, because this way it’s easier to ensure that the comments below stay valid. Eldev source code itself comes with no examples: I think real-world usage provides better models.

All these projects also use continuous integration on GitHub for automated testing. Various elements of files Eldev in these projects are documented below.

Eldev bootstraps itself when needed, but won’t automatically fetch new versions. To upgrade it later, explicitly run (from any directory):

By default it uses MELPA Stable. If you want to test or use some not yet officially released version, try:

This will make it use MELPA Unstable for upgrading. If you want to switch back to the latest stable version (as recommended), supply -d (--downgrade) option to the command:

If your project uses Git hooks, you can take advantage of Eldev’s command githooks to install them:

Eldev doesn’t try to enforce any hooks on you, instead, it only symlinks the files the project has in directory githooks to the place Git expects them. For security reasons, Git doesn’t activate any hooks by default upon repository cloning, this has to be an explicit decision — be that copying by hands or an Eldev invocation.

If you don’t have such a subdirectory, command will not do anything and will also not be shown in the output of eldev help.

Eldev tries to create a self-contained environment for building and testing your project. It will isolate your project as much as possible from your “normal” Emacs, i.e. the one that you use for editing. This is done to avoid interference from your other installed packages or configuration, to prevent broken and misbehaving projects from affecting your Emacs and, finally, to simplify testing of certain “permanent effect” features, like customizing variables.

Starting with version 0.8 you can opt out of some of the default project isolation features and use preinstalled dependencies, e.g. those from your normal Emacs. To activate this mode, use global option --external (-X), e.g.:

In this mode Eldev will expect dependencies to be installed in given directory (standard Emacs location — ~/.emacs.d/elpa — is only the default: you can use another directory). If a dependency is not installed, Eldev will not install it on its own: it doesn’t know which package archives should be used. Likewise, it will not upgrade anything. In all such cases, i.e. when required dependencies are not correctly preinstalled in the specified external directory, Eldev will simply fail.

Local dependencies discussed later take precedence even in this mode: anything declared as local will override dependencies available from an external directory, just like it will in usual full isolation mode.

This mode can be useful to load exactly the same dependency versions as those installed in your normal Emacs. However, it is not suitable for continuous integration or for working on packages that you do not have — for whatever reason — installed normally. It is also difficult to test on different Emacs versions in external directory mode. Therefore, it is not the default. But, as usual in Eldev, you can make it the default in file ~/.config/eldev/config if you want.

There is also a way to disable dependency management completely. However, other than in few very special cases you should prefer normal operation.

Imagine you are developing more than one project at once and they depend on each other. You’d typically want to test the changes you make in one of them from another right away. If you are familiar with Cask, this is solved by linking projects in it.

Eldev provides a more flexible approach to this problem called local dependencies. Let’s assume you develop project foo in directory ~/foo and also a library called barlib in ~/barlib. And foo uses the library. To have Eldev use your local copy of barlib instead of downloading it e.g. from MELPA, add the following form in file ~/foo/Eldev-local:

Note that the form must not be added to Eldev: other developers who check out your project probably don’t even have a local copy of barlib or maybe have it in some other place. In other words, this should really remain your own private setting and go to Eldev-local.

Local dependencies have loading modes, just as the project’s package itself. Those will be discussed later.

Eldev correctly handles situations with changing definitions of local dependencies. I.e. by simply commenting out or uncommenting eldev-use-local-dependency call, you can quickly test your project both with a MELPA-provided package and with a local dependency — Eldev will adapt without any additional work from you.

It is possible to register additional dependencies for use only by certain Eldev commands. Perhaps the most useful is to make certain packages available for testing purposes. For example, if your project doesn’t depend on package foo on its own, but your test files do, add the following form to Eldev file:

Additional dependencies are looked up in the same way as normal ones. So, you need to make sure that all of them are available from the package archives you instructed Eldev to use.

The following commands make use of additional dependencies: build, emacs, eval, exec and test. Commands you define yourself can also take advantage of this mechanism, see function eldev-load-project-dependencies.

Sometimes it is useful to check what a project depends on, especially if it is not your project, just something you have checked out. There are two commands for this in Eldev.

First is dependencies (can be shortened to deps). It lists direct dependencies of the project being built. By default, it omits any built-in packages, most importantly emacs. If you want to check those too, add option -b (--list-built-ins).

Second is dependecy-tree (short alias: dtree). It prints a tree of project direct dependencies, direct dependencies of those, and so on — recursively. Like with the first command, use option -b if you want to see built-ins in the tree.

Both commands can also list additional dependencies if instructed: just specify set name(s) on the command line, e.g.:

You can also check which archives Eldev uses to look up dependencies for this particular project with the following command:

Eldev will install project dependencies automatically, but it will never upgrade them, at least if you don’t change your project to require a newer version. However, you can always explicitly ask Eldev to upgrade the installed dependencies:

First, package archive contents will be refetched, so that Eldev knows about newly available versions. Next, this command upgrades (or installs, if necessary) all project dependencies and all additional dependencies you might have registered (see above). If you don’t want to upgrade everything, you can explicitly list names of the packages that should be upgraded:

You can also check what Eldev would upgrade without actually upgrading anything:

If you use MELPA for looking up dependencies, you can switch between Stable and Unstable using global options with the same name, i.e.:

Because of the incompatible version numbers that MELPA Unstable supplies, you cannot directly “upgrade” from an unstable version back to a stable one. But you can specify option -d (--downgrade) to the command:

In this case Eldev will downgrade dependencies if this allows it to use more preferable package archive. (Since --stable is the default, specifying it in the command above is not really needed, it’s only mentioned for clarity.)

To install unstable version of only a specific dependency, while leaving all others at stable versions, combine --unstable with listing package names after the command, e.g.:

Eldev knows how to install certain development tools and also uses predefined package archives for this, not the ones you specify in project’s configuration. This means you don’t need to list archives for tools like Buttercup: only list them if they are needed to look up real dependencies.

There is a simple way to customize where exactly Eldev finds the tools: use variable eldev-known-tool-packages for this. The value of the variable is an alist keyed by tool names and containing package descriptor plists as values. By default it already contains information about the tools Eldev knows about. You can add more or replace existing ones if you need: just push more entries at the beginning of the list, there is no need to actually remove anything.

You can also use the tools as e.g. runtime dependencies if needed (though in most cases you should leave this to Eldev). Just specify package plist as (:tool TOOL-NAME) for this. Both tools with built-in support and any new you add to eldev-known-tool-packages can be referred this way.

Current list of the known tools:

Eldev has limited support for operating without dependency management. This mode can be activated using global option --disable-dependencies (there is no short version to emphasize that it is not recommended). It exists to support certain environments that themselves provide a suitable value for Emacs variable load-path via environment variable EMACSLOADPATH. An example of such an environment is GUIX package building.

Unlike in preinstalled-dependency mode described earlier, here Eldev doesn’t work with dependencies (and tools) as standard Emacs packages at all. Instead, everything is expected to be loadable using require form without any further setup. For this, variable load-path must be set appropriately, most likely using EMACSLOADPATH (though you could, in principle, set its value in e.g. Eldev-local).

One consequence of this mode is that Emacs package system won’t consider dependency packages installed at all, see package-installed-p. Autoloads are not supported in this mode (neither for dependencies nor for the project itself), so you must explicitly require all features before using them. There might be other, unexpected, limitations as well, as this mode is not thoroughly tested.

Unless you need to build packages for GUIX or have some comparable environment that computes load-path on its own and doesn’t let Eldev manage dependencies normally by accessing standard package archives, you shouldn’t use this mode.

To avoid downloading the same packages repeatedly, Eldev employs a package archive cache. This cache is shared between all projects and all Emacs versions on your machine. It can significantly speed up package preparation if you use a new project, test it on another Emacs version or delete project-specific cache (subdirectory .eldev) for whatever reason.

By default, downloaded packages stay cached indefinitely, while archive contents expires in one hour. However, if you use command upgrade or upgrade-self, package archive contents is always refreshed.

Cache usage is not controllable from command line. However, you can customize it somewhat in ~/.config/eldev/config. Variable eldev-enable-global-package-archive-cache lets you disable the global cache outright. Using eldev-global-cache-archive-contents-max-age you can adjust how long cached copies of archive-contents stay valid.

When a loading mode require Eldev to do something in order to prepare the project or its local 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

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

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.

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 local dependencies. Instead, eldev-display-indirect-build-stdout as defined in the main project affects both the project itself and all local dependencies at once: only the main project “knows” if it is important to avoid indirect build output for it or not.

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 Magit.

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

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

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

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 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.

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

Build system is based on targets. Targets come in two kinds: real and virtual. First type of targets corresponds to files — not necessarily already existing. When needed, such targets get rebuilt and the files are (re)generated in process. Targets of the second type always have names that begin with “:” (like keywords in Elisp). Most import virtual target is called :default — this is what Eldev will build if you don’t request anything explicitly.

To find all targets in a project (more precisely, its main target set):

Project’s targets form a tree. Before a higher-level target can be built, all its children must be up-to-date, i.e. built first if necessary. In the tree you can also see sources for some targets. Those can be distinguished by lack of builder name in brackets. Additionally, if output is colored, targets have special color, while sources use default text color.

Here is how target tree looks for Eldev project itself (version may be different and more targets may be added in future):

And a short explanation of various elements:

To build an Elisp package out of your project, use command package:

This command is basically a wrapper over the build system, it tells the system to generate virtual target :package. However, there are a few options that can only be passed to this special command, not to underlying build.

Files that are copied to the package .tar default to Elisp files plus standard documentation: *.info, doc/*.info and files dir along those. However, if you need to package additional files, just modify variable eldev-files-to-package. Its value must be a fileset. In particular, you can extend the default value, making a composite fileset, instead of replacing it. Here is an example from Eldev’s own file Eldev:

Here we instruct package builder to copy all files from subdirectory bin, except those with names ending in .in or .part, additionally to the standard files. If you distribute your package through MELPA, you will unfortunately need to repeat these instructions in MELPA recipe.

Normally, packages are generated in subdirectory dist (more precisely, in directory specified by eldev-dist-dir variable). If needed, you can override this using --output-dir option.

By default, Eldev will use package’s self-reported version, i.e. value of “Version” header in its main .el file. If you need to give the package a different version, use option --force-version. E.g. MELPA would do this if it used Eldev.

Finally, if you are invoking Eldev from a different tool, you might be interested in option --print-filename. When it is specified, Eldev will print absolute filename of the generated package and word “generated” or “up-to-date” as the two last lines of its (stdout) output. Otherwise it is a bit tricky to find the package, especially if you don’t use --force-version option. As an optimisation, you can also reuse previous package file if Eldev says “up-to-date”.

You can use Eldev to byte-compile your project. Indirectly, this can be done by selecting appropriate loading mode for the project or its local dependencies. However, sometimes you might want to do this explicitly. For this, use command compile:

You can also byte-compile specific files:

Eldev will not recompile .el that have up-to-date .elc versions. So, if you issue command compile twice in a row, it will say: “Nothing to do” the second time.

However, simple comparison of modification time of .el and its .elc file is not always enough. Suppose file foo-misc.el has form (require 'foo-util). If you edit foo-util.el, byte-compiled file foo-misc.elc might no longer be correct, because it has been compiled against old definitions from foo-util.el. Luckily, Eldev knows how to detect when a file requires another. You can see this in the target tree:

As a result, if you now edit foo-util.el and issue compile again, both foo-util.elc and foo-misc.elc will be rebuilt.

Eldev treats warnings from Emacs’ byte-compiler just as that — warnings, i.e. they will be shown, but will not prevent compilation from generally succeeding. However, during automated testing you might want to check that there are no warnings. The easiest way to do it is to use --warnings-as-errors option (-W):

Command compile is actually only a wrapper over the generic building system. You can rewrite all the examples above using command build. If you don’t specify files to compile, virtual target :compile is built. This target depends on all .elc files in the project.

However, there is a subtle difference: for compile you specify source files, while build expects targets. Therefore, example

above is equivalent to this command:

with .el in filenames substituted with .elc.

While cleaning is not really part of the build system, it is closely related. Cleaning allows you to remove various generated files that are the result of other commands (not only build). Command can be executed without any arguments:

In this case, it removes byte-compiled Elisp files and any .info files generated from .texi/.texinfo if you have those in your project.

In general case, you can specify name one or more cleaners as command arguments. All supported cleaners can be found using option --list-cleaners (-L). Here is a short list of some of the more useful ones:

Cleaners executed by default are called .elc, .info and info-dir. Normally, they delete their targets in all target sets at once. However, you can limit them to main, test and so on set with option -s (--set), e.g. command:

would delete all byte-compiled test files.

You can also specify option -n (--dry-run) to see what would be deleted, without actually deleting it.

As stated above, Eldev supports ERT (Emacs built-in), Buttercup, Doctest and Ecukes testing frameworks. With the exception of Doctest, you don’t need to specify which framework the project uses, as the tool can autodetect that. But in some cases (for Doctest — always) you may need to set variable eldev-test-framework to either 'ert, 'buttercup, 'doctest or 'ecukes, as appropriate. It is also possible to use more than one framework in a project, see below. You don’t need to declare testing package(s) as extra dependencies: Eldev will install them itself when needed.

Eldev tries to provide uniform command line interface to the supported frameworks, but of course there are many differences between them.

Eldev supports using test of different types in one project, in any combination of supported frameworks. In fact, its autodetection will work even in such cases. However, especially when using different test types, it might be useful to set variable eldev-test-framework to a list of the frameworks the project uses. E.g.:

The order of elements in the list is important, as this will be the order in which test command calls the different frameworks.

Command test will apply all its options and selectors to all frameworks (autodetected or specified explicitly as above) at once. Additionally, when tests of different types are invoked, the command will print a short summary over all types.

Often, however, you don’t want to mix different test types and instead run them using separate commands. This is especially useful when you specify selectors, because those are often different across frameworks. In this case you can use commands test-FRAMEWORK or their shorter aliases FRAMEWORK. The syntax and behavior of these commands is the same as that of test, with the only difference that only one, specified, framework is used. These commands are available in all project. However, they are not “advertised”, i.e. not shown in output of eldev help, unless you set variable eldev-test-framework to a list of at least two elements.

Example usage:

It is also possible to specify filesets that limit test file selection for each framework, using variables eldev-test-FRAMEWORK-fileset. If you often use single-framework commands, these filesets can speed up testing by not loading unneeded files. For example, if you have ERT tests in one file called ert.el and a lot of files with Buttercup tests, you could add this to file Eldev:

There appears to be two common ways of using tests: 1) they are loaded from project root; 2) subdirectory test/ (or similar) in the project is added to load-path. Eldev supports both. First one is the default, since it doesn’t require anything in addition.

To better understand the second way, imagine your project structure is like this:

and file test-my-project.el includes a form (require 'test-helper). Naturally, this setup will work only if subdirectory tests/ is in load-path by the point tests are executed. To instruct Eldev that your project needs this, add the following to file Eldev:

where 'test is the command name and "tests" is the name of the subdirectory that should serve as additional loading root. In principle, loading roots can also be used for other commands too, just like extra dependencies.

If you want to switch to the first way and avoid special forms in file Eldev, replace (require 'test-helper) with (require 'tests/test-helper).

ERT provides a few selectors that operate on tests’ last results. Even though different Eldev executions will run in different Emacs processes, you can still use these selectors: Eldev stores and then loads last results of test execution as needed.

For example, execute all tests until some fails (-s is a shortcut for --stop-on-unexpected):

If any fails, you might want to fix it and rerun again, to see if the fix helped. The easiest way is:

For more information, see documentation on ERT selectors — other “special” selectors (e.g. :new or :unexpected) also work.

For Ecukes there is a comparable feature, though only for failing scenarios. Internally it is implemted differently, as it is built into the framework itself, but from the interface point of view it works almost exactly the same: specify selector :failed or :failing on the command line:

When variable eldev-dwim (“do what I mean”) is non-nil, as by default, Eldev supports a few simplifications of the command line to make testing even more streamlined.

If you dislike these simplifications, set eldev-dwim to nil in ~/.config/eldev/config.

Eldev comes with a way to “lint” the project and its checkout too. Just run:

This will check the project for a few common potential problems. All the warnings come with quite verbose explanations, detailing what the doctor thinks is wrong, why and how to fix that. However, it’s up to you to decide what and if anything at all should be done — the doctor doesn’t, and actually cannot, fix anything itself.

Here is the current list of available checks, to give an idea of what it verifies:

Profiling is most useful with commands eval and exec. Additionally, those have certain options targeted especially at profiling, though they could, of course, be used in other cases.

Options --macroexpand and --compile (-m and -c) make the commands preprocess their expressions accordingly; by default expressions are simply evaluated using Elisp interpreter.

Option --repeat (-n) lets you evaluate the same expression(s) multiple times. This is useful if normal evaluation is too fast for a meaningful profile. If the command eval is used, only the last result is printed. However, any side effects (including printing) will be observable that many times, so keep that in mind!

For example:

Alternatively, if you are on a Linux or macOS system and have Docker or (since 1.10) Podman installed, you can run arbitrary Eldev commands within containers based on the images distributed by docker-emacs. For example:

will start an Emacs 27.2 container and run eldev emacs --eval '(insert (format "Emacs version: %s" emacs-version))' in it.

Podman, from Eldev’s point of view, works just the same. There is a special command for it, but it is basically indistinguishable (except for the name):

This command can be used not only to start Emacs of given version, but to run any Eldev command. For example, run project’s tests on an older editor version:

or evaluate something using project’s functions:

Docker’s (Podman’s) output is forwarded to normal Eldev output, however, because of Elisp limitations, it all ends up on Eldev’s stdout! There might also be unwieldy delays, so that output doesn’t come smoothly as generated by the process inside Docker, but instead in larger chunks. Before Eldev 1.2 the output would instead only appear when Docker has exited.

It is also possible to use a custom image. For this, replace Emacs version argument (26.3 in the last example above) with the full image name. The image must contain a preinstalled Emacs of a version supported by Eldev (i.e. 24.4 and up), but not Eldev itself.

Additionally, docker run arguments are customisable via the variable eldev-docker-run-extra-args (and likewise for Podman: eldev-podman-run-extra-args). For example, adding the following to your project’s Eldev:

will set the container name to “my_cool_container”.

The easiest option for continuous integration for GitHub-hosted projects are GitHub workflows, as this doesn’t involve using a 3rd-party service. Probably most of Elisp projects can take advantage of this, since GitHub appears to be the most popular hosting for Elisp projects. Workflow definition files for GitHub are somewhat more verbose than for Travis CI, but ultimately not really more complicated.

The easiest way to install Emacs binary of appropriate version is to use jcs090218/setup-emacs action (which internally uses nix-emacs-ci). There are other setup-emacs actions around, but this one works across all operating systems. Since EVM seems tuned to Ubuntu Trusty (i.e. what Travis CI provides), it is likely unsuitable for GitHub workflows.

There is a simple action called setup-eldev too. It works on all GitHub-supported operating systems — Linux, macOS and Windows — as well.

A basic workflow file (you can e.g. name it .github/workflows/test.yml) would look something like this:

Eldev’s terminal autorecognition doesn’t work on GitHub machines (unlike e.g. on Travis CI). If you want colored output from Eldev, you need to explicitly enable it using -C (--color) global option.

Travis CI is perhaps the most used continuous integration service for Elisp code, at least until the addition of GitHub workflows. The largest problem on Travis CI is to install Emacs binary of the desired version. Luckily, there are tools that can be used for this: at least EVM and nix-emacs-ci.

Another frequently used service is CircleCI. I don’t know that much about it, presumably nix-emacs-ci can be used to install Emacs on it. Some projects successfully use Docker images.

Regardless of how you install Emacs, adding Eldev is yet another one-liner. It is handy to use, because propagating PATH modifications between different commands on CircleCI is somewhat non-obvious. To use it, add the following lines in the relevant place in file .circleci/config.yml:

Once you have Emacs with Eldev set up on the continuous integration server of your choice, it is time to actually test your project. The most basic command is, naturally, eldev test. You might want to add a few options to both make project loading more similar to that typical for your users and Eldev’s output more informative:

To make sure that your project byte-compiles cleanly, use the following command:

Or maybe even this, if you want to make sure that test .el files also can be byte-compiled without warnings (this can sometimes catch more problems):

You can also enforce conformance to certain coding standards by adding an invocation of lint to the script part. Remember, however, that most linters are continuously being developed. Even if a linter finds your source warning-free today, it might detect problems tomorrow. relint is probably one of the “safer” linters in this regard:

Eldev can make your continuous integration runs more robust. This means that when facing certain externally-caused errors, Eldev will not give up immediately, but rather wait for a while and then retry — several times. This makes CI runs more reliable and less likely to fail because of reasons completely unrelated to your project.

This is a work in progress, as examples of such errors are pretty difficult to collect, as they are intermittent and happen only occasionally. As of 1.5, Eldev will retry if it fails to fetch contents of a package archive. In practice such an error has been observed at least with MELPA and is probably caused by MELPA updates being non-atomic, meaning that at the end of each archive rebuild, there is a relatively short period where its current contents is not properly reported. Another possibility might be network problems.

In any case, normally you don’t even have to do anything to get these improvements in Eldev. They are activated using option --robust-mode (-R), which by default has value “auto”. If this value is unchanged, robust mode is inactive on normal machines (e.g. when you run Eldev locally), but gets activated if environment variable $CI is true, which appears to be an unwritten standard for continuous integration servers. For example, it is set on GitHub workflow servers. Anyway, you can also set this option to “always” or “never” — as you prefer.

There are two common ways of debugging code: interactively, using a debugger program to step through the code and determine at which place things go wrong, and non-interactively, by adding debugging output to relevant places in the code. While Eldev cannot really help you with interactive debugging, it provides several functions useful for generating debugging output.

The main such function is predictably called eldev-debug. It accepts the same arguments as message and writes the output to stderr in a standing-out color.

If you launch interactive Emacs with your project, output of the function comes to Emacs stderr, i.e. the console from which you have started up Eldev. This makes debugging output more visible and easily relatable to things going on in Emacs: you have two separate OS-level windows and just need to arrange them in such a way that they don’t cover each other. Additionally, the whole project setup procedure is repeated in such Emacs instances, so e.g. files Eldev or Eldev-local can easily affect those too.

You can call eldev-debug from your project’s code directly or from an advice defined in Eldev-local. E.g. you could temporarily add something like this:

This will log all calls to my-function on the stderr, along with arguments and produced result.

If you need to see how several functions call each other, linear logs produced by advices as above may be too confusing. In such a case you may be interested in macro eldev-nest-debugging-output, which indents all Eldev-generated debugging output inside its body. It is also useful to split output shown above into two lines: one for when a function gets called and another — when it returns:

Assuming you have similar advices for other functions that call each other, output might look something like this:

Macro eldev-dump reuses eldev-debug to show the current value of its argument variable(s) or even arbitrary form(s) in a human readable way:

prints

This allows you to save some typing on debugging output forms that are meant to be temporary anyway and get changed quickly.

A pretty useful function to generate debugging output is eldev-backtrace. In some cases it is quite difficult to understand how a function gets called (with given arguments). Seeing a backtrace can help you out. Using different project loading modes can be useful here: sometimes a backtrace in a byte-compiled code is more readable and provides the information you need, while in other cases you rather need non-compiled forms.

Global option -u (--cut-backtraces) lets you make backtraces more informative by omitting the common outermost frames. This becomes particularly useful if you call eldev-backtrace more than once in order to compare the output. Eldev itself will put “notches” in backtraces when it invokes project code, and will later cut the result of eldev-backtrace at the deepmost encountered notch. You can also do the same — which might be even more useful — with macro eldev-backtrace-notch. Cutting is not applied to backtraces that are printed because of errors in combination with option -d.

Macro eldev-time-it can be used to roughly estimate performance of pieces of code and understand where your project becomes too slow.

Functions and macros above also come in “conditional” form: just add x before function name, e.g. eldev-xdebug, eldev-xdump, etc. These functions by default do nothing, but can be activated or deactivated using one of eldev-enabling-xdebug, eldev-disabling-xdebug, eldev-maybe-xdebug, eldev-maybe-enabling-xdebug and eldev-maybe-disabling-xdebug macros, all with different semantics explained in their in-Emacs documentation. Global option -x also activates eldev-xdebug-like output initially (can still be deactivated programmatically later). Appropriate usage can drastically reduce debugging output size in a deeply nested calltree and limit it to only relevant (to the bug you are investigating) portions.

Another technique to reduce debugging output is to activate it only after the project has been fully loaded and initialized — depending on the project, the setup can involve quite a lot of function calls on its own, e.g. from computation of constants, eval-when-compile forms and so on. In this case it might be useful to install debugging advices inside a with-eval-after-load form.

It is, generally, a good idea to use Eldev calls only in files Eldev and Eldev-local. Actual project source code should be limited to using Eldev only while debugging — in all other cases Eldev is hardly a proper dependency, at least for most projects. However, as I have found from experience, it is pretty easy to forget and accidentally commit debugging output changes that were meant only as a temporary aid for investigating one specific issue.

If you use Git as your VCS, you may want to employ Git hooks that prevent such accidental commits. Eldev even has a special command for that.

The following is an overview of Eldev features that can help you in debugging project setup scripts and Eldev — which is also not bug-proof — itself.

A plugin that enables automatic collection of functions and other forms marked with ;;;###autoload cookie in project’s .el files. It tries to behave exactly the same as for installed Elisp packages, so that there are no differences between development and installed versions of the project.

The plugin is not on by default because many projects don’t use autoloading functionality at all and having file PACKAGE-autoloads.el magically appear all the time in them would be annoying.

To have autoloads automatically collected in your project, just activate the plugin: add form (eldev-use-plugin 'autoloads) to the project’s file Eldev. You don’t need any additional steps to instruct Eldev how to use the generated file. In fact, it is able to do this even without the plugin: the plugin only takes cares to build and update the file as necessary.

If the plugin is activated, you can see new target :autoloads in the output of targets command. In addition to being built by default, this file is also generated whenever Eldev needs to load the project: for commands test, eval, exec and emacs. Finally, the file is also registered as a dependency to all .elc targets in the project; this way, byte-compiling always has access to up-to-date list of autoloaded functions.

This plugin can also be activated in projects you use as local dependencies for other projects. Eldev knows how to keep the autoloads file up-to-date in all local dependencies, regardless of their loading mode.

This is a special plugin that adds commands for project’s maintainer use, in fact, currently just one: release. Because not every developer is a maintainer, this command is not enabled by default and is instead available only when the plugin is active, to avoid potential confusion. The recommended way to activate it, therefore, is by adding code:

to your (as maintainer’s) personal file Eldev-local. You can also do this in ~/.config/eldev/config to have the commands available everywhere. If you are the only developer of your project (or simply don’t care), you can of course do this right in file Eldev.

The plugin defines a lot of variables that control its behavior. They are available even if the plugin itself is not active, and it is actually recommended to set them in file Eldev, so that if the plugin is activated, project-specific configuration is already present.

This built-in plugin provides integration with undercover tool that generates coverage reports for your tests. It is active only for command test. By default, behavior of the tool is unaltered (with the exception that reports are not merged), so effectively it will do nothing unless run on a supported continuous integration server.

To have your project’s code coverage statistics automatically gathered during continuous integration, all you need to do is:

The plugin adds two options for command test: --undercover (-u) and --undercover-report (-U). First option can be used to configure the plugin and the tool, the second — to change report filename. Value for the option -u should be a comma and/or space-separated list of any of the following flags:

Additionally, when eldev-dwim is non-nil, certain flags can affect each other:

Based on the above, easiest way to generate a local coverage report is something like this:

Full help for the plugin can always be checked by running eldev plugins in a project with the plugin activated.

From Lisp point of view, a simple fileset is a list of strings. A single-string list can also be replaced with that string. The most important filesets are eldev-main-fileset and eldev-test-fileset. Using them you can define which .el files are to be packaged and which contain tests. Default values should be good enough for most projects, but you can always change them in file Eldev if needed.

Each rule is a string that matches file path — or its part — relative to the root directory. Path elements must be separated with a slash (/) regardless of your OS, to be machine-independent. A rule may contain glob wildcards (* and ?) with the usual meaning and also double-star wildcard (**) that must be its own path element. It stands for any number (including zero) of nested subdirectories. Example:

matches foo/bar-1.el and foo/x/y/bar-baz.el.

If a rule starts with an exclamation mark (!), it is an exclusion rule. Files that match it (after the mark is stripped) are excluded from the result. Other (“normal”) rules are called inclusion rules.

Typically, a rule must match any part of a file path (below the root, of course). However, if a rule starts with / or ./ it is called anchored and must match beginning of a file path. For example, rule ./README matches file README in the root directory, but not in any of its subdirectories.

If a rule matches a directory, it also matches all of the files the directory contains (with arbitrary nesting level). For example, rule test also matches file test/foo/bar.el.

A rule that ends in a slash directly matches only directories. But, in accordance to the previous paragraph, also all files within such directories. So, there is a subtle difference: a rule test/ won’t match a file named test, but will match any file within a directory named test.

Finally, note a difference with Git concerning inclusions/exclusions and subdirectories. Git manual says: “It is not possible to re-include a file if a parent directory of that file is excluded.” Eldev filesets have no such exceptions.

Eldev also supports composite filesets. They are built using common set/logic operations and can be nested, i.e. one composite fileset can include another. There are currently three types:

Finally, some parts of filesets — but not elements of simple filesets! — can be evaluated. An evaluated element can be a variable name (a symbol) or a form. When matching, such element will be evaluated once, before eldev-find-files or eldev-filter-files start actual work.

Result of evaluating such an expression can be an evaluated fileset in turn — Eldev will keep evaluating elements until results finally consist of only simple and composite filesets. To prevent accidental infinite loops, there is a limit of eldev-fileset-max-iterations on how many times sequential evaluations can yield symbols or forms.

Example of an evaluated fileset can be seen from return value of eldev-standard-fileset function. E.g.:

As the result contains references to two variables, they will be evaluated in turn — and so on, until everything is resolved.

Eldev contains quite a few variables with filesets that may be modified by the projects, for example, eldev-test-fileset, eldev-standard-excludes or eldev-files-to-package. To modify those, you should create a composite fileset that refers to the previous value. For example like this:

Previously Eldev documentation and its own source code would use append or push to modify existing filesets. This turned out to be a bad advice, because this implicitly assumes that the modified filesets are simple and might lead to unexpected results (stacktraces or filesets that don’t do what is expected) for any other fileset type.

Starting with version 1.2 Eldev will print a warning whenever it detects a “suspicious” modification in any of its standard filesets, to avoid potential bugs: eldev-files-to-package is no longer a simple filesets starting with that version, some others may be changed in the future too. If your project triggers this warning, please modify the erroneous code (in file Eldev or Eldev-local) to be similar to the example above. If you still get warnings, but are certain that all fileset-modifying code is correct, you can set variable eldev-warn-about-suspicious-fileset-var-modifications to nil in file Eldev.

Eldev defines several hooks executed at different times (more might be added later). Due to historical reasons, Eldev doesn’t follow Emacs naming convention on using -hook only for standard hooks (i.e. those not accepting any arguments) and -functions in other cases. Functions for many of the hooks listed below do receive arguments.

Eldev build system provides standard builders that cover all basic needs of Elisp packages. However, some projects have uncommon build steps. Instead of writing custom shell scripts, you can integrate them into the overall build process — which also simplifies further development.

An example of a project with additional build steps is Eldev itself. Its executable(s) are combined from executable template that is OS-specific and a common Elisp bootstrapping script. For example, bin/eldev is generated from files bin/eldev.in and bin/bootstrap.el.part. However, only the first file counts as the source; see how function eldev-substitute works.

There is a simple builder for this in file Eldev of the project:

Here eldev-defbuilder is a macro much like defun. It defines an Elisp function named eldev-builder-preprocess-.in and registers it with parameters (the keyword lines before the body) as an Eldev builder. Predictably, list (source target) specifies function arguments.

Let’s skip the keywords for a bit and have a look at the body. It works exactly like in a normal Elisp function. Its job is to generate target from source using builder-specific means. This particular builder calls function eldev-substite that does the actual work (this function is available also to your project, should you need it). But your builders could do whatever you want, including launching external processes (C/C++ compiler, a Python script, etc.) and using anything from Elisp repertoire. Note that return value of the body is ignored. If building the target fails, builder should signal an error.

Now back to the keyword parameters. As you can see, they all have a name and exactly one value after it. First comes parameter :short-name. It specifies what you see in the target tree of the project, i.e. builder’s name for the user. It is not required; without it Eldev would have used preprocess-.in as user-visible name.

Next parameter is :message. It determines what Eldev prints when the builder is actually invoked. For example, when byte-compiling, you’d see messages like this:

That’s because byte-compiling builder has its :message set to source (the default). Other valid values are target and source-and-target (as in the example). Both source and target can be pluralized (i.e. sources-and-target is also a valid value), but singular/plural is not important in this case as both work identically. Finally, value of :message can be a function, in which case it is called with the same arguments as the builder itself and should return a string.

Value of :source-files parameter must be a fileset. In the above example, fileset consists of only one simple rule — which is actually enough in most cases, — but it could also be much more complicated. All files that match the fileset and do not match eldev-standard-excludes will be processed using this builder.

Parameter :targets defines the rule used to construct target names out of sources matched by :source-files. There are several ways to define this rule, we’ll consider them in their own subsection.

Keyword :collect determines how targets generated by this builder are “collected” into virtual targets. In the example all such targets are simply added to the virtual target :default. However, here too we have several other possibilities, which will be described later.

Finally, keyword :define-cleaner provides a simple way of linking builders with the cleaning system.

Another important keyword is :type. It is not used here only because the example builder is of the default and most common type that generates one target for each source file. All possible types are: one-to-one (the default), one-to-many (several targets from one source file), many-to-one and many-to-many. If you write a builder of a non-default type, be aware that it will be called with a list of strings instead of a single string as one or both of its arguments, as appropriate. You should probably also name them in plural in the definition in this case, to avoid confusion.

Eldev has lots of standard commands, but sometimes you need to define yet more. Commands should generally be defined for things that cannot be reformulated in terms of building targets. If a command would just create a file, e.g. extract documentation from source code, an additional builder would be more suitable.

Defining a command is not much more complicated than defining a normal Elisp function:

Macro eldev-defcommand works much like defun, but additionally it adds the new function to the list of Eldev command handlers. New command receives name built from the function name by removing package prefix. If that doesn’t produce the needed result in your case (e.g. if package prefix is two words in your project), you can always specify name explicitly by using :command parameter. You can also give your command any number of aliases, as shown above.

Keyword :parameter describes what the command expects to see on the command line. It is used when invoking eldev help COMMAND to improve documentation: all commands are automatically documented. The short one-liner for eldev help is derived from the function’s documentation by taking the first sentence. If this is not good enough in your case, use keyword :briefdoc to set it explicitly.

When command is invoked from command line, Eldev calls the corresponding function, passing all remaining parameters to it as strings. The example command above just parrots the parameters back at user, in accordance to its name.

FIXME