Difference between revisions of "Coding style/Reindenting"

Revision as of 13:32, 10 November 2009

How to help with the "great reindent"

Sign up below at #Cleanup coordination.

• Temporarily modify the #Makefile variables to try out stuff
• Run the make mark-cstyle and make reindent targets
• Inspect the changes
  • svn diff
  • svn diff -x -w (ignores whitespace changes)
  • svn diff | cat -et (to show tabs and end-of-line)
• Look for #Common failure modes

Infrastructure

• emacs file-local variable settings
• scripts in src/util
• make mark-cstyle
• make reindent

Prerequisites

The reindenting scripts require at least GNU Emacs version 22. Earlier versions of Emacs had versions of CC-Mode that produce variant indentations. The number of differences is small, though. Different versions of Emacs have different incarnations of whitespace.el that behave differently and have different interfaces. The reindenting scripts accommodate for these differences, with a very few exceptions. (Old-style whitespace.el cleans up mixtures of spaces and tabs anywhere on a line, while the new-style one only does so inside indentation whitespace.)

GNU find (or a reasonably compatible find program that supports the -path and -print0 options) is also required, as is an xargs program that supports the -0 option.

Python is also needed, though any modern version (2.3 or later) should work.

If the versions of these programs that you are using do not have their usual names, you can override the program names when running make, e.g.

make reindent FIND=gfind XARGS=gxargs EMACS=/usr/local/bin/emacs22

Emacs variables

We use various combinations Emacs file-local variable settings to mark what sort of C formatting style a given source file conforms with, as well as for controlling the operation of the reindenting scripts.

This is the standard file-local variable line (at top of file) for marking files expected to fully conform to our "krb5" formatting style:

/* -*- mode: c; c-basic-offset: 4; indent-tabs-mode: nil -*- */

For BSD-derived code, we use:

/* -*- mode: c; c-file-style: "bsd"; indent-tabs-mode: t -*- */

Makefile targets

Running make mark-cstyle will mark certain designated files as the "krb5" style, and certain others as "bsd" style. At the moment, it uses an explicitly specified group of directories as starting points, but in the future it should start at the top of the source tree and rely on exclusions to tailor its operation.

Running make reindent executes the actual reindenting script, which examines the file-local variable settings in each file. The steps are:

• Untabify (expand tabs to spaces) if the file-local variable settings specify
• Reindent if the file is marked as conforming to the "krb5" C style
• Perform whitespace cleanup
  • Delete whitespace at the ends of lines
  • Remove blank lines at beginning and end of file
  • Fix up mixtures of tabs and spaces (only if indent-tabs-mode is explicitly specified)

Makefile variables

$(INDENTDIRS) sets the list of directories that the make mark-cstyle target will operate on.

$(BSDFILES) contains a list of files that the make mark-cstyle target will mark as BSD-style.

$(OTHEREXCLUDES) contains a list of other files or directories to exclude from being marked as krb5-style.

Common failure modes

The most consistently occurring problems when reindenting appear to be:

• Function declarations or similar constructs that have an open-parenthesis as the first non-whitespace character of a line
• Non-conforming block comments, i.e., ones without an asterisk on the left-hand side of each line

Cleanup coordination

Edit the tables to volunteer to evaluate a directory or exclusion. Use ~~~ (three tildes) to insert your username in the "who?" cell of a row. Please see [1] for help with editing MediaWiki tables. If a table row that indicates a directory name seems to broad, feel free to create new rows specifying subdirectories so that we can divide the work on a finer granularity.

Abbreviations:

P/C

Proposed/Committed

E/F

Evaluate/Fix

Temporary exclusions

Exclusions here will move to one of the "to keep" tables below once evaluated. If they are fixed, remove them instead. (from the table, and from the Makefile, if the exclusion was already committed)

Exclusions to keep