Documentation/CodingStyle: Move emacs settings into .dir-locals.el
PATCH 1/1 Documentation/CodingStyle: Move emacs settings into .dir-locals.el
For new kernel developers who use emacs it is tedious to follow the instructions in Documentation/process/coding-style.rst for configuring emacs. Make it easier for emacs users by moving these settings into the top-level .dir-locals.el file. Emacs supports directory-local variables since version 23.1, released in 2009. See also
https://lists.gnu.org/archive/html/info-gnu-emacs/2009-07/msg00000.html
The settings in .dir-locals.el are not identical to those in Documentation/process/coding-style.rst. The most important difference is that "(arglist-cont-nonempty c-lineup-gcc-asm-reg c-lineup-arglist-tabs-only)" (which is not a valid alist) has been changed into "(arglist-cont-nonempty . c-lineup-arglist)". I have verified with several large and nontrivial kernel source files that the settings in .dir-locals.el format code according to what checkpatch expects.
The Italian and Chinese translations of the modified paragraphs have been generated by Google Translate.
--- .dir-locals.el | 41 +++++++++++++++ Documentation/process/coding-style.rst | 49 ++---------------- .../it_IT/process/coding-style.rst | 50 ++----------------- .../translations/zh_CN/coding-style.rst | 43 +--------------- 4 files changed, 53 insertions(+), 130 deletions(-) create mode 100644 .dir-locals.el
.dir-locals.el new file +41 -0
@@ -0,0 +1,41 @@ +;; Emacs settings for Linux kernel C code. + +( + (c-mode . ( + (c-basic-offset . 8) + (c-cleanup-list . (brace-else-brace)) + (c-hanging-braces-alist . ( + (arglist-cont-nonempty) + (block-close . c-snug-do-while) + (brace-entry-open) + (brace-list-open) + (substatement-open after) + )) + (c-label-minimum-indentation . 0) + (c-offsets-alist . ( + (arglist-cont-nonempty . c-lineup-arglist) + (arglist-intro . +) + (brace-list-intro . +) + (c . c-lineup-C-comments) + (case-label . 0) + (comment-intro . c-lineup-comment) + (cpp-define-intro . +) + (cpp-macro . -1000) + (cpp-macro-cont . +) + (defun-block-intro . +) + (else-clause . 0) + (func-decl-cont . +) + (inclass . +) + (inher-cont . c-lineup-multi-inher) + (knr-argdecl-intro . 0) + (label . 0) + (statement . 0) + (statement-block-intro . +) + (statement-case-intro . +) + (statement-cont . +) + (substatement . +) + )) + (indent-tabs-mode . t) + ) + ) +)
Documentation/process/coding-style.rst +5 -44
55 lines not on this page · raw message
Documentation/translations/it_IT/process/coding-style.rst +5 -45
56 lines not on this page · raw message
Documentation/translations/zh_CN/coding-style.rst +2 -41
49 lines not on this page · raw message
Signature · 1 line
2.20.1.415.g653613c723-goog
Documentation/process/coding-style.rst item, explaining its use. · line 579
Quoted 10 lines · Bart Van Assche
Documentation/process/coding-style.rst +0
-6@@ -571,50 +571,11 @@ item, explaining its use. 9) You've made a mess of it --------------------------- -That's OK, we all do. You've probably been told by your long-time Unix -user helper that ``GNU emacs`` automatically formats the C sources for -you, and you've noticed that yes, it does do that, but the defaults it -uses are less than desirable (in fact, they are worse than random -typing - an infinite number of monkeys typing into GNU emacs would never -make a good program).
I feel like this patch makes the mistake a lot of doc patches do ... it removes some of the whimsical humourous comments that have been with us for years. I don't think this paragraph needs to be changed in the slightest.
Quoted 3 lines
Documentation/process/coding-style.rst +0
-3-So, you can either get rid of GNU emacs, or change it to use saner -values. To do the latter, you can stick the following in your .emacs file: -
[...]
Documentation/process/coding-style.rst item, explaining its use. · line 578
Quoted 8 lines
Documentation/process/coding-style.rst +5
-3- -This will make emacs go better with the kernel coding style for C -files below ``~/src/linux-trees``. +``GNU emacs`` automatically formats the C sources for you. However, +the defaults it uses are less than desirable. Use a version of emacs +that support directory local variables such that it automatically +picks up the settings from .dir-locals.el in the kernel top level +directory.
How about:
So, you can either get rid of GNU emacs, or change it to use saner defaults. Versions of emacs since [...] support directory local variables and will pick up the settings from .dir-locals.el in the kernel top level directory.
Quoted 32 lines · Matthew Wilcox
Documentation/process/coding-style.rst item, explaining its use. · line 579
Quoted 10 lines · Bart Van Assche
@@-571,50 +-571,11 @@item, explaining its use.
9) You've made a mess of it
---------------------------Documentation/process/coding-style.rst +0
-6-That's OK, we all do. You've probably been told by your long-time Unix -user helper that ``GNU emacs``automatically formats the C sources for -you, and you've noticed that yes, it does do that, but the defaults it -uses are less than desirable (in fact, they are worse than random -typing - an infinite number of monkeys typing into GNU emacs would never -make a good program).I feel like this patch makes the mistake a lot of doc patches do ... it removes some of the whimsical humourous comments that have been with us for years. I don't think this paragraph needs to be changed in the slightest.
Documentation/process/coding-style.rst item, explaining its use. · line 583
Quoted 3 lines
Documentation/process/coding-style.rst +0
-3-So, you can either get rid of GNU emacs, or change it to use saner -values. To do the latter, you can stick the following in your .emacs file: -[..]>>-
Review
Quoted 7 lines
(quoted diff) +5
-2-This will make emacs go better with the kernel coding style for C -files below ``~/src/linux-trees`` +-``GNU emacs``automatically formats the C sources for you. However, +-the defaults it uses are less than desirable. Use a version of emacs +-that support directory local variables such that it automatically +-picks up the settings from .dir-locals.el in the kernel top level +-directory.How about:
Quoted 4 lines
So, you can either get rid of GNU emacs, or change it to use saner defaults. Versions of emacs since [..]support directory local variables and will pick up the settings from .dir-locals.el in the kernel top level directory.
Hi Matthew,
Thanks for having taken a look. I had removed the first paragraph of section 9 since it seemed more negative than humouristic to me. Anyway, I will make the change that you proposed.
Bart.
Federico Vaga
maintainerQuoted 7 lines · CET Bart Van Assche
For new kernel developers who use emacs it is tedious to follow the instructions in
Documentation/process/coding-style.rstfor configuring emacs. Make it easier for emacs users by moving these settings into the top-level .dir-locals.el file. Emacs supports directory-local variables since version 23.1, released in 2009. See also
https://lists.gnu.org/archive/html/info-gnu-emacs/2009-07/msg00000.html
Quoted 8 lines
The settings in .dir-locals.el are not identical to those in
Documentation/process/coding-style.rst. The most important difference is that "(arglist-cont-nonempty c-lineup-gcc-asm-reg c-lineup-arglist-tabs-only)" (which is not a valid alist) has been changed into "(arglist-cont-nonempty . c-lineup-arglist)". I have verified with several large and nontrivial kernel source files that the settings in .dir-locals.el format code according to what checkpatch expects.
Isn't it better if we collect such configuration files into a dedicated directory (where exactly?) instead of putting them in the top-level one? Then, the developer has to copy/link the configuration file into the top-level directory.
If we accept emacs configuration files in the top-level directory we will have to accept also the ones from other editors (of course, when they support local configurations). In addition, probably, there are people who do not want to use local configurations.
Quoted 2 lines
The Italian and Chinese translations of the modified paragraphs have been generated by Google Translate.
Thanks for the Italian translation but unfortunately Google Translate is not up to the task :) Any one can understand the translation that Google did but it is incorrect.
I can give you a correct translation once it has been agreed on the English version.
Quoted 242 lines
Signed-off-by Bart Van Assche <[email protected]>Cc Geyslan G. Bem <[email protected]>Cc Tiago Natel de Moura <[email protected]>Cc Alison Chaiken <[email protected]>Cc Joe Perches <[email protected]>Cc Federico Vaga <[email protected]>Cc Zhang Le <[email protected]>Cc Li Yang <[email protected]>--- .dir-locals.el | 41 +++++++++++++++ Documentation/process/coding-style.rst | 49 ++---------------- .../it_IT/process/coding-style.rst | 50 ++----------------- .../translations/zh_CN/coding-style.rst | 43 +--------------- 4 files changed, 53 insertions(+), 130 deletions(-) create mode 100644 .dir-locals.el.dir-locals.el new file +41
-0@@ -0,0 +1,41 @@ +;; Emacs settings for Linux kernel C code. + +( + (c-mode . ( + (c-basic-offset . 8) + (c-cleanup-list . (brace-else-brace)) + (c-hanging-braces-alist . ( + (arglist-cont-nonempty) + (block-close . c-snug-do-while) + (brace-entry-open) + (brace-list-open) + (substatement-open after) + )) + (c-label-minimum-indentation . 0) + (c-offsets-alist . ( + (arglist-cont-nonempty . c-lineup-arglist) + (arglist-intro . +) + (brace-list-intro . +) + (c . c-lineup-C-comments) + (case-label . 0) + (comment-intro . c-lineup-comment) + (cpp-define-intro . +) + (cpp-macro . -1000) + (cpp-macro-cont . +) + (defun-block-intro . +) + (else-clause . 0) + (func-decl-cont . +) + (inclass . +) + (inher-cont . c-lineup-multi-inher) + (knr-argdecl-intro . 0) + (label . 0) + (statement . 0) + (statement-block-intro . +) + (statement-case-intro . +) + (statement-cont . +) + (substatement . +) + )) + (indent-tabs-mode . t) + ) + ) +)(quoted diff) +0
-0
b/Documentation/process/coding-style.rstindex277c113376a6..e12b845d6766100644Documentation/process/coding-style.rst +5
-43@@ -571,50 +571,11 @@ item, explaining its use. 9) You've made a mess of it --------------------------- -That's OK, we all do. You've probably been told by your long-time Unix -user helper that ``GNU emacs`` automatically formats the C sources for -you, and you've noticed that yes, it does do that, but the defaults it -uses are less than desirable (in fact, they are worse than random -typing - an infinite number of monkeys typing into GNU emacs would never -make a good program). - -So, you can either get rid of GNU emacs, or change it to use saner -values. To do the latter, you can stick the following in your .emacs file: - -.. code-block:: none - - (defun c-lineup-arglist-tabs-only (ignored) - "Line up argument lists by tabs, not spaces" - (let* ((anchor (c-langelem-pos c-syntactic-element)) - (column (c-langelem-2nd-pos c-syntactic-element)) - (offset (- (1+ column) anchor)) - (steps (floor offset c-basic-offset))) - (* (max steps 1) - c-basic-offset))) - - (add-hook 'c-mode-common-hook - (lambda () - ;; Add kernel style - (c-add-style - "linux-tabs-only" - '("linux" (c-offsets-alist - (arglist-cont-nonempty - c-lineup-gcc-asm-reg - c-lineup-arglist-tabs-only)))))) - - (add-hook 'c-mode-hook - (lambda () - (let ((filename (buffer-file-name))) - ;; Enable kernel mode for the appropriate files - (when (and filename - (string-match (expand-file-name "~/src/linux-trees") - filename)) - (setq indent-tabs-mode t) - (setq show-trailing-whitespace t) - (c-set-style "linux-tabs-only"))))) - -This will make emacs go better with the kernel coding style for C -files below ``~/src/linux-trees``. +``GNU emacs`` automatically formats the C sources for you. However, +the defaults it uses are less than desirable. Use a version of emacs +that support directory local variables such that it automatically +picks up the settings from .dir-locals.el in the kernel top level +directory. But even if you fail in getting emacs to do sane formatting, not everything is lost: use ``indent``.(quoted diff) +0
-0
b/Documentation/translations/it_IT/process/coding-style.rstindexb707bdbe178c..05a86c69bd5d100644Documentation/translations/it_IT/process/coding-style.rst +5
-44@@ -578,51 +578,11 @@ commento per spiegarne l'uso. 9) Avete fatto un pasticcio --------------------------- -Va bene, li facciamo tutti. Probabilmente vi è stato detto dal vostro -aiutante Unix di fiducia che ``GNU emacs`` formatta automaticamente il -codice C per conto vostro, e avete notato che sì, in effetti lo fa, ma che -i modi predefiniti non sono proprio allettanti (infatti, sono peggio che -premere tasti a caso - un numero infinito di scimmie che scrivono in -GNU emacs non faranno mai un buon programma). - -Quindi, potete sbarazzarvi di GNU emacs, o riconfigurarlo con valori più -sensati. Per fare quest'ultima cosa, potete appiccicare il codice che -segue nel vostro file .emacs: - -.. code-block:: none - - (defun c-lineup-arglist-tabs-only (ignored) - "Line up argument lists by tabs, not spaces" - (let* ((anchor (c-langelem-pos c-syntactic-element)) - (column (c-langelem-2nd-pos c-syntactic-element)) - (offset (- (1+ column) anchor)) - (steps (floor offset c-basic-offset))) - (* (max steps 1) - c-basic-offset))) - - (add-hook 'c-mode-common-hook - (lambda () - ;; Add kernel style - (c-add-style - "linux-tabs-only" - '("linux" (c-offsets-alist - (arglist-cont-nonempty - c-lineup-gcc-asm-reg - c-lineup-arglist-tabs-only)))))) - - (add-hook 'c-mode-hook - (lambda () - (let ((filename (buffer-file-name))) - ;; Enable kernel mode for the appropriate files - (when (and filename - (string-match (expand-file-name "~/src/linux-trees") - filename)) - (setq indent-tabs-mode t) - (setq show-trailing-whitespace t) - (c-set-style "linux-tabs-only"))))) - -Questo farà funzionare meglio emacs con lo stile del kernel per i file che -si trovano nella cartella ``~/src/linux-trees``. +`` GNU emacs`` formatta automaticamente le sorgenti C per te. Tuttavia, +le impostazioni predefinite che utilizza sono meno desiderabili. +Utilizzare una versione di emacs che supporti le variabili locali della +directory in modo tale che raccolga automaticamente le impostazioni da +.dir-locals.el nella directory di livello superiore del kernel. Ma anche se doveste fallire nell'ottenere una formattazione sensata inemacs non tutto è perduto: usate ``indent``.
(quoted diff) +0
-0
b/Documentation/translations/zh_CN/coding-style.rstindex1466aa64b8b4..32a72a9c110a100644Documentation/translations/zh_CN/coding-style.rst +2
-40@@ -516,47 +516,8 @@ Documentation/doc-guide/ 和 scripts/kernel-doc 以获得详细信息。 9) 你已经把事情弄糟了 ------------------------------ -这没什么,我们都是这样。可能你的使用了很长时间 Unix 的朋友已经告诉你 -``GNU emacs`` 能自动帮你格式化 C 源代码,而且你也注意到了,确实是这样,不过它 -所使用的默认值和我们想要的相去甚远 (实际上,甚至比随机打的还要差——无数个猴子 -在 GNU emacs 里打字永远不会创造出一个好程序) (译注:Infinite Monkey Theorem) - -所以你要么放弃 GNU emacs,要么改变它让它使用更合理的设定。要采用后一个方案, -你可以把下面这段粘贴到你的 .emacs 文件里。 - -.. code-block:: none - - (defun c-lineup-arglist-tabs-only (ignored) - "Line up argument lists by tabs, not spaces" - (let* ((anchor (c-langelem-pos c-syntactic-element)) - (column (c-langelem-2nd-pos c-syntactic-element)) - (offset (- (1+ column) anchor)) - (steps (floor offset c-basic-offset))) - (* (max steps 1) - c-basic-offset))) - - (add-hook 'c-mode-common-hook - (lambda () - ;; Add kernel style - (c-add-style - "linux-tabs-only" - '("linux" (c-offsets-alist - (arglist-cont-nonempty - c-lineup-gcc-asm-reg - c-lineup-arglist-tabs-only)))))) - - (add-hook 'c-mode-hook - (lambda () - (let ((filename (buffer-file-name))) - ;; Enable kernel mode for the appropriate files - (when (and filename - (string-match (expand-file-name "~/src/linux-trees") - filename)) - (setq indent-tabs-mode t) - (setq show-trailing-whitespace t) - (c-set-style "linux-tabs-only"))))) - -这会让 emacs 在 ``~/src/linux-trees`` 下的 C 源文件获得更好的内核代码风格。 +``GNU emacs``會自動為您設置C源代碼。但是,它使用的默認值不太理想。 +使用支持目錄本地變量的emacs版本,以便它自動從內核頂級目錄中的.dir-locals.el中獲取設置。 不过就算你尝试让 emacs 正确的格式化代码失败了,也并不意味着你失去了一切:还可 以用 ``indent`` 。
Quoted 9 lines · Federico Vaga
Isn't it better if we collect such configuration files into a dedicated directory (where exactly?) instead of putting them in the top-level one? Then, the developer has to copy/link the configuration file into the top-level directory.
If we accept emacs configuration files in the top-level directory we will have to accept also the ones from other editors (of course, when they support local configurations). In addition, probably, there are people who do not want to use local configurations.
Fully agreed.
Also, you probably do not wish the file to change when you switch branches with different upstream baselines. Or deal with possible emacs version dependent changes. I do like having the example in the kernel tree, but let the users deal with actually using the file. Placing the file at the top level makes it harder for users to have a file of their own there. This from an emacs user.
BR,
Jani.
Signature · 1 line
Jani Nikula, Intel Open Source Graphics Center
Quoted 6 lines · Jani Nikula
Also, you probably do not wish the file to change when you switch branches with different upstream baselines. Or deal with possible emacs version dependent changes. I do like having the example in the kernel tree, but let the users deal with actually using the file. Placing the file at the top level makes it harder for users to have a file of their own there. This from an emacs user.
If this patch gets accepted upstream it won't take long before the .dir-locals.el file ends up in all branches. Additionally, I expect that the rate of change for this file will be low so I do not except any inconsistencies between branches.
Regarding emacs versions: this patch has been tested with different emacs versions. Additionally, the rate of change in emacs' CC mode is slow. Any backwards incompatible changes in that mode would cause trouble to a very large number of users so I do not expect radical changes in emacs' CC mode.
Regarding users having their own version of .dir-locals.el: why do you think anyone would want to do that? Anyway, if anyone wants to replace that file they can provide a .dir-locals-2.el file. See also
https://www.gnu.org/software/emacs/manual/html_node/emacs/Directory-Variables.html.
Bart.
Quoted 2 lines · Bart Van Assche
Regarding users having their own version of .dir-locals.el: why do you think anyone would want to do that?
Err, .dir-locals.el is not only for a project to enforce local variables on emacs users, it's also for the users to set local variables for the project.
Quoted 2 lines
Anyway, if anyone wants to replace that file they can provide a .dir-locals-2.el file.
It does not replace anything, it's loaded in addition to .dir-locals.el.
BR,
Jani.
Signature · 1 line
Jani Nikula, Intel Open Source Graphics Center
Quoted 17 lines · Federico Vaga
Quoted 7 lines · CET Bart Van Assche
For new kernel developers who use emacs it is tedious to follow the instructions in
Documentation/process/coding-style.rstfor configuring emacs. Make it easier for emacs users by moving these settings into the top-level .dir-locals.el file. Emacs supports directory-local variables since version 23.1, released in 2009. See also
https://lists.gnu.org/archive/html/info-gnu-emacs/2009-07/msg00000.htmlQuoted 8 lines
The settings in .dir-locals.el are not identical to those in
Documentation/process/coding-style.rst. The most important difference is that "arglist-cont-nonempty c-lineup-gcc-asm-reg c-lineup-arglist-tabs-only)"(which is not a valid alist) has been changed into "arglist-cont-nonempty . c-lineup-arglist)" I have verified with several large and nontrivial kernel source files that the settings in .dir-locals.el format code according to what checkpatch expects.
Quoted 4 lines
Isn't it better if we collect such configuration files into a dedicated directory (where exactly?) instead of putting them in the top-level one? Then, the developer has to copy/link the configuration file into the top-level directory.
I don't think so. The reason we have the checkpatch script and the coding-style.rst document in the kernel tree is to promote coding style uniformity. Placing the .dir-locals.el at the top level serves the same purpose. Additionally, if the .dir-locals.el file is not at the top level many kernel developers will overlook it.
Quoted 3 lines
If we accept emacs configuration files in the top-level directory we will have to accept also the ones from other editors (of course, when they support local configurations).
I am aware of this and I'm fine with this.
Quoted 2 lines
In addition, probably, there are people who do not want to use local configurations.
I expect that only a minority will not want to use the .dir-locals.el file. Anyone who wants to override any of the settings from .dir-locals.el can do that by using one of the methods explained in the emacs manual, e.g. by adding a .dir-locals-2.el file. See also
https://www.gnu.org/software/emacs/manual/html_node/emacs/Directory-Variables.html.
Quoted 9 lines
Quoted 2 lines
The Italian and Chinese translations of the modified paragraphs have been generated by Google Translate.
Thanks for the Italian translation but unfortunately Google Translate is not up to the task :) Any one can understand the translation that Google did but it is incorrect.
I can give you a correct translation once it has been agreed on the English version.
Thank you for this offer. I will leave out the Italian translation.
Bart.
Jonathan Corbet
maintainerQuoted 10 lines · On Fri, 04 Jan 2019 08:32:38 -0800 Bart Van Assche <[email protected]> wrote:
Quoted 4 lines
Isn't it better if we collect such configuration files into a dedicated directory (where exactly?) instead of putting them in the top-level one? Then, the developer has to copy/link the configuration file into the top-level directory.
I don't think so. The reason we have the checkpatch script and the
coding-style.rstdocument in the kernel tree is to promote coding style uniformity. Placing the .dir-locals.el at the top level serves the same purpose. Additionally, if the .dir-locals.el file is not at the top level many kernel developers will overlook it.
I think we have to be careful about silently configuring other developers' tools. We put checkpatch.pl in the kernel tree, but we don't add a git hook for everybody to run it. I'm totally in favor of adding this .el file to the documentation (or samples) directory and pointing users to it; I'm less thrilled about putting in a dotfile where emacs will just pick it up.
jon
Quoted 6 lines · Jonathan Corbet
Quoted 4 lines · On Fri, 04 Jan 2019 08:32:38 -0800 Bart Van Assche <[email protected]> wrote:
Quoted 4 lines
Isn't it better if we collect such configuration files into a dedicated directory (where exactly?) instead of putting them in the top-level one? Then, the developer has to copy/link the configuration file into the top-level directory.
[]
Quoted 2 lines
I think we have to be careful about silently configuring other developers' tools.
I agree and as an emacs user I am also not a proponent of this change.
Longtime emacs users are very sensitive to their keybindings and styles and having these change unexpectedly can be unsettling.