[cmake-developers] Preferred case for macro names?

[Joachim Wuttke]

My understanding was that prevalent usage in modern CMake
is all lowercase for function names, all uppercase for
macro names. In this sense, I submitted a number of merge
requests where function and macro names are normalized, and
in
https://gitlab.kitware.com/cmake/cmake/merge_requests/2607
I suggest an explicit recommendation in the macro and
function doc pages.

Now I am learning from Craig Scott that the more recent
convention is actually all lowercase for macros as well
as for functions.

Thus two requests for comments:

- Shall the reference manual give a clear recommendation
on preferred case, to stear the community away from the
inherited anarchy?

- Macro names all uppercase or all uppercase?

/Joachim

[Craig Scott]

Post by Joachim Wuttke
My understanding was that prevalent usage in modern CMake
is all lowercase for function names, all uppercase for
macro names. In this sense, I submitted a number of merge
requests where function and macro names are normalized, and
in
https://gitlab.kitware.com/cmake/cmake/merge_requests/2607
I suggest an explicit recommendation in the macro and
function doc pages.
Now I am learning from Craig Scott that the more recent
convention is actually all lowercase for macros as well
as for functions.

To be clear, my understanding is that in the past (many years ago),
uppercase tended to be common, but I don't see that used much these days
for functions, macros or built-in commands. The general sentiment seems to
be that uppercase tends to be a bit "shouty" now. I'm suggesting that if
we're going to bring some consistency to the docs, I propose that we just
go with lowercase everywhere (functions, macros, built-in commands and
examples).

<nit-filter ON>
Regarding the finer points of macros versus functions versus built-in
commands and establishing a convention, it's actually a bit difficult to
draw a hard line in behaviour across all three. Consider commands like
find_package() and project(). These are built-in commands, but they behave
like a macros in that they add variables to the calling scope (yes,
functions can do that too, but the primary reason to use macros is to
inject variables into the calling scope). Most built-in commands act more
like functions and do not modify the calling scope. Trying to decide
whether built-in commands act like macros and which do not and making them
upper or lowercase based on that is unlikely to be a distinction that most
users would make, so a mix of upper and lowercase for built-in commands
would be unexpected. A consequence of this is that having macros and
functions with differing case conventions would seem to create a potential
inconsistency with whatever convention is used for built-in commands. The
only way to really have consistency here would seem to be just use the one
case convention, for which lowercase seems to be the logical and
increasingly prevalent choice.
<nit-filter OFF>

Post by Joachim Wuttke
- Shall the reference manual give a clear recommendation
on preferred case, to stear the community away from the
inherited anarchy?

The docs can be consistent throughout, but matters of style are ultimately
up to individual projects and their own coding conventions. Over time,
making the CMake docs present a consistent style will likely encourage
projects that don't have a convention of their own to adopt that style out
of familiarity.

[Eric Noulard]

Post by Craig Scott

Post by Joachim Wuttke
My understanding was that prevalent usage in modern CMake
is all lowercase for function names, all uppercase for
macro names. In this sense, I submitted a number of merge
requests where function and macro names are normalized, and
in
https://gitlab.kitware.com/cmake/cmake/merge_requests/2607
I suggest an explicit recommendation in the macro and
function doc pages.
Now I am learning from Craig Scott that the more recent
convention is actually all lowercase for macros as well
as for functions.

To be clear, my understanding is that in the past (many years ago),
uppercase tended to be common, but I don't see that used much these days
for functions, macros or built-in commands. The general sentiment seems to
be that uppercase tends to be a bit "shouty" now. I'm suggesting that if
we're going to bring some consistency to the docs, I propose that we just
go with lowercase everywhere (functions, macros, built-in commands and
examples).
<nit-filter ON>
Regarding the finer points of macros versus functions versus built-in
commands and establishing a convention, it's actually a bit difficult to
draw a hard line in behaviour across all three. Consider commands like
find_package() and project(). These are built-in commands, but they behave
like a macros in that they add variables to the calling scope (yes,
functions can do that too, but the primary reason to use macros is to
inject variables into the calling scope). Most built-in commands act more
like functions and do not modify the calling scope. Trying to decide
whether built-in commands act like macros and which do not and making them
upper or lowercase based on that is unlikely to be a distinction that most
users would make, so a mix of upper and lowercase for built-in commands
would be unexpected. A consequence of this is that having macros and
functions with differing case conventions would seem to create a potential
inconsistency with whatever convention is used for built-in commands. The
only way to really have consistency here would seem to be just use the one
case convention, for which lowercase seems to be the logical and
increasingly prevalent choice.
<nit-filter OFF>

