$ eldev help

$ eldev help COMMAND

$ eldev init

Now that we have created file Eldev, it makes sense to go over the full startup process:

• Load file ~/.eldev/config

• Load file Eldev in the current directory

• Load file Eldev-local in the current directory

• Execute setup forms specified on the command line

None of these Elisp files and forms are required. They are also not restricted in what they do. However, their intended usage is different.

File ~/.eldev/config is user-specific. It is meant mostly for customizing Eldev to your personal preferences. For example, if you hate coloring of Eldev output, add form (setf eldev-coloring-mode nil) to it. Then every Eldev process started for any project will default to using uncolored output.

File Eldev is project-specific. It is the only configuration file that should be added to project’s VCS (Git, Mercurial, etc.). Typical usage of this file is to define in which package archives to look up dependencies. It is also the place to define project-specific builders and commands, for example to build project documentation from source.

File Eldev-local is working directory or user/project-specific. Unlike Eldev, it should not be added to VCS: it is meant to be created by each developer (should he want to do so) to customize how Eldev behaves in this specific directory. The most common use is to define local dependencies. A good practice is to instruct your VSC to ignore this file, e.g. list it in .gitignore for Git.

Finally, it is possible to specify some (short) setup forms on the command line using --setup (-S) option. This is not supposed to be used often, mostly in cases where you run Eldev on a use-once project checkout, e.g. on a continuous integration server.

(eldev-use-package-archive 'melpa-stable)

(eldev-use-package-archive '("myarchive" . "http://my.archive.com/packages/"))

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:

$ eldev -p test

(setf eldev-project-loading-mode 'byte-compiled)

(eldev-use-local-dependency "~/barlib" 'packaged)

$ eldev --list-modes

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:

:default, :package, :compile etc.

Virtual targets. The ones you see above are typical, but there could be more.

bin/eldev, dist/eldev-0.1.tar, eldev-ert.elc etc.

Real targets.

SUBST, PACK, ELC

Builders used to generate target. Note that virtual targets never have builders. SUBST is not a standard builder, it is defined in file Eldev of the project.

bin/eldev.in, eldev-ert.el etc.

Sources for generating targets. Certain targets have more than one source file. Also note how targets can have other targets as their sources (bin/eldev is both a target on its own and a source for dist/eldev-0.1.tar).

[repeated ...]

To avoid exponential increase in tree size, Eldev doesn’t repeat target subtrees. Instead, only root target of a subtree is printed.

Target cross-dependencies

Target sets

$ eldev targets test

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.

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.

Byte-compiling complicated macros

$ eldev compile -l

(setf eldev-build-load-before-byte-compiling t)

Speed of byte-compilation

$ eldev -v compile
[...]
ELC      foo-misc.el
Byte-compiling file ‘foo-misc.el’...
ELC      foo-util.el
Byte-compiling file ‘foo-util.el’ early as ‘require’d from another file...
Done building “sources” for virtual target ‘:compile’

FIXME

$ eldev test

$ eldev test foo-test-15

$ eldev test -f foo.el

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.

When variable eldev-test-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.

• Any selector that ends in .el is instead treated as a file pattern. For example:

  $ eldev test foo.el

  will work as if you specified -f before foo.el.

• For ERT: any symbol selector that doesn’t match a test name is instead treated as regular expression (i.e. as a string). For example:

  $ eldev test foo

  will run all tests with names that contain foo. You can achieve the same result with ‘strict’ command line (see also ERT selector documentation) like this:

  $ eldev test \"foo\"

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

$ eldev eval "(+ 1 2)"

$ eldev eval "(my-package-function)"

$ eldev emacs

$ eldev emacs foo.bar

$ eldev emacs -- -q foo.bar

$ EMACS=emacs25 eldev eval emacs-version

The largest problem on Travis CI is to install Emacs binary of the desired version. Luckily, there is a tool that can be used for this called EVM. For convenience, Eldev provides a simple script specifically for use on Travis CI that installs Eldev and EVM in one go.

Here is a simple project-agnostic .travis.yml file that you can use as a basis:

If you want to additionally test that your project byte-compiles cleanly, add another line to script section:

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):

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:

(:and ELEMENT...)

A file matches an :and fileset if and only if it matches every of its ELEMENT filesets.

(:or ELEMENT...)

A file matches an :or fileset if and only if it matches at least one of its ELEMENT filesets.

(:not NEGATED)

A file matches a :not fileset when it doesn’t match its NEGATED fileset and vice versa.

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 defines a few hooks (more might be added later).

eldev-executing-command-hook

Run before executing any command. Command name (as a symbol) is passed to the hook’s functions as the only argument. This is always the “canonical” command name, even if it is run using an alias.

eldev-COMMAND-hook

Run before executing specific command, functions have no arguments. Eldev itself uses it (i.e. in its file Eldev) to print a disclaimer about its fairly slow tests.

eldev-build-system-hook::

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.

Target rules

:targets        (".el" -> ".elc")

Collecting into virtual targets

:gen-files
    :gen-sources
        :gen-el
            foo.el.in
            bar.el.in

Summary

FIXME

FIXME