README.adoc

ifndef::env-github[:icons: font] ifdef::env-github[] :warning-caption: :warning: :caution-caption: :fire: :important-caption: :exclamation: :note-caption: :paperclip: :tip-caption: :bulb: endif::[] :empty: :uri-documentation: https://emacs-eldev.github.io/eldev/ :uri-xdg: https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html :uri-flycheck: https://www.flycheck.org/ :uri-flycheck-eldev: https://github.com/flycheck/flycheck-eldev :uri-flymake: https://www.gnu.org/software/emacs/manual/html_node/emacs/Flymake.html :uri-flymake-eldev: https://github.com/emacs-eldev/flymake-eldev

// Some text duplication with the full documentation is expected here.

= Eldev

image:https://img.shields.io/badge/license-GPL_3-green.svg[License: GPL 3, link=http://www.gnu.org/licenses/gpl-3.0.txt] image:https://img.shields.io/github/release/emacs-eldev/eldev.svg[Latest release, link=https://github.com/emacs-eldev/eldev/releases] image:http://stable.melpa.org/packages/eldev-badge.svg[MELPA Stable, link=http://stable.melpa.org/#/eldev] image:https://github.com/emacs-eldev/eldev/workflows/CI/badge.svg[CI, link=https://github.com/emacs-eldev/eldev/actions?query=workflow%3ACI]

Eldev (Elisp development tool) is an Emacs-based build tool, targeted solely at Elisp projects. It is an alternative to Cask. Unlike Cask, Eldev itself is fully written in Elisp and its configuration files are also Elisp programs. If you are familiar with Java world, Cask can be seen as a parallel to Maven — it uses project description, while Eldev is sort of a parallel to Gradle — its configuration is a program on its own.

== Documentation

NOTE: Detailed documentation on Eldev features is {uri-documentation}[available online]. This page intentionally provides only a brief overview.

== Eldev features

• Eldev configuration is Elisp. It can change many defaults, add special cases for Emacs versions and much more — even define additional Eldev commands and options.
• Built-in {uri-documentation}#testing[support for regression/unit testing].
• Blends nicely into {uri-documentation}#continuous-integration[continuous integration] setups.
• Can run on {uri-documentation}#different-emacs-versions[different Emacs version] even on the same machine; can also use {uri-documentation}#docker[Docker] or {uri-documentation}#podman[Podman] for that.
• There are {uri-documentation}#setup-procedure[four levels of configuration] — you can customize most aspects of Eldev for your project needs and personal preferences.
• {uri-documentation}#dependencies[Project dependency] downloading, installation etc. is fully automated, you only need to tell the tool where to find them: ** {uri-documentation}#package-archives[in package archives] (MELPA, GNU ELPA, etc.); ** {uri-documentation}#vc-repositories[in VC (Git) repositories]; ** {uri-documentation}#local-sources[in a local directory on your machine] (this is similar to Cask linking, but with more flexibility).
• Full support for {uri-documentation}#autoloads[autoloads] during development.
• Miscellaneous operations useful during development: {uri-documentation}#running-emacs[running Emacs] with only your project, {uri-documentation}#linting[linting] source code, {uri-documentation}#evaluating[evaluating expressions] in project’s context, {uri-documentation}#profiling[profiling].
• Can {uri-documentation}#maintainer-plugin[automate release process] for your project.
• Eldev by default {uri-documentation}#project-isolation[isolates] your project for development, helping you to distinguish between problems with setup or configuration and inherent bugs in the project.
• Full-featured {uri-documentation}#build-system[build system] for complex projects.
• Can {uri-documentation}#debugging-features[help you debug your code].
• {uri-documentation}#requirements[Runs on all major operating systems]: Linux, macOS, Windows.
• Eldev is fast.

Eldev source code itself comes with no examples, but there is a short {uri-documentation}#example-projects[list of real-world projects] in the documentation.

TIP: If you are using {uri-flycheck}[Flycheck] or {uri-flymake}[Flymake], check out {uri-flycheck-eldev}[flycheck-eldev] or, correspondingly, {uri-flymake-eldev}[flymake-eldev] package. They provide integration between Flycheck/Flymake and Eldev, allowing the former to automatically use proper dependencies in Eldev projects.

== Installation

The easiest and most common way to install Eldev on Linux, macOS, etc. is this shell oneliner:

$ curl -fsSL https://raw.github.com/emacs-eldev/eldev/master/webinstall/eldev | sh

This will install eldev script to ~/.local/bin. Usually, {uri-xdg}[this directory should already be in your PATH]. But if not, e.g. in ~/.profile add this:

export PATH="$HOME/.local/bin:$PATH"

Documentation {uri-documentation}#installation[lists several other ways to install Eldev], including on Windows. They are not more difficult than the one above.

== Safety concerns

TIP: In general, it is not recommended to execute Eldev, GNU Make, Scons, any other build tool or anything based on one in a directory that contains untrusted code.

Like many (if not most) other development tools, Eldev is unsafe when executed on untrusted code. For example, simply running eldev in a project you have just downloaded from hackerden.org can result in anything, including emptied home directory. For that matter, running make or gradle is not better in this regard. Eldev is perhaps a bit more dangerous, because even eldev help reads file Eldev, thus executing arbitrary code.

Even seemingly harmless things, like opening a .el file in Emacs can lead to unforeseen consequences. If you e.g. have {uri-flycheck}[Flycheck] or {uri-flymake}[Flymake] enabled everywhere, this will result in byte-compiling said file, which also can execute arbitrary code, for example using (eval-when-compile ...) form. The same holds for installing (not even using!) Elisp packages.

Only use build tools on code that you trust. Better yet, don’t even touch code that you don’t plan running.

== Getting started

Eldev comes with built-in help. Just run:

$ eldev help

This will list all the commands Eldev supports. To see detailed description of any of those, type:

$ eldev help COMMAND

In the help you can also see lots of options — both global and specific to certain commands. Many common things are possible just out of the box, but {uri-documentation}#extending-eldev[later we will discuss] how to define additional commands and options or change defaults for the existing.

Two most important global options to remember are --trace (-t) and --debug (-d). With the first one, Eldev prints lots of additional information about what it is doing to stdout. With the second, Eldev prints stacktraces for most errors. These options will often help you figure out what’s going wrong without requesting any external assistance. Also check out section on {uri-documentation}#debugging-features[various debugging features] discussed later.

Eldev mostly follows GNU conventions in its command line. Perhaps the only exception is that global options must be specified before command name and command-specific options — after it.

== Documentation

NOTE: Detailed documentation on Eldev features is {uri-documentation}[available online]. This page intentionally provides only a brief overview.