Re: [cmake-developers] Preferred case for macro names?

[Ben Boeckel]

On Tue, Nov 13, 2018 at 11:36:24 +0100, Eric Noulard wrote:
> > 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

Re: [cmake-developers] Preferred case for macro names?

[Ben Boeckel]

On Tue, Nov 13, 2018 at 06:11:26 -0500, David Cole via cmake-developers wrote:
> 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

Re: [cmake-developers] Preferred case for macro names?

[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.

On Tue, Nov 13, 2018 at 5:36 AM Eric Noulard  wrote:
>
>
>
> Le mar. 13 nov. 2018 à 10:41, Marc CHEVRIER  a écrit 
> :
>>
>> 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
>
> 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
-- 

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

Re: [cmake-developers] Preferred case for macro names?

[Eric Noulard]

Le mar. 13 nov. 2018 à 10:41, Marc CHEVRIER  a
écrit :

> 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

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

Re: [cmake-developers] Preferred case for macro names?

[Eric Noulard]

Le mar. 13 nov. 2018 à 00:21, Craig Scott  a
écrit :

>
>
> On Tue, Nov 13, 2018 at 9:51 AM Joachim Wuttke 
> wrote:
>
>> 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).
>
> 
> 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.
> 
>

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.


-- 
Eric
-- 

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

Re: [cmake-developers] Preferred case for macro names?

[Craig Scott]

On Tue, Nov 13, 2018 at 9:51 AM Joachim Wuttke 
wrote:

> 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).


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.



>
> 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?
>

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.


-- 
Craig Scott
Melbourne, Australia
https://crascit.com

New book released: Professional CMake: A Practical Guide

-- 

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