Flycheck practices

Table of Contents

Flycheck is a modern on-the-fly syntax checking extension for GNU Emacs 24, intended as replacement for the older Flymake extension which is part of GNU Emacs.

Flycheck是GNUE macs24的动态语法检查扩展,目的是取代GNU Emacs中旧的Flymake扩展。

It uses various syntax checking and linting tools to check the contents of buffers, and reports warnings and errors directly in the buffer or in an optional error list (see Flycheck manual for more information):

通过各种语法检查和lint工具检查buffer内容,直接在buffer或可选的错误列表中报告警告和错误。

Out of the box Flycheck supports over 40 different programming languages with more than 80 different syntax checking tools, and comes with a simple interface to define new syntax checkers.

开箱即用的Flycheck支持超过40中不同的编程语言和超过80种不同的语法检查工具,并带有一个简单的接口可以定义新的语法检查器。

Many 3rd party extensions provide new syntax checkers and other features like alternative error displays or mode line indicators.

许多第三方扩展提供新的语法检查和其他功能,比如替代的错误显示和模式行指示符。

1 Introduction

Flycheck provides modern on-the-fly syntax checking extension for GNU Emacs 24, intended as replacement for the older Flymake extension which is part of GNU Emacs.

Flycheck为GNU Emacs 24提供现代的动态语法检查,目的是取代GNU Emacs中的Flymake扩展。

Flycheck runs various linting tools and services to automatically check the contents of buffers while you are typing, and reports warnings and errors directly in the buffer, in the mode line and in an optional error list. You can navigate errors and warnings in the current buffer, show the corresponding messages, and copy errors to the kill ring.

Flycheck运行各种linting工具和服务自动检查输入到buffer中的内容,在buffer、模式行或可选的error列表中报告错误。可以在当前buffer中浏览错误和警告,显示相应的信息,拷贝错误到kill ring中。

  • Over 40 languages with more than 70 checkers. See Supported languages.

    超过40种语言和70款检查器。

  • Fully automatic, fail-safe, on-the-fly syntax checking in buffers

    全自动、防故障、动态检查buffer。

  • In-buffer error highlighting, with fringe indicators

    buffer中使用边缘标识高亮错误

  • Error navigation

    浏览错误

  • Auto-updating error list

    自动更新错误列表

  • Many customisation options

    许多定制选项。

  • A comprehensive manual

    全面的手册。

  • A simple API to add support for new languages and tools

    使用简单的API就可以添加新语言和工具。

  • A “doesn’t get in your way guarantee”

    不以你的方式得到保证。(啥意思)

2 Installation

2.1 Prerequisites

Flycheck needs GNU Emacs 24. Older releases of GNU Emacs or other flavours of Emacs (e.g. XEmacs, Aquamacs, etc.) are not supported.

Flycheck需要GNU Emacs24。旧版GNU Emacs和其他种类的Emacs不受支持。

Flycheck works best on Unix-like operating systems. It is extensively tested on Linux and OS X.

Flycheck在类Unix操作系统中工作良好。在Linux和OS X上经过广泛测试。

Flycheck does not explicitly support Windows, but tries to maintain Windows compatibility and should generally work fine on Windows, too. However, we can neither answer questions about Windows nor fix bugs that only occur on Windows without the help of active Windows users. Please watch out for known Windows issues!

Flycheck没有明确支持windows,但试图维护windows兼容性,在windows行也应该运行良好。不过,没有活跃的windows用户的帮助,我们也不能回答关于windows的问题,或修复发生在windows上的错误。

2.2 Syntax checking tools

Flycheck does not check buffers itself. It relies on external programs to check buffers, which need to be installed separately. See Supported languages, for a list of required programs for each language supported by Flycheck.

Flycheck并不自己检查buffer。它以来那些需要单独安装的外部工具检查buffer。

Most of these programs are available in the package repositories of Linux distributions, or with the standard package managers of specific programming languages (e.g. Rubygems, NPM, Cabal, etc.)

大部分这种程序都能在Linux发行版的包容器中找到,或者在特定语言的标准包管理器中。(比如Rubygems、NPM、Cacal等)。

2.3 Installation

Install Flycheck via Emacs’ built-in package manager, from the MELPA Stable repository:

