logo_kerberos.gif

Difference between revisions of "Coding style/Reindenting"

From K5Wiki
Jump to: navigation, search
(Cleanup coordination: refine exclusions for lib/krb5/asn.1)
(update makefile variables)
Line 48: Line 48:
   
 
=== Makefile variables ===
 
=== Makefile variables ===
  +
  +
<code>$(INDENTDIRS)</code> sets the list of directories that the <code>make mark-cstyle</code> target will operate on.
   
 
<code>$(BSDFILES)</code> contains a list of files that the <code>make mark-cstyle</code> target will mark as BSD-style.
 
<code>$(BSDFILES)</code> contains a list of files that the <code>make mark-cstyle</code> target will mark as BSD-style.
Line 70: Line 72:
   
 
{| class="wikitable"
 
{| class="wikitable"
|+ directories included in find
+
|+ directories included in find (<code>$(INDENTDIRS)</code>)
 
|-
 
|-
 
! directory name
 
! directory name
Line 125: Line 127:
   
 
{| class="wikitable"
 
{| class="wikitable"
|+ exclusions to eval/fix
+
|+ exclusions to eval/fix (<code>$(BSDFILES)</code> or <code>$(OTHEREXCLUDES)</code>)
 
! directory or file name
 
! directory or file name
 
! P/C
 
! P/C
Line 149: Line 151:
   
 
{| class="wikitable"
 
{| class="wikitable"
|+ BSD-marked exclusions to keep
+
|+ BSD-marked exclusions to keep (<code>$(BSDFILES)</code>)
 
! directory or file name
 
! directory or file name
 
! P/C
 
! P/C
Line 178: Line 180:
   
 
{| class="wikitable"
 
{| class="wikitable"
|+ other exclusions to keep
+
|+ other exclusions to keep (<code>$(OTHEREXCLUDES)</code>)
 
! directory or file name
 
! directory or file name
 
! P/C
 
! P/C

Revision as of 14:57, 6 November 2009

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

Don't sign up here yet... still working on how best to set up the tables.

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