Hi Magnus,
great work!
I completely agree with all points and especially like the indentation
level of two spaces:)
Thanks,
Volker
On Tue, Oct 8, 2013 at 9:40 AM, Magnus Ihse Bursie
<magnus.ihse.bur...@oracle.com> wrote:
> Whitespace and indentation in makefiles is a more problematic area than for
> other languages. Even while most of the time whitespace is not significant,
> sometimes is is. This might be considered a design flaw in make, but that's
> not something we can do anything about. In particular, initial tabs signify
> make rule recipes, and in make string manipulation, sometimes spaces matter.
>
> Probably partly due to this, there is little editor/IDE/tooling support for
> automatically formatting makefiles. This in turns makes keeping sane
> whitespace usage and indentation a "manual" task. When we started writing
> the new build system, we didn't set up a set of coding conventions to
> regulate whitespace and indentation (which we regret now). So the existing
> code varies wildly in style and indentation. All too often, proper
> indentation is completely missing, making it hard to read and understand the
> code.
>
> So, we created a set of rules for indention and whitespace usage. We tried
> to stay close to the Java code conventions, but Makefiles are not Java
> source code. We have then started to transform the code base according to
> these conventions. A webrev will shortly follow, with the whitespace changes
> resulting from this work.
>
> But first, let us present the set of rules.
>
> Indentation:
> 1) The basic level of indentation is two spaces. Use this for "logical"
> indentation (if blocks, function definitions etc).
> 2) If a line must be broken, use four spaces for indentation.
> 3) Recipes in makefile rules must start with a tab (per definition).
> 4) If a single tab (interpreted as 8 spaces wide) is not enough to put the
> recipe clearly indented (meaning at least 4 spaces difference) from the code
> around it, use additional tabs.
> 5) Non-shell commands in a recipe (e.g. comments and make directives like
> ifdef) must not start with tab, but should instead be indented to the same
> level as the surrounding shell commands using spaces (with tabs interpreted
> as 8 spaces wide).
> 6) Additional indentation in recipes should be done using space after the
> tab(s), as in normal makefile lines.
> 7) Partial recipes (macro definitions that are supposed to be inlined into
> a recipe) should be treaded like a recipe and start with tabs as well.
>
> Whitespace, required:
> 8) Trailing whitespaces is never allowed.
> 9) Do not use tabs, only spaces (except for in recipes, as stated by rule
> 3-7).
>
> Whitespace, recommended:
> 10) There should be no whitespace between the list of targets and the : at
> the start of a rule.
> 11) There should be an empty line before and after each rule.
> 12) Avoid empty lines inside the recipe.
> 13) Broken lines should end with a backslash, and a single space before the
> backslash (" \").
> 14) A single space should separate a comma from the next argument in a
> function call.
> 15) A single space should be used before and after assignment operators
> (e.g. :=, =, +=).
> These recommendations are not always possible to follow, since whitespace
> might have semantic meaning. If an exception from these recommendations is
> required by make, it should ideally be pointed out by a comment. Especially
> spacing around commas might be sensitive, so beware.
>
> Style recommentations:
> 16) Use := (direct assignment) instead of = (recursive macro definition),
> unless you really need the recursive definition.
> 17) In long lists, do not let the first and last element have different
> form. For instance, start the first element on a new line rather than after
> a :=, and end the list with an empty comment (#) to be able to have a
> trailing backslash on the last line.
> 18) Avoid padding internally in a line with spaces to try to align some
> feature into columns with surrounding lines.
> 19) For multiple commands run by the shell, separated by "&& \" or similar,
> all commands should start at the same indention level.
>
> Rationales (to some of the rules):
> 1-2) This is in contrast to Java, which has twice as long indentations (4
> space logical indentation, 8 spaces for wrapped lines). But since all
> indentation needs to be done basically by repeatedly pressing space, and
> since wrapped lines are fairly common, we felt it important to keep the
> indentation level short. Otherwise a wrapped line two levels in would needed
> 16 presses on the space bar.
> 9-12) Tabs are required in recipes, but for the sake of sanity, this is the
> only accepted use of tabs. The makefile syntax does not make it easy to spot
> rules in complex makefiles, and everything that helps in distinguishing
> rules from non-rules is needed.
> 16) Recursive macro definition (= instead of :=) slows down make and can
> have surprising effects. Typically this is not what you mean.
> 17-18) A very typical use case of makefile changes is to add things (files,
> compiler directives, etc) to a list. These rules help making such changes
> easy and context free. Otherwise the developer must modify several lines
> that are unrelated to the actual change. Chances are that a nicely padded
> grid will not be updated and start deteriorating from the very first change.
> 19) Separating multiple shell commands (e.g. after a shell "if" command)
> should not be considered a broken line which needs to be indenting, but a
> way to specify a list of commands on the same indentation levels. This is
> after all the intent; the && is merely a roundabout device to get this to
> work properly in makefiles.
>
> /Magnus