通过Emacs自带的包管理器或MELPA标准容器安装Flycheck。

 M-x package-install RET flycheck

Alternatively, you may use the MELPA repository, which hosts the most recent development version. Note that these repositories are not included in GNU Emacs by default.

也可以使用MELPA容器,上次有最近的开发版本。注意GNU Emacs默认不包括这些容器。

You need to enable them explicitly, by adding the following to your init file:

可以通过在init文件中添加以下代码来显示启用他们:

(require 'package)
(add-to-list 'package-archives
			 '("melpa" . "http://melpa.org/packages/") t)
(package-initialize)

2.4 Cask

If you use Cask to manage your packages, add the following to your Cask file:

(source gnu)
(source melpa-stable)

(depends-on "flycheck")

3 Quickstart

3.1 Install and enable Flycheck

To get started with Flycheck, enable it by adding the following to your init file:

(add-hook 'after-init-hook #'global-flycheck-mode)

If you don’t know where your init file is take a look at the value of the variable user-init-file with C-h v user-init-file.

3.2 Install syntax checker tools

Next you need to install syntax checking tools for the major modes you are using. For instance, for Python you may want to install Pylint:

下一步需要安装正在使用的major mode对应的语法检查工具。

$ pip install pylint

For Ruby, you might want to use Rubocop and ruby-lint:

gem install rubocop ruby-lint

See Supported languages, for a complete list of all languages that Flycheck supports.

3.3 Check syntax in a buffer

Now switch to a Python or Ruby Mode buffer and run M-x flycheck-verify-setup to check whether Flycheck is correctly setup.

现在在Python或者Ruby模式buff中使用flycheck-verif-setup来检查是否正确设置了Flycheck。

If everything is fine Flycheck will now check syntax using these tools, when you visit a buffer in any of these languages. Syntax checking happens automatically when you save the buffer or make any changes. Flycheck highlights errors and warnings in the buffer, indicates them in the fringe, and reports their numbers in the mode line.

一切设置好之后,当访问这些语言的任何buffer时,Flycheck将会使用这些工具进行代码检查。当保存buffer或作出改变时会自动检查。Flycheck高亮buffer中的错误和警告,使用边缘标记指示它们,并在模式行显示它们的数字。

You can also manually check a buffer with C-c ! c (flycheck-buffer). 可以使用C-c ! c手动检查buffer。

3.4 Navigate and list errors

Use C-c ! n (flycheck-next-error) and C-c ! p (flycheck-previous-error) to navigate between error locations. If you keep the point at an error location, Flycheck will show the error message in the echo area after a short delay. You can also hover error locations with the mouse and see the error message in a tooltip.

使用C-c ! n (flycheck-next-error) and C-c ! p (flycheck-previous-error)在错误位置间进行导航。如果光标在error位置,短暂延迟后Flycheck会在回显区显示错误消息。也可以你使用鼠标悬位置,在tooltip中查看错误消息。

To get an overview of all errors and warnings in the current buffer, type C-c ! l (flycheck-list-errors) to pop up a list of all errors in your current buffer. The error list updates automatically when you fix errors or introduce new ones, or when you switch to another buffer.

为了得到当前buffer中所有错误和警告的概述,使用C-c ! l(flycheck-list-error)来弹出当前buffer中所有错误的列表。当修正错误、引入新错误、或切换到新的buff时列表会自动更新。

3.4.1 More features

All Flycheck commands are available in the Emacs menu at ‘Syntax checking’ in the ‘Tools’ menu.

所有Flycheck命令都在Emacs Tools菜单下“Syntax checking”菜单中。

4 Usage

This chapter explains the usage of Flycheck in-depth.

本章深入讲解Flycheck的用法。

Note: All commands in this chapter are documented with their default key prefix C-c !. You can customise this prefix with flycheck-keymap-prefix, but remember your custom prefix while reading this chapter.

注意:本章的所有命令都是。可以通过flycheck-keymap-prefix定制该前缀,但是阅读本章的时候请记得定制的前缀。

4.1 Checking buffers

The minor mode flycheck-mode enables syntax checking in a single buffer. global-flycheck-mode automatically enables flycheck-mode all buffers whenever possible. You can exclude specific major modes from global-flycheck-mode with flycheck-global-modes.

flycheck-mode辅助模式在单独的buffer中启用语法检查。globa-flycheck-mode自动在所有buffer中启用flycheck-mode。可用flycheck-global-modes从global-flycheck-mode中排除特定的主模式。

Note: global-flycheck-mode does not enable flycheck-mode for remote or encrypted files. The former is flaky and might be very slow, and the latter would leak confidential data to temporary directories. You may still check syntax in these buffers by manually enabling flycheck-mode with M-x flycheck-mode. However, this is not recommended for said reasons.

注意:global-flycheck-mode不会远程或加密文件启用flycheck-mode。前者可能是片段,并且非常慢。后者可能会泄露机密数据到临时目录。可以在这些目录中通过M-x flycheck-mode手动启用flycheck-mode。然而,正如刚才所说原因并不推荐这样做。

Add the following code to your init file to enable syntax checking permanently:

将下面的代码添加到init文件来永久启用语法检查:

(add-hook 'after-init-hook #'global-flycheck-mode)

When flycheck-mode is enabled, Flycheck automatically checks a buffer whenever 启动flycheck-mode后,下面这些情况,Flycheck会自动检查buffer:

  • the buffer is saved,
  • new lines are inserted,
  • or a short time after you stopped to make changes to the buffer.

You can customise this behaviour by changing flycheck-check-syntax-automatically:

可以通过改变flycheck-check-syntax-automatically定制这种行为:

User Option: flycheck-check-syntax-automatically

A list of events that trigger a new syntax check in the current buffer:

当前buffer中触发语法检查的事件列表:

  • save

    Check the buffer immediately after it was saved.

    保存buffer后立即检查。

  • idle-change

    Check the buffer a short time after the last change to the buffer. The delay is customisable with flycheck-idle-change-delay.

    buffer最后更改一段时间后检查。通过flycheck-idle-change-delay定制延迟时间。

  • new-line

    Check the buffer immediately after a new line was inserted.

    插入新行后立刻检查缓冲区。

  • mode-enabled

    Check the buffer immediately after Flycheck Mode was enabled.

    Flycheck mode启用后立即检查。

For instance, with the following code in your init file Flycheck will only check the buffer when it is saved, but never while you are making changes to the buffer:

例如,如果init文件中是下面的代码,只有在保存buffer的时候才会检查,更改buffer不会检查。

(setq flycheck-check-syntax-automatically '(mode-enabled save))

In addition to automatic syntax checking you can always check the current buffer manually:

除了自动语法检查,还可以手动检查当前buffer:

  • C-c ! c
  • M-x flycheck-buffer

    Check syntax in the current buffer.

Note: If syntax checking does not work, please check your setup:

注意:如果语法检查不工作,请检查设置:

  • C-c ! v
  • M-x flycheck-verify-setup

    Popup a buffer with information about the Flycheck setup for the current buffer.

    弹出显示当前buffer的Flycheck设置信息的buffer。

    Lists the syntax checkers available for the current buffer, together with potential problems in their setup.

    显示可用于当前buffer的语法检查器,以及它们设置中可能存在的问题。

During syntax checks Flycheck creates temporary files to feed to contents of the current buffer to external programs. You can change the prefix used for the names of these temporary files with flycheck-temp-prefix.

语法检查过程中Flycheck创建临时文件将当前buffer内容传递给外部程序。可通过flycheck-mtp-prefix改变这些临时文件名字的前缀。

4.2 Syntax checkers

Flycheck does not check buffers by itself, but relies on external syntax checkers. When checking a buffer Flycheck automatically selects the best syntax checker from flycheck-checkers:

Flycheck本身不会检查buffer,而是依赖外部的语法检查器。检查时Flycheck自动从flycheck-checkers中选择最好的语法检查器:

User Option: flycheck-checkers

A list of all syntax checkers available for syntax checking.

用于语法检查的所有语法检查器的列表:

A syntax checker in this list is a registered syntax checker.

Flycheck may apply further syntax checkers to the current buffer, if the selected syntax checker chains to other syntax checkers. For instance, the emacs-lisp syntax checker, which checks Emacs Lisp with Emacs’ byte compiler, chains to the emacs-lisp-checkdoc syntax checker, which checks Emacs Lisp for violations of documentation conventions, (elisp)Documentation Tips. In Emacs Lisp buffers, Flycheck will first use emacs-lisp, and then emacs-lisp-checkdoc.

如果选中的语法检查器关联其他检查器的话,Flycheck可能会做进一步检查。例如,emacs-lisp语法检查器使用Emacs的字节编译器检查Emacs lisp,但它关联了检查Emacs Lisp是否违反文档约定emacs-lisp-checkdoc语法检查器。Emacs Lisp buffer中,Flycheck先使用emacs-lisp,然后使用emacs-lisp-checkdoc。

Flycheck ignores chained checkers which are not contained in flycheck-checkers.

Flycheck忽略没有包含在flycheck-chekcers中的关联检查器。

Like everything else in GNU Emacs, syntax checkers have online documentation as well. If you are interested what major modes a particular syntax checker in flycheck-checkers supports, or what tool it uses, type C-c ! ?:

像GNU Emacs所有其他东西一样,语法检查器也有在线文档,如果有兴趣了解flycheck-checkers中的特定语法检查器支持哪种主模式,或者它使用什么工具,键入C-c ! ?:

  • C-c ! ?
  • M-x flycheck-describe-checker

    Prompt for a syntax checker and show its documentation.

    输入语法检查器,显示它的文档。

    The documentation includes the name of the program or service used by the syntax checker, a list of major modes in which the checker will be used, and a list of its options.

    文档包括语法检查器使用的程序或服务的名字,检查器适用的主模式列表以及它的选项。

Instead of letting Flycheck select a syntax checker automatically you can also explicitly tell Flycheck which checker to use for the current buffer, by manually selecting a specific syntax checker:

除了让Flycheck自动选择语法检查器,还可以为当前buffer手动选择Flycheck使用的检查器:

  • C-c ! s
  • M-x flycheck-select-checker

    Prompt for a syntax checker and select this syntax checker for the current buffer.

    输入检查器名字,为当前buffer选择该检查器。

  • C-u C-c ! s
  • C-u M-x flycheck-select-checker Remove any manual

    syntax checker selection for the current buffer, and let Flycheck automatically select a syntax checker from flycheck-checkers again.

    当前buffer语法检查器选项,再次让Flycheck从flycheck-checkers中自动选择语法检查器。

You can also select a syntax checker via the variable flycheck-checker. In fact, flycheck-select-checker just sets this variable accordingly:

也可以通过变量flycheck-checker选择语法选择器,事实上,flycheck-select-checker只是设置了这个变量:

  • Variable: flycheck-checker

    A syntax checker to use for the current buffer.

    用于当前buffer的语法检查器。

    If nil (the default), Flycheck will automatically select the best checker from flycheck-checkers.

    如果为nil(默认值),Flycheck将会自动从flycheck-checkers中选择最好的检查器。

    If set to a syntax checker, Flycheck will use this syntax checker for the current buffer, and never automatically select any other. Flycheck still runs chained checkers, though.

    如果设置为一个语法检查器,Flycheck会将该检查器用于当前buffer,不再自动选择其他的。Flycheck仍会运行关联的检查器。

    If the syntax checker selected by this variable does not work in the current buffer, Flycheck signals an error.

    如果该变量选中的检查器不能再buffer中工作,Flych将会给出错误信号。

    You can set this variable locally. For instance, if your Python project mandates Flake8 as a syntax checker, you can tell Flycheck to only use the corresponding checker python-flake8 in Python files of your project by setting flycheck-checker as a directory-local variable in the top-level directory of your project with M-x add-dir-local-variable RET python-mode RET flycheck-checker RET python-flake8. See (emacs)Directory Variables, for more information about directory variables.

    可以将该变量设置为局部值。例如,如果Python项目将Flake8设置为语法检查器,Flycheck对项目中的所有python文件只使用对应的检查器python-flake8检查。要这样做,需要在项目顶层目录中通过

    M-x add-dir-local-variable RET python-mode RET flycheck-checker RET python-flake8
    

    将flycheck-checker设置为局部目录变量。

Occasionally you may want to disable specific syntax checkers completely, so that they can never be used at all, neither via automatic nor via manual selection:

偶尔可能想要完全禁用特定语法检查器,这样它们就会永远不会被使用,不管通过自动还是手动选择:

  • C-c ! x
  • M-x flycheck-disable-checker

    Prompt for a syntax checker to disable in the current buffer.

    提示要在当前buffer中关闭的语法选择器。

  • C-u C-c ! x
  • C-u M-x flycheck-disable-checker

    Prompt for a syntax checker to re-enable in the current buffer.

    提示要在当前buffer中重新启用的语法选择器。

This is particularly useful if you want to disable syntax checkers that are chained after others. For instance, if you do not care for documentation conventions of Emacs Lisp you may not need for the emacs-lisp-checkdoc checker, so you can disable it for the current buffer with M-x flycheck-disable-checker RET emacs-lisp-checkdoc.

这对于禁用被关联的语法检查器很有用。例如,如果不关心Emacs Lisp的文档约定,可能就不需要emacs-lisp-checkdoc检查器,所以可以使用M-x flycheck-disable-checker RET emacs-lisp-checkdoc禁用它。

flycheck-disable-checker actually sets the buffer-local value of the flycheck-disabled-checkers option:

flycheck-disable-checker 实际上是设置了buff-local值flycheck-disabled-checkers 选项的buffer-local值:

  • User Option: flycheck-disabled-checkers

    A list of disabled syntax checkers. Flycheck will never use disabled syntax checkers to check a buffer.

    禁用的语法检查器列表。Flycheck将不会使用禁用的语法检查器检查buffer。

    You can customise this variable with M-x customize-variable RET flycheck-disabled-checkers or set its default value in your init file to permanently disable specific checkers. For instance, to permanently disable Clang for all C/C++ buffers:

    可以通过M-x customize-variable RET flycheck-disabled-checkers定制该变量,或者在init文件中将其值设置为永远禁用的指定检查器。例如,针对C/C++ buffers永远禁用Clang。

    (setq-default flycheck-disabled-checkers '(c/c++-clang))
    

    You can also disable checkers via local variables. For instance, to disable emacs-lisp-checkdoc for your entire project, add it to flycheck-disabled-checkers in the .dir-locals.el file of your project:

    也可以通过局部变量禁用检查器。例如针对整个工程禁用emacs-lisp-checkdoc,在工程的.dir-locals.el文件中,将它添加到flycheck-disable-checkers变量中。

    ((emacs-lisp-mode (flycheck-disabled-checkers emacs-lisp-checkdoc)))
    

    See (emacs)Directory Variables, for more information about directory variables.

You can change the completion system used by the commands of this section with flycheck-completion-system.

可以通过flycheck-completion-system改变本节所有命令使用的补全系统。

4.3 Reporting results

When a syntax check in the current buffer has finished, Flycheck reports the results of the syntax checkers used by the check in the current buffer:

  • It highlights errors and warnings reported by a syntax checking in the buffer according to flycheck-highlighting-mode,
  • and indicates these locations in the fringe according to flycheck-indication-mode.

User Option: flycheck-highlighting-mode

How Flycheck highlights errors and warnings in the buffer:

  • lines

    Highlight the whole line, ignoring any column information.

  • columns

    Highlight the column of the error, if the error has a column, otherwise behave as lines.

  • symbols

    Highlight the symbol at the error column, if any, otherwise behave like columns. This is default

  • sexps

    Highlight the expression at the error column, if any, otherwise behave like columns. Warning: sexps can be very slow in some major modes, notably the built-in python-mode.

  • nil

    Do not highlight errors at all.

Flycheck uses the flycheck-error, flycheck-warning and flycheck-info faces to highlight errors, warnings and info messages respectively.

User Option: flycheck-indication-mode

How Flycheck indicates errors and warnings:

  • left-fringe
  • right-fringe

    Indicate errors in the left or right fringe respectively. See (emacs)Fringes, for more information about fringes.

    Flycheck uses the flycheck-fringe-error, flycheck-fringe-warning, and flycheck-fringe-info faces for the indicators for the corresponding error levels.

  • nil

    Do not indicate errors and warnings.

To avoid flooding a buffer with excessive reports, Flycheck discards any reports and disables the corresponding syntax checker subsequently, if the total number of reported errors of any level exceeds the value of flycheck-checker-error-threshold.

You can explicitly clear with the flycheck-clear command.

4.4 Navigating errors

By default, Flycheck integrates into standard error navigation commands of Emacs: M-g n (next-error) and M-g p (previous-error) will navigate between Flycheck warnings and errors in the current buffer. See (emacs)Compilation Mode, for more information about these commands. You can disable this integration by setting flycheck-standard-error-navigation to nil, and re-enabling flycheck-mode afterwards.

Note: With standard error navigation visible compilation buffers (e.g. from M-x compile, M-x grep, M-x occur, etc.) take precedence over Flycheck errors.

Flycheck provides an independent set of navigation commands which will always navigate Flycheck errors in the current buffer, regardless of visible compilation buffers and flycheck-standard-error-navigation:

  • C-c ! n
  • M-x flycheck-next-error

    Jump to the next error.

    With prefix argument, jump forwards by as many errors as specified by the prefix argument, e.g. M-3 C-c ! n will move to the 3rd error from the current point. With negative prefix argument, move to previous errors instead. Signal an error, if there are no more Flycheck errors.

  • C-c ! p
  • M-x flycheck-previous-error

    Jump to the previous Flycheck error.

    With prefix argument, jump backwards by as many errors as specified by the prefix argument, e.g. M-3 C-c ! p will move to the 3rd error before the current point. With negative prefix argument, move to next errors instead. Signal an error, if there are no more Flycheck errors.

    • M-x flycheck-first-error

      Jump to the first Flycheck error.

      With prefix argument, jump forwards to by as many errors as specified by the prefix argument, e.g. M-3 M-x flycheck-first-error moves to the 3rd error from the beginning of the buffer. With negative prefix argument, move to the last error instead.

By default, these commands consider all errors in the current buffer. With flycheck-navigation-minimum-level you can restrict them to errors above certain levels:

User Option: flycheck-navigation-minimum-level

The minimum levels of errors to consider for navigation.

If set to an error level, only navigate to errors whose level is as least as severe as this one. If nil, navigate to all errors.

4.5 Displaying errors

When the point moves to an error location Flycheck automatically displays the error at point after a short delay: User Option: flycheck-display-errors-delay

The number of seconds to wait before displaying the error at point. Floating point numbers can express fractions of seconds.

You can also display errors at point explicitly with C-c ! h:

  • C-c ! h
  • M-x flycheck-display-error-at-point

    Show the error(s) at point.

By default Flycheck shows the error message and the error ID in the echo area, but you can customise how Flycheck displays errors with flycheck-display-errors-function:

  • User Option: flycheck-display-errors-function

    A function to display errors. The function is called with a list of Flycheck error objects to display. See Errors, for more information about these objects.

Flycheck provides some built-in display functions:

  • Function: flycheck-display-error-messages

    Show error messages and IDs in the echo area.

  • Function: flycheck-display-error-messages-unless-error-list

    Like flycheck-display-error-messages, but does not show anything if the error list is visible. See Listing errors, for more information about the error list.

Alternatively the flycheck-pos-tip extension provides an display function which shows error messages in a graphical popup.

In addition to this display mechanism, Flycheck adds a tooltip to each error which appears when you hover the error location with the mouse pointer. You can force Emacs to show the contents of the tooltip in the echo area with C-h . (display-local-help).

The contents of this tooltip are created with flycheck-help-echo-function:

  • User Option: flycheck-help-echo-function

    A function to compute the contents of the error tooltips.

    By default Flycheck adds the error message and the error ID of all errors at point to the tooltip contents.

4.6 Killing errors

You can also put error messages into the kill ring:

  • C-c ! C-w
  • M-x flycheck-copy-errors-as-kill

    Copy all Flycheck error messages at point into the kill ring.

    Each error message is killed separately, so C-y (yank) only yanks a single error message. You can use M-y (yank-pop) to cycle between the killed messages after yanking the first one.

  • C-u C-c ! C-w
  • C-u M-x flycheck-copy-errors-as-kill

    Copy all Flycheck error messages at point, including their IDs.

  • M-0 C-c ! C-w
  • M-0 M-x flycheck-copy-errors-as-kill

    Copy the IDs of the errors at point.

4.7 Listing errors

4.8 Mode line display

4.9 Configuring checkers

5 Syntax checker definitions

6 Flycheck hooks

7 Flycheck API:

8 Supported languages

Author: lsl

Created: 2017-08-30 三 16:06

Emacs 25.2.2 (Org mode 8.2.10)

Validate