Skip to content

Build system rules for pretty-formatting C and Python code

Karl Wetterequested to merge
(removed):build-sys-pretty-code into master

Description

This MR adds build system rules for pretty-formatting C and Python code. No code is reformatted by default. Pretty-formatting is entirely opt-in, either on a per-file, per-directory, or per-LALSuite library basis.

Pretty-formatting only works in a Git checkout, and only processes files that have already been committed to Git. Hopefully that will mean that a user can always roll back to an un-pretty-formatted version of the code, in case the pretty-formatting causes problems during development.

C code is pretty-formatted using Artistic Style. This is a more modern C/C++ formatter than indent. I've often used it to tidy up my own code, and it seems reliable. It's available for RPMs, Debian, Ubuntu, Homebrew, MacPorts, etc. It supports lots of different options for formatting C/C++ in different styles.

  • Artistic Style options are given either in
    • A per source config file, e.g. lalpulsar/lib/.LatticeTiling.pretty.astylerc will apply to lalpulsar/lib/LatticeTiling.[ch]
    • A per directory config file, e.g. lalpulsar/bin/Weave/.pretty.astylerc will apply to everything in lalpulsar/bin/Weave/
    • A library top-level config file, e.g. lalpulsar/.pretty.astylerc, will apply to everything in LALPulsar

Python code is pretty-formatted using Black.

  • Black is enabled either
    • Per file, e.g. the presence of a file lalpulsar/python/lalpulsar/.simulateCW.pretty.black will reformat lalpulsar/python/lalpulsar/simulateCW.py
    • Per directory, e.g. the presence of a file lalpulsar/python/lalpulsar/.pretty.black will reformat everything in lalpulsar/python/lalpulsar
    • Per library, e.g. the presence of a file lalpulsar/.pretty.black will reformat everything in LALPulsar

Pretty-formatting is performed by running make pretty. A new CI job lint:pretty runs make pretty to check that code has been pretty-formatted before merging.

API Changes and Justification

Backwards Compatible Changes

  • This change does not modify any class/function/struct/type definitions in a public C header file or any Python class/function definitions
  • This change adds new classes/functions/structs/types to a public C header file or Python module

Backwards Incompatible Changes

  • This change modifies an existing class/function/struct/type definition in a public C header file or Python module
  • This change removes an existing class/function/struct/type from a public C header file or Python module

If any of the Backwards Incompatible check boxes are ticked please provide a justification why this change is necessary and why it needs to be done in a backwards incompatible way.

Review Status

Please provide details on any reviews related to this change and and the associated reviewers.

Edited by Karl Wette

Merge request reports