Coding style/Reindenting

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. 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

directories included in find ($(INDENTDIRS))

directory name	P/C	exclusions?	reviewed?	who?	comments
appl
ccapi
clients	C	N	N
include	P			Ghudson
kadmin	C	Y	N
kdc	C	N	N
kim
lib/apputuils
lib/crypto
lib/gssapi
lib/kadm5	C	Y	N
lib/kdb5	C	N	N
lib/krb5	C	Y	N
lib/rpc
plugins
prototype	C	N	Y	TomYu
slave	C	Y	N	TomYu
tests
util
windows

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 eval/fix ($(BSDFILES) or $(OTHEREXCLUDES))

directory or file name	P/C	E/F	why?	who?	comments
lib/krb5/asn.1/asn1_decode.h	C	F	block comments	TomYu
lib/krb5/asn.1/asn1_encode.h	C	F	block comments	TomYu
lib/krb5/asn.1/asn1_k_encode.h	C	F	block comments	TomYu
lib/krb5/asn.1/asn1_make.h	C	F	block comments	TomYu
lib/krb5/asn.1/asn1buf.h	C	F	block comments	TomYu
lib/krb5/asn.1/krb5_decode.c	C	F	block comments	TomYu

Exclusions to keep

BSD-marked exclusions to keep ($(BSDFILES))

directory or file name	P/C	why?	who?	comments
kadmin/cli/strftime.c	C	BSD	TomYu
kadmin/server/ipropd_svc.c	C	rpcgen	TomYu
kadmin/server/kadm_rpc_svc.c	C	rpcgen	TomYu
lib/kadm5/admin_xdr.h	C	rpcgen	TomYu
lib/kadm5/clnt/client_rpc.c	C	rpcgen	TomYu
lib/kadm5/kadm_rpc.h	C	rpcgen	TomYu
lib/kadm5/kadm_rpc_xdr.c	C	rpcgen	TomYu
lib/kadm5/srv/adb_xdr.c	C	rpcgen	TomYu
lib/krb5/krb/strftime.c	C	BSD	TomYu
lib/krb5/krb/strptime.c	C	BSD	TomYu
slave/kpropd_rpc.c	C	rpcgen	TomYu

other exclusions to keep ($(OTHEREXCLUDES))

directory or file name	P/C	why?	who?	comments
lib/krb5/krb/deltat.c	C	Bison	TomYu
lib/krb5/unicode	C	Unicode	TomYu