I would add that sometimes useful macro/function may become builtin
See example for include_guard in
https://github.com/dev-cafe/cmake-cookbook/blob/master/chapter-07/recipe-06/example/CMakeLists.txt

So differentiating macro/function/builtin by their case does not seems a
good option to me.
My personal opinion though.

+1 for lower case for every function, macro or builtin.
macro or function OPTION are UPPERCASE
properties are UPPERCASE as well
and I personnally tend to define CMake VARIABLES as uppercase too.

[Marc CHEVRIER]

This post might be inappropriate. Click to display it.

[Eric Noulard]

Post by Marc CHEVRIER
I agree as well that trying to distinguish macros from functions is not a
good idea because functions can act in the same way as macros (i.e.
changing calling environment) but with a better control over environment
changes (changes are done explicitly by using 'set(... PARENT_SCOPE)').
so also +1 for lower case for every function, macro or builtin. And good
point to standardize macro or function OPTION to UPPERCASE.
Now, for variables, the problem is a bit different because they are case
sensitive: 'set(my_var ...)' and 'set (MY_VAR ...)' will create two
different variables.

Yes damn right.

Post by Marc CHEVRIER
My personal tendency is to use lower case for local variables and upper
case for global variables. May be we can normalize variables to upper case
regarding global variables used by CMake itself (which is globally the
current rule).

Having a convention for local is nice and I tend to prefix with _ (single
or double) variables that should be local.
lowercasing locals is fine too, however I think that enforcing casing on
"user-defined" variable may not be desirable, concerning CMAKE_ CTEST_ and
CPACK_
I guess they already are all UPPERCASE so we may stick with this as a
convention?

