A makefile to facilitate checking Emacs packages
You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
Damien Cassou 87b5b63908 Merge branch '0.5.3' of DamienCassou/makel into master 3 weeks ago
test Only run buttercup tests if TEST_BUTTERCUP_OPTIONS is non empty 3 weeks ago
.drone.yml Add gnu package archive for let-alist 3 weeks ago
.gitignore Ignore a file required by package-lint 3 weeks ago
README.org Release 0.5.3 3 weeks ago
makel.mk Release 0.5.3 3 weeks ago

README.org

makel

Summary

makel is a project consisting of a Makefile (makel.mk) that Emacs package authors can use to facilitate quality checking (linting and tests). The Makefile can be used both locally on the developer machine and remotely on a continuous integration machine. These are the rules provided by ~makel.mk~:

test-ert
run your ERT (the Emacs Lisp Regression Testing tool)
tests.
test-buttercup
run your buttercup tests.
lint-checkdoc
collect and report checkdoc (the Emacs coding
convention tool) errors.
lint-package-lint
collect and report package-lint (a linting
library for package definitions) errors.
lint-compile
collect and report errors and warnings from the
Emacs Lisp compiler.
lint
starts all linting-related rules.
test
starts all test-related rules (both ert and buttercup tests).
check
starts all lint and test rules.
makel-version
displays makel's version

What distinguishes makel from similar tools (see below) is its simplicity: simplicity to use it in your Emacs package (there are just a handful of variables to define) and simplicity to understand what it does (it's just a Makefile).

Installation

Alongside your package, create a Makefile file containing the following code:


  makel.mk:
          # Download makel
          @if [ -f ../makel/makel.mk ]; then \
                  ln -s ../makel/makel.mk .; \
          else \
                  curl \
                  --fail --silent --show-error --insecure --location \
                  --retry 9 --retry-delay 9 \
                  -O https://gitlab.petton.fr/DamienCassou/makel/raw/v0.5.3/makel.mk; \
          fi

  # Include makel.mk if present
  -include makel.mk

The lines above indicate that you want to use makel.mk if present in the current directory. If not, you want to use the one from a sibling directory (../makel/makel.mk) or from Internet.

You decide which version of makel you want to use by changing the URL (here v0.5.3 is the latest version).

Usage

You have to tell makel which files you want each rule to look at. This is a bit verbose but easy to understand (and easy to copy/paste :-)). This can be done by setting a few variables at the beginning of your Makefile:


  # Space-separated list of the dependencies of your project (include
  # package-lint and/or buttercup if you want makel to use these tools):
  ELPA_DEPENDENCIES=package-lint

  # List of package archives to download above dependencies
  # from. Available archives are: gnu, melpa, melpa-stable and org:
  ELPA_ARCHIVES=melpa

  # List of ERT test files:
  TEST_ERT_FILES=$(wildcard test/*.el)

  # List of buttercup test directories:
  TEST_BUTTERCUP_OPTIONS=specs

  # List of files to check for Emacs conventions:
  LINT_CHECKDOC_FILES=$(wildcard *.el) ${TEST_ERT_FILES}

  # List of files to check for packaging guidelines:
  LINT_PACKAGE_LINT_FILES=$(wildcard *.el)

  # List of files to check for compilation errors and warnings:
  LINT_COMPILE_FILES=${LINT_CHECKDOC_FILES}

The variable ELPA_DEPENDENCIES list Emacs packages that you want makel to download if not already present. This is especially useful on a continuous integration environment where no external package is usually installed. If some of the dependencies you need are not available on a package archive (or not in a recent-enough version), you can add URLs to DOWNLOAD_DEPENDENCIES and they will be downloaded to the project's main directory.

Above code uses the wildcard Make function to list Emacs Lisp files in the current directory as well as the test/ sub-directory. makel makes sure to remove any *-autoloads.el file from such a list before doing anything.

Running the rules

Now that you have configured makel, you just need to use it. A design choice I made is that makel should only print important information: this is to avoid making you spend time searching for potential problems in a log that doesn't contain any. If everything is fine, makel will only print the tasks it runs:


$ make check
# Run ert tests from test/libmpdel-test.el…
# Run checkdoc on libmpdel.el, test/libmpdel-test.el…
# Run package-lint on libmpdel.el…
# Run byte compilation on libmpdel.el, test/libmpdel-test.el…

makel is only noisy if there actually is a problem to report:


$ make check
# Run ert tests from test/libmpdel-test.el…
Loading /home/cassou/.emacs.d/lib/libmpdel/test/libmpdel-test.el (source)...
Running 29 tests (2018-10-03 20:49:23+0200)
   passed   1/29  libmpdel-test--message-filter-activates-saved-buffer
   passed   2/29  libmpdel-test--message-filter-keeps-current-buffer-if-saved-one-died
   passed   3/29  libmpdel-test--msghandler-status-updates-volume
   passed   4/29  libmpdel-test--raw-send-command-with-handler-add-ignore-handler
   […]
Test libmpdel-test-artist-name condition:
    (ert-test-failed
     ((should
       (equal "The Artist"
	      (libmpdel-artist-name artist)))
      :form
      (equal "The Artist" "The Artists")
      :value nil :explanation
      (arrays-of-different-length 10 11 "The Artist" "The Artists" first-mismatch-at 10)))
   FAILED  12/29  libmpdel-test-artist-name
   passed  13/29  libmpdel-test-create-song-from-data
   passed  14/29  libmpdel-test-current-playlist-p

Ran 29 tests, 28 results as expected, 1 unexpected (2018-10-03 20:49:23+0200)

1 unexpected results:
   FAILED  libmpdel-test-artist-name

make: *** [makel.mk:55: test-ert] Error 1

Emacs packages using makel

The following Emacs packages (all from me :-)) are already using makel and could act as examples:

*Package name* *Description*
libmpdel Library to communicate with Music Player Daemon (MPD), server-side application for playing music
mpdel User interface for Music Player Daemon (MPD), server-side application for playing music
libelcouch Library to communicate with CouchDB databases
elcouch User interface to view and manipulate CouchDB databases
khardel User interface to integrate khard, a console cardav client

Alternatives

If you are looking for something similar to makel, you might be interested in these projects:

I designed and implemented makel after having used both Cask and EMake for some time. My opinion is that makel is simpler to use and maintain (it's only a Makefile and it has many unit tests) but may lack some features you might need.

Regarding Cask, I was frustrated by the complexity (I mean understanding how things work and play together) and warnings/errors I and others would regularly get.

Regarding EMake, I opened a few PRs and issues to make it do what I need but the maintainer and I disagreed on several core decisions. I made sure I agree with all decisions I took for makel :-).

License

See COPYING. Copyright (c) 2018-2019 Damien Cassou.

#+BEGIN_HTML Donate using Liberapay #+END_HTML