Modern editors provide plenty of ways to visually separate functions.
Drop the explicit comments that previously served this purpose.
Use the following command to automate the change:

    $ git ls-files -z -- \
        "*.c" "*.cc" "*.cpp" "*.cxx" "*.h" "*.hh" "*.hpp" "*.hxx" |
      egrep -z -v "^Source/cmCommandArgumentLexer\." |
      egrep -z -v "^Source/cmCommandArgumentParser(\.y|\.cxx|Tokens\.h)" |
      egrep -z -v "^Source/cmDependsJavaLexer\." |
      egrep -z -v "^Source/cmDependsJavaParser(\.y|\.cxx|Tokens\.h)" |
      egrep -z -v "^Source/cmExprLexer\." |
      egrep -z -v "^Source/cmExprParser(\.y|\.cxx|Tokens\.h)" |
      egrep -z -v "^Source/cmFortranLexer\." |
      egrep -z -v "^Source/cmFortranParser(\.y|\.cxx|Tokens\.h)" |
      egrep -z -v "^Source/cmListFileLexer\." |
      egrep -z -v "^Source/cm_sha2" |
      egrep -z -v "^Source/(kwsys|CursesDialog/form)/" |
      egrep -z -v "^Utilities/(KW|cm).*/" |
      xargs -0 sed -i '/^\(\/\/---*\|\/\*---*\*\/\)$/ {d;}'

This avoids modifying third-party sources and generated sources.

Jean-Christophe Fillion-Robin authored May 04, 2016 and Brad King committed May 09, 2016

Teach the `add_custom_command` and `add_custom_target' commands to
substitute argv0 with the crosscompiling emulator if it is a target with
the `CROSSCOMPILING_EMULATOR` property set.

Add a long comment inside a few braced initializer lists in order to
convince clang-format to break after the opening brace and format the
list without indenting every value past the opening brace.

The clang-format tool may turn this:

   public: // comment about access specifier

     // unrelated comment indented with code
     ...

Into:

   public: // comment about access specifier

           // unrelated comment indented with code
     ...

Avoid this by moving comments off of access specifier lines.

The clang-format tool can do a good job formatting most code, but
well-organized streaming blocks are best left manually formatted.

Find blocks of the form

    os <<
      "...\n"
      "...\n"
      ;

using the command

    $ git ls-files -z -- Source |
      egrep -v -z '^Source/kwsys/' |
      xargs -0 pcregrep -M --color=always -B 1 -A 1 -n \
        '<<[^\n]*\n(^ *("[^\n]*("|<<|;)$|;)\n){2,}'

Find blocks of the form

    os << "...\n"
       << "...\n"
       << "...\n";

using the command

    $ git ls-files -z -- Source |
      egrep -v -z '^Source/kwsys/' |
      xargs -0 pcregrep -M --color=always -B 1 -A 1 -n \
        '<<[^\n]*\n(^ *<<[^\n]*(\\n"|<<|;)$\n){2,}'

Surround such blocks with the pair

    /* clang-format off */
    ...
    /* clang-format on */

in order to protect them from update by clang-format.  Use the C-style
`/*...*/` comments instead of C++-style `//...` comments in order to
prevent them from ever being swallowed by re-formatting of surrounding
comments.

geoffviola authored May 04, 2016 and Brad King committed May 06, 2016

Detect when the resulting object path is too long and compute an
alternative name using a hash.

Add missing unset of scratch variables to generated export file for case
that the file was already included. We already unset these when parsing
the file normally, but the multiple inclusion case was leaving them
around.

Re-apply the approach from commit e1c77472 (Format include directive
blocks and ordering with clang-format, 2016-04-29) but this time be
more careful about exclusion of parser generator sources:

    $ git ls-files -z -- \
        '*.c' '*.cc' '*.cpp' '*.cxx' '*.h' '*.hh' '*.hpp' '*.hxx' |
      egrep -z -v '^Source/cmCommandArgumentLexer\.' |
      egrep -z -v '^Source/cmCommandArgumentParser\.' |
      egrep -z -v '^Source/cmDependsJavaLexer\.' |
      egrep -z -v '^Source/cmDependsJavaParser\.' |
      egrep -z -v '^Source/cmExprLexer\.' |
      egrep -z -v '^Source/cmExprParser\.' |
      egrep -z -v '^Source/cmFortranLexer\.' |
      egrep -z -v '^Source/cmFortranParser\.' |
      egrep -z -v '^Source/cmListFileLexer\.' |
      egrep -z -v '^Source/cm_sha2' |
      egrep -z -v '^Source/(kwsys|CursesDialog/form)/' |
      egrep -z -v '^Utilities/(KW|cm).*/' |
      egrep -z -v '^Tests/Module/GenerateExportHeader' |
      egrep -z -v '^Tests/RunCMake/CommandLine/cmake_depends/test_UTF-16LE.h' |
      xargs -0 clang-format -i

Also drop use of custom sorting for `sys/types.h`.

When this header is included in blocks where order does not matter, just
place it in lexicographic order as clang-format would by default.

Include the two headers in an isolated block with a comment separating
them so that tools that re-order includes do not re-order these.

Sort include directives within each block (separated by a blank line) in
lexicographic order (except to prioritize `sys/types.h` first).  First
run `clang-format` with the config file:

    ---
    SortIncludes: false
    ...

Commit the result temporarily.  Then run `clang-format` again with:

    ---
    SortIncludes: true
    IncludeCategories:
      - Regex:    'sys/types.h'
        Priority: -1
    ...

Commit the result temporarily.  Start a new branch and cherry-pick the
second commit.  Manually resolve conflicts to preserve indentation of
re-ordered includes.  This cleans up the include ordering without
changing any other style.

Use the following command to run `clang-format`:

    $ git ls-files -z -- \
        '*.c' '*.cc' '*.cpp' '*.cxx' '*.h' '*.hh' '*.hpp' '*.hxx' |
      egrep -z -v '(Lexer|Parser|ParserHelper)\.' |
      egrep -z -v '^Source/cm_sha2' |
      egrep -z -v '^Source/(kwsys|CursesDialog/form)/' |
      egrep -z -v '...

Each source file has a logical first include file.  Include it in an
isolated block so that tools that sort includes do not move them.

Update documentation to mark the generator deprecated.  Add a warning at
the end of generation plus an option to turn off the warning.

Daniel Pfeifer authored Apr 28, 2016 and Brad King committed Apr 28, 2016

The tool expects the entire compiler command, including `cc`.  It
will automatically skip that and extract the options it needs.

Daniel Pfeifer authored Apr 26, 2016 and Brad King committed Apr 27, 2016

Clang-Tidy writes the number of warnings, the number of suppressed
warnings, and instructions on how to suppress warnings to stderr.  Since
each source file is checked individually, this repetitive information is
disturbing and should be suppressed.

The actual warning messages are written to stdout.  Some IDEs (eg.
QtCreator) analyze only stderr for issues.  Redirecting Clang-Tidy's
stdout to stderr makes sure the warnings are correctly displayed.

Solution folders are supported on VS 8 and above in the full versions
and on VS 11 and above in the express versions.

geoffviola authored Apr 24, 2016 and Brad King committed Apr 25, 2016

Green Hills MULTI project files must specify explicitly distinct object
file names for source files with the same name.

Sebastian Holtermann authored Apr 24, 2016 and Brad King committed Apr 25, 2016

To avoid Race conditions with other processes writing to stdout/stderr compose
the whole message in a std::stringstream then submit the single complete message.