Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/emacs-eldev/eldev

Elisp development tool
https://github.com/emacs-eldev/eldev

build-tool continuous-integration developer-tools emacs-lisp

Last synced: about 1 month ago
JSON representation

Elisp development tool

Awesome Lists containing this project

README 

        
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 specify which

  Elisp package archive(s) to use.

* You can also use {uri-documentation}#local-dependencies[local

  dependencies], even those that don’t use Eldev (some restrictions

  still apply).  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.