A small quote to the cmake-format (
https://github.com/cheshirekow/cmake_format) tool which is trying to
beautify CMakeLists.txt, I'm not using it on complex projects
because it still has some issues but I find it otherwise useful.

[David Cole via cmake-developers]

I would just like to point out that some modules (ExternalData,
ExternalProject, to name two specific examples) adopted the convention
to prefix all their provided function names with the module name and
an underscore: for example, ExternalProject_Add and
ExternalData_Expand_Arguments.

These functions adopt a mixed-case function naming convention, since
the module name is mixed case, and since module names are file names,
and some file systems have case sensitive file names ...... they
should stay that way regardless of any convention you may like to try
to adopt elsewhere.


David C.

Post by Eric Noulard

I agree as well that trying to distinguish macros from functions is not a good idea because functions can act in the same way as macros (i.e. changing calling environment) but with a better control over environment changes (changes are done explicitly by using 'set(... PARENT_SCOPE)').
so also +1 for lower case for every function, macro or builtin. And good point to standardize macro or function OPTION to UPPERCASE.
Now, for variables, the problem is a bit different because they are case sensitive: 'set(my_var ...)' and 'set (MY_VAR ...)' will create two different variables.

Yes damn right.

My personal tendency is to use lower case for local variables and upper case for global variables. May be we can normalize variables to upper case regarding global variables used by CMake itself (which is globally the current rule).

Having a convention for local is nice and I tend to prefix with _ (single or double) variables that should be local.
lowercasing locals is fine too, however I think that enforcing casing on "user-defined" variable may not be desirable, concerning CMAKE_ CTEST_ and CPACK_
I guess they already are all UPPERCASE so we may stick with this as a convention?
A small quote to the cmake-format (https://github.com/cheshirekow/cmake_format) tool which is trying to beautify CMakeLists.txt, I'm not using it on complex projects
because it still has some issues but I find it otherwise useful.
--
Eric
--
Powered by www.kitware.com
Please keep messages on-topic and check the CMake FAQ at: http://www.cmake.org/Wiki/CMake_FAQ
CMake Support: http://cmake.org/cmake/help/support.html
CMake Consulting: http://cmake.org/cmake/help/consulting.html
CMake Training Courses: http://cmake.org/cmake/help/training.html
Visit other Kitware open-source projects at http://www.kitware.com/opensource/opensource.html
https://cmake.org/mailman/listinfo/cmake-developers

--
Powered by www.kitware.com

Please keep messages on-topic and check the CMake FAQ at: http://www.cmake.org/Wiki/CMake_FAQ

Kitware offers various services to support the CMake community. For more information on each offering, please visit:

CMake Support: http://cmake.org/cmake/help/support.html
CMake Consulting: http://cmake.org/cmake/help/consulting.html
CMake Training Courses: http://cmake.org/cmake/help/training.html

Visit other Kitware open-source projects at http://www.kitware.com/opensource/opensource.html

Follow this link to subscribe/unsubscribe:
https://cmake.org/ma

[Ben Boeckel]

Post by David Cole via cmake-developers
I would just like to point out that some modules (ExternalData,
ExternalProject, to name two specific examples) adopted the convention
to prefix all their provided function names with the module name and
an underscore: for example, ExternalProject_Add and
ExternalData_Expand_Arguments.
These functions adopt a mixed-case function naming convention, since
the module name is mixed case, and since module names are file names,
and some file systems have case sensitive file names ...... they
should stay that way regardless of any convention you may like to try
to adopt elsewhere.

Agreed. I use lower case everywhere I can, but externalproject_add just
looks worse than ExternalProject_add (though I'd really prefer
external_project_add, that ship sailed long ago).

--Ben
--
Powered by www.kitware.com

Please keep messages on-topic and check the CMake FAQ at: http://www.cmake.org/Wiki/CMake_FAQ

Kitware offers various services to support the CMake community. For more information on each offering, please visit:

CMake Support: http://cmake.org/cmake/help/support.html
CMake Consulting: http://cmake.org/cmake/help/consulting.html
CMake Training Courses: http://cmake.org/cmake/help/training.html

Visit other Kitware open-source projects at http://www.kitware.com/opensource/opensource.html

Follow this link to subscribe/unsubscribe:
https://cmake.org/mailman/listinfo/cmake-developers

[Ben Boeckel]

Post by Eric Noulard

Post by Marc CHEVRIER
My personal tendency is to use lower case for local variables and upper
case for global variables. May be we can normalize variables to upper case
regarding global variables used by CMake itself (which is globally the
current rule).

Having a convention for local is nice and I tend to prefix with _ (single
or double) variables that should be local.
lowercasing locals is fine too, however I think that enforcing casing on
"user-defined" variable may not be desirable, concerning CMAKE_ CTEST_ and
CPACK_
I guess they already are all UPPERCASE so we may stick with this as a
convention?

My personal style is to use lowercase for derived or internal variables
(and properties). Uppercase is left for environment (e.g., CMake) or
user variables. Note that CMake also defines some un-namespaced
variables including:

- BUILD_SHARED_LIBS
- BUILD_TESTING
- many CTest variables (*_COMMAND, DART_TESTING_TIMEOUT, etc.)

--Ben
--
Powered by www.kitware.com

Please keep messages on-topic and check the CMake FAQ at: http://www.cmake.org/Wiki/CMake_FAQ

Kitware offers various services to support the CMake community. For more information on each offering, please visit:

CMake Support: http://cmake.org/cmake/help/support.html
CMake Consulting: http://cmake.org/cmake/help/consulting.html
CMake Training Courses: http://cmake.org/cmake/help/training.html

Visit other Kitware open-source projects at http://www.kitware.com/opensource/opensource.html

Follow this link to subscribe/unsubscribe:
https://cmake.org/mailman/listinfo/cmake-developers