flymake-collection

flymake-collection tries to provide a comprehensive list of diagnostic-functions for use with flymake, give users the tools to easily define new syntax checkers and help selectively enable or disable diagnostic-functions based on major-modes.

The goal of this project is to make the transition from flycheck to flymake as easy as possible, and to act as a catching ground for all the checkers that don’t already have a flymake backend available.

Table of Contents

• Installation
  • Manually
  • From MELPA
  • Configurations
• Contributing
• Related Packages
  • flymake-flycheck
  • flymake-quickdef
  • flymake-proselint, flymake-shellcheck, etc.
• Appendix

Installation

Manually

1. Clone the repo
2. Add the cloned repo path and the checkers sub-directory to the load path.
3. Configure the package to your liking.

From MELPA

This package is on MELPA. You can add this to your package-archives variable and then install through M-x package-install.

(push '("melpa" . "https://melpa.org/packages/") package-archives)
(package-refresh-contents)
(package-install 'flymake-collection)

Configurations

Enabling Diagnostic Functions

This package comes with several diagnostic-functions out of the box, these can be used by simply hooking them into flymake-diagnostic-functions for whatever buffer you’ve enabled flymake in.

For example

(add-hook 'python-mode-hook
          (defun python-mode-setup-flymake ()
            (add-hook 'flymake-diagnostic-functions 'flymake-collection-pycodestyle nil t)
            (flymake-mode +1)))

For a list of supported syntax-checkers see ./src/checkers/. All of the defined checkers are auto-loaded and have no other dependencies than flymake-collection so once you’ve installed and compiled flymake-collection you can hook them into flymake-diagnostic-functions without any extra configuration or loading being needed.

Associating Checkers with Major Modes

flymake-collection provides a special configuration variable to let you associate diagnostic functions with major-modes. This can be useful both for automatically enabling diagnostic functions and for interactively toggling them based on your configuration.

The flymake-collection-config config variable is an alist with the key being the major-mode and the cdr being the list of diagnostic functions for that mode. Each diagnostic function can be defined as the function symbol, or an alist with the car of the symbol being the function symbol and the cdr being a plist of options for that function. Currently the supported options include :depth for the DEPTH property passed to add-hook, a predicate function which is called to determine whether to enable this diagnostic-function and a boolean field :disabled to indicate whether or not this checker shouldn’t be added to flymake-diagnostic-functions.

Here is an example configuration for python-mode:

(push
 '(python-mode
   flymake-collection-mypy                      ; Always added to diagnostic functions.
   (flymake-collection-pycodestyle :disabled t) ; Never added.
   (flymake-collection-pylint                   ; Added when predicate is true.
    :predicate (lambda ()
                 (executable-find "pylint"))))
 flymake-collection-config)

Note: The executable-find predicate example here is redundant, each checker will already make sure any dependent executables are installed before being run.

Lastly there’s also a use-package keyword you can use to define config entries. This is just syntax sugar over pushing these values into flymake-collection-config as shown above.

(use-package python-mode
  :flymake-hook
  (python-mode
   flymake-collection-mypy                      ; Always added to diagnostic functions.
   (flymake-collection-pycodestyle :disabled t) ; Never added.
   (flymake-collection-pylint                   ; Added when predicate is true.
    :predicate (lambda ()
                 (executable-find "pylint"))))))

Automatically Enabling Syntax Checkers

To automatically enable diagnostic functions based on flymake-collection-config you have to call the flymake-collection-hook-setup function. This can be done through use-package, for example:

(use-package flymake-collection
  :hook (after-init . flymake-collection-hook-setup))

You can also interactively enable or disable a diagnostic-function from flymake-collection-config using the flymake-collection-change-checker command.

Contributing

Please do!. There are more checkers out there than I have the time to explore, if you’d like to add support for a new checker or contribute improvements to an existing one, we’d be more than happy to accept.

Tests can be found in tests/checkers/. The installers directory is where bash scripts are setup to install the checker on ubuntu:20.04. Actual test-cases are declarative YAML configurations that run a given checker function on a given file with the latest version of flymake and your local flymake-collection repository and then examines the results. See pylint.yml for an example. Please supply installer and test-cases for any contributed checkers as well.

To run locally you can use the supplied Makefile with make lint compiling all your local elisp files and make test running the test-cases within docker. If you do not have docker setup the CI/CD pipeline on this repo will automatically lint and test when you open a PR.

Related Packages

flymake-flycheck

Provides a bridge between flymake and flycheck. It allows you to use all of the checker functions already exposed through flycheck with flymake. This would be useful if you’re intent on using both flycheck and flymake or need to use flymake but require a checker that’s only available with flycheck.

flymake-collection doesn’t bridge flycheck and flymake, it re-implements several flycheck checkers as flymake compatible ones. It also provides helpers to allow defining checkers as easily as flycheck does (for example flymake-collection provides a parallel to the convenient :error-patterns option of flycheck-define-checker). In the end flymake-collection has no dependency on flycheck where as flymake-flycheck does.

flymake-quickdef

This was the initial package I adapted into flymake-collection-define because I needed extra functionality for pylint. It provides a helper macro to define backend functions for various checkers. If you prefer a more fine grained configuration or just need a standalone checker for your own use-cases it may be easier to define one using this instead of installing flymake-collection.

Note: All the features of flymake-quickdef (as of version 1.0.0) is also supported by flymake-collection. We also support some extra features such as linting a file in the same directory as an existing file.

flymake-proselint, flymake-shellcheck, etc.

These packages provide standalone backend functions for specific checkers. This lets you have a more modular, what-you-need is what-you-install setup where you only install flymake backends for the checkers you actually intend to use. If you believe flymake-collection to be too large for your liking I’d recommend deferring to one of these existing packages.

flymake-collection exists because I didn’t want to have to setup and configure all of these different backends for all the languages I use. If you’d prefer to install one package and have linting work across a collection of different languages and possible checkers then flymake-collection may be more what you’re looking for.

Appendix