Style format templates

[LecrisUT]

I want to suggest to bundle a few common templates of styles for the user to choose from. There are still a few missing logic in order to implement all, but I hope it is helpful to have them all in one place for quick referencing. Please comment with any related issues to append to each style so they are easier to close in PRs.

Hopefully the example bellow can cover most style differences, but I will try to update it with other comments. I will explicitly not cover a few items:

• Dangling parenthesis
• Space between conditional and/or function paranthesis
• Reordering of the arguments

Example of unparsed CMakeLists.txt

#! Some random copyright text format
#! just ignore this
project(my_project VERSION 1.0.1 URL https://myproject.com DESCRIPTION "Imagine a long description here" LANGUAGES C CXX Fortran CUDA)

######
# Stylized_banner #
###

## This maybe a header
# This is a text help
# that spans multiple lines
set(my_variable "Default value" CACHE STRING "This is a long helper text" FORCE)
option(my_option "Helper text that for some reason is too long" OFF)

add_library(some_library STATIC src1.c src3.c src2.c)
add_library(other_library SHARED)
add_library(my_project::some_library ALIAS some_library)
target_sources(other_library PRIVATE src1.c src3.c src2.c)

message(WARNING "Again imagine a very long text over here")

add_custom_target(custom_target COMMAND /path/to/bin --flags --option ${my_variable} COMMENT "Some random comment about life the universe and everything")

# cmake-format: horizontal
add_subdirectories(dir1 dir2 dir3 dir4)

if(my_var OR my_var OR my_var OR and_so_on_until_linebreak)
endif()

---

Style 1: Oops all-vertical

This is mostly the current default one, but taken to a more extreme in some places.

Example of parsed CMakeLists.txt

#! Some random copyright text format
#! just ignore this
project(
    my_project
    VERSION 1.0.1
    URL https://myproject.com
    DESCRIPTION "Imagine a long \
    description here"
    LANGUAGES C CXX Fortran CUDA)

###################
# Stylized_banner #
###################

## This maybe a header
# This is a text help that spans multiple lines
set(
    my_variable
    "Default value"
    CACHE STRING
    "This is a long \
    helper text"
    FORCE)
option(
    my_option
    "Helper text that for some \
    reason is too long"
    OFF)

add_library(
    some_library STATIC
    src1.c
    src3.c
    src2.c)
add_library(other_library SHARED)
add_library(my_project::some_library ALIAS some_library)
target_sources(
    other_library
    PRIVATE
    src1.c
    src3.c
    src2.c)

message(
    WARNING
    "Again imagine a very \
    long text over here")

add_custom_target(
    custom_target
    COMMAND /path/to/bin --flags
    --option ${my_variable}
    COMMENT "Some random comment about \
    life the universe and everything")

# cmake-format: horizontal
add_subdirectories(dir1 dir2
    dir3 dir4)

if(my_var
    OR my_var
    OR my_var
    OR and_so_on_until_linebreak)
endif()

The issue I have with this one is that it tends to be too "consistent" in the rules. E.g. if commands are nicer in horizontal mode, but some people might prefer the consistency. Then people can tweak it based on this rule for individual commands

Style 2: All horizontal

This is exaggerated in places again to emphasize the difference

Example of parsed CMakeLists.txt

#! Some random copyright text format
#! just ignore this
project(my_project VERSION 1.0.1 URL https://myproject.com DESCRIPTION "Imagine a long \
    description here" LANGUAGES C CXX Fortran CUDA)

###################
# Stylized_banner #
###################

## This maybe a header
# This is a text help that spans multiple lines
set(my_variable "Default value" CACHE STRING "This is a long \
    helper text" FORCE)
option(my_option "Helper text that for some \
    reason is too long" OFF)

add_library(some_library STATIC src1.c
    src3.c src2.c)
add_library(other_library SHARED)
add_library(my_project::some_library ALIAS some_library)
target_sources(other_library PRIVATE src1.c
    src3.c src2.c)

message(WARNING "Again imagine a very \
    long text over here")

add_custom_target(custom_target COMMAND /path/to/bin --flags
    --option ${my_variable} COMMENT "Some random comment about \
    life the universe and everything")

# cmake-format: horizontal
add_subdirectories(dir1 dir2
    dir3 dir4)

if(my_var OR my_var OR my_var 
    OR and_so_on_until_linebreak)
endif()

Realistically this is mostly for a base if people want the exact opposite of the former style.

Style 3: Nested/Mixed

This is in principle what we are trying to obtain, a the cost of consistency. Here we are basically defining each built-in functions to sensible formats. Note that these rules are not actually implemented, just a wish list of how to view a good form

Example of parsed CMakeLists.txt

#! Some random copyright text format
#! just ignore this
project(my_project VERSION 1.0.1
    URL https://myproject.com
    DESCRIPTION "Imagine a long \
    description here"
    LANGUAGES C CXX Fortran CUDA)

###################
# Stylized_banner #
###################

## This maybe a header
# This is a text help that spans multiple lines
set(my_variable "Default value"
    CACHE STRING "This is a long \
    helper text"
    FORCE)
option(my_option "Helper text that for some \
    reason is too long" OFF)

add_library(some_library STATIC
    src1.c
    src3.c
    src2.c)
add_library(other_library SHARED)
add_library(my_project::some_library ALIAS some_library)
target_sources(other_library PRIVATE
    src1.c
    src3.c
    src2.c)

message(WARNING "Again imagine a very \
    long text over here")

add_custom_target(custom_target
    COMMAND /path/to/bin
    --flags --option ${my_variable}
    COMMENT "Some random comment about \
    life the universe and everything")

# cmake-format: horizontal
add_subdirectories(dir1 dir2
    dir3 dir4)

if(my_var OR my_var OR my_var 
    OR and_so_on_until_linebreak)
endif()

Style 4: IDE preferred

This one is a bit trickier to define since the IDEs usually decide on a specific format based on how you initially split it, e.g. if you made it vertical at the beginning. This should not be adapted, since the goal of this is to make a consistent format. However, there are a few minor style notes to adapt like the ones mentioned initially (dangling parenthesis, tab aliment, etc.).

So for this, it should be an addition on top of the previous style templates to define the minor style points. For example if built on top of the previous nested form with different alignment logic.

Example of parsed CMakeLists.txt

#! Some random copyright text format
#! just ignore this
project(my_project VERSION 1.0.1
    URL https://myproject.com
    DESCRIPTION "Imagine a long \
                 description here"
    LANGUAGES C CXX Fortran CUDA)

###################
# Stylized_banner #
###################

## This maybe a header
# This is a text help that spans multiple lines
set(my_variable "Default value"
    CACHE STRING "This is a long \
                  helper text"
    FORCE)
option(my_option "Helper text that for some \
    reason is too long" OFF)

add_library(some_library STATIC
    src1.c
    src3.c
    src2.c)
add_library(other_library SHARED)
add_library(my_project::some_library ALIAS some_library)
target_sources(other_library PRIVATE
    src1.c
    src3.c
    src2.c)

message(WARNING "Again imagine a very \
                 long text over here")

add_custom_target(custom_target
    COMMAND /path/to/bin
            --flags --option ${my_variable}
    COMMENT "Some random comment about \
            life the universe and everything")

# cmake-format: horizontal
add_subdirectories(dir1 dir2
    dir3 dir4)

if (my_var OR my_var OR my_var 
    OR and_so_on_until_linebreak)
endif ()

---

Missing features

• Base templates to choose and expand
• First argument(s) are allowed on same line. Also the first keyword if wanted (Choose vertical/horizontal wrapping based on line length #293, Positional argument formatting #283)
• Mixed alignment tabs and filling spaces. (e.g. in style 4 project(), there is a single tab before DESCRIPTION and the next line is a tab and 12 filling spaces)
• Split long text in multiple lines
• More specific formatting options for if(), add_custom_target(), message(), set(CACHE), project() (Request: Add ability to blacklist line breaks after certain words #301, Never consider vertical layout if a command can be put in one line #309, Choose vertical/horizontal wrapping based on line length #293)
• Define single-line header comments (e.g. ##)
• Format banners
• Individual switching of format style/options (Option to disable wrapping #294)

[sizeak]

I would very much like the target names to stay on the first line!