dinghy

Dinghy is a collection of one-size-fits-all package files and tools for building Cask-based Emacs packages.

Installation

The idea ist to add this repo as a submodule.

git submodule add https://github.com/Walheimat/dinghy.git
git submodule update

If you add dinghy using a different name, make sure to set DINGHY_DIR in your Makefile accordingly.

Usage

Say you have such an Emacs package called my-package.el. You could now create a Makefile with the following contents.

PACKAGE_NAME=my-package

include dinghy/emacs-package.mk

This would give you access to the following goals:

• install
• package-install
• clean-install
• ci
• local
• test
• test-coverage
• test-tagged
• test-not-tagged
• test-selector
• cask-clean
• clean
• update-version
• pacify
• upgrade-bydi
• commits
• clean-commits

The default goal install will depend on ci if CI env is set (by GitHub Actions for example) otherwise on local.

Goal clean-install runs clean then install.

The ci goal by default will make sure .cask exists. If you have additional dependencies. You can set CI_DEPS.

The local goal by default depends on DIST_DIR which itself defaults to the dist directory created by cask. You can set LOCAL_DEPS and LOCAL_PHONY_DEPS yourself if you need additional targets. Note that LOCAL_DEPS get deleted as part of the clean goal.

The package-install goal will use package-install-file on the cask package result. If you have a multi-file package, you will need to set PACKAGE_SUFFIX to tar (it defaults to el).

The test goal by default calls ert-run-tests-batch-and-exit using cask. The goals test-{tagged,not-tagged,selector} use environment variables TEST_TAG and TEST_SELECTOR_STRING to set a selector for ert.

If you want to run something before the tests you can set TEST_EXECUTE_BEFORE.

You can alternatively set TEST_USE_ERT_RUNNER to use run cask exec ert-runner, meaning you need to add that to your Cask dependencies.

(development
 ;; Your other dependencies
 (depends-on "ert-runner"))

The ert-runner execution can be controlled using TEST_ARGS.

Goal clean runs cask clean-elc and removes local dependencies (LOCAL_DEPS).

You can also use script src/update-version.sh using goal update-version. This requires setting CURRENT_PACKAGE_VERSION. You can set the files to update using UPDATE_VERSION_FILES which defaults to updating the Cask and package file. This goal also updates the changelog file using UPDATE_VERSION_CHANGELOG_FILE (defaulting to CHANGELOG.md) and UPDATE_VERSION_CHANGELOG_HEADING (defaulting to Unreleased).

PACKAGE_NAME=my-package
CURRENT_PACKAGE_VERSION=1.3.1

UPDATE_VERSION_DEPS=Cask $(PACKAGE_NAME).el other-file.el

include dinghy/emacs-package.mk

Please also have a look at my various Emacs packages for usage examples.

You can also check your package files with flymake using goal pacify. It will use elisp-flymake-byte-compile and elisp-flymake-checkdock. Set PACIFY_DEPS if you need them. You can also set PACIFY_PRE_EXEC for setups.

For example, you could set dinghy-pacify-not-testable to a regular expression to ignore files matching the pattern.

PACIFY_DEPS=dist
PACIFY_PRE_EXEC=--eval "(setq dinghy-pacify-not-testable \"ignore\\\|untestable\")"

include dinghy/emacs-package.mk

Goal upgrade-bydi force-updates Cask dependency bydi (a library of mocking macros).

You can also setup commit linting using npm packages husky and commitlint by executing commits. It will set up a config using conventional commits, add a pre-commit hook to lint the commit message and install this hook.

You can use dinghy-rope to setup paths for your test as well as packages like ert-runner and undercover.

The main recipe is the following:

(require 'dinghy-rope)

(dinghy-rope-setup-paths)
;; or
(dinghy-rope-setup-paths '("relative/one" "relative/two"))

(dinghy-rope-setup-undercover (list "my-package.el"))
;; or
(dinghy-rope-setup-undercover  (list "src/*.el" "root.el"))

(dinghy-rope-setup-ert-runner)
;; or
(defun my-reporter (&rest _)
  "Notify."
  (message "We are done here"))
(dinghy-rope-setup-ert-runner #'my-reporter)

(dinghy-rope-setup-ert :increase-print-depth t)

There’s also convenience command dinghy-rope-find-test-helper to find the helper file ert-runner uses.

Please have a look at my Emacs configuration for real-world usage examples that set up ert-runner and undercover (the same is done here but since we test dinghy itself, it’s not using its setup functions).