Change from upper-case SOME_FUNCTION_NAME() to lower-cases some_function_name()

[bartlettroscoe]

It seems the current CMake convention is to use lower case for CMake functions and local variables and upper case for global variables, built-in CMake variables, etc. Therefore, TriBITS should change this in all TriBITS code, examples, and documentation.

To make this change in all of TriBITS (including documentation and examples) the one could make make a script that looked for SOME_FUNC_NAME( and replaced it with some_func_name(. So we would provide a script called something like tribits_upper_to_lower_case_func_names.sh <file-name> and a driver script tribits_upper_to_lower_case_func_names_recurse.sh that would apply to files CMakeLists.txt, *.cmake to be safe. (Then you could apply manually to *.rst and other files if you like.) This would likely not be all that hard to do. But would would need to very carefully look at the changes to make sure that no changes that were not expected were made.

To not completely break branches of TriBITS, we would need to provide scripts to run on a given branch to update all of the names to match and then this should avoid conflicts.

Also, other TriBITS projects could use these scripts to update their CMake code and documentation.

[bartlettroscoe]

This was mentioned again in #337 (comment). I really should do this as part of the epic #367. I think I am going to write a tool to do this right after I merge the branch '63-merge-tpls-packages-1' for #63. That will make further refactoring nicer to do.

[bartlettroscoe]

@billhoffman, @bradking,

Do you know of a robust took that can convert CMake code to lower-case function, macro, and command names? That it, that can take CMake code like:

Set(SOME_VAR “”)

SET (someOtherVar “Value”)

MESSAGE(“My message”)

Message
    (“Some other message”)

MACRO(MACRO1)
ENDMACRO()

Function(
  Function1
  )

EndFunction
  ()

and likewise and only change the case of command, macro and functions names to all lower case like:

set(SOME_VAR “”)

set (someOtherVar “Value”)

message(“My message”)

message
    (“Some other message”)

macro(macro1)
endmacro()

function(
  function1
  )

endfunction
  ()

That is, I want to tool to change every name of a macro, function, and built-in CMake command to lower-case and don't get messed up by any crazy usage of horizontal or vertical whitespace or change whitespace in any way.

If such a robust tool does not exist, does someone at Kitware want to write one? A nice little Python script to do this would be great. (We can support this under the existing contract.)

[billhoffman]

I found this https://github.com/cheshirekow/cmake_format... I have also reached out to our EU office to see if they have something and they will get back to me.

[bartlettroscoe]

I found this https://github.com/cheshirekow/cmake_format

Thanks @billhoffman. Sadly, I don't seem to be able to use it. It requires pip to install it and I can't seem get pip installed on my RHEL7 machine (not sure if I can say more about that here). I really hate these Python packages that require special install processes.

[billhoffman]

I was able to run pip on my windows box and run it. It did not handle all of the cases. So, this might require some coding. But, I think it is something we can certainly look into implementing at Kitware if we don't find something that is already done.

[bartlettroscoe]

@billhoffman, it occurred to me that some specialized regexes with replacements in python might do the trick (a general command-call case, a macro definition case, and a function definition case). I may time-box a little effort to see what I can do with regex and replacements with Python.

[bartlettroscoe]

Okay, so I have a tool lower_case_cmake.py on the branch 274-lower-case-cmake that does the replacements shown above. But it is way too aggressive in its lower-casing of things. For example, it lower cases just pain text in comments like:

# EXEMPLARY, OR CONSEQUENTIAL [-DAMAGES-]{+damages+} (INCLUDING, BUT NOT LIMITED TO,

because it matches the command-call pattern <identifier> ( :-(

This is a huge problem as there is a lot of prose in CMake comments and *.rst files that have the pattern <identifier> ( that you don't want to lower-case.

I already had to put in special logic to avoid lower-casing logical operator names like in code:

  IF ( (VAR1) AND (VAR2) )

that otherwise becomes:

  if ( (VAR1) and (VAR2) )

which is invalid CMake code.

Note that I want to uniformly lower-case the command names in CMake code, CMake comments, and *.rst files. I need to employ a different strategy. What are the options?

Option-1: Create a tool that generates a huge list of possible command names that fit the pattern <identifier>[\s]*( that could be lower-cased from a bunch of files and sort and remove duplicates to create a master list. Then, I could manually remove the names from that list are not names that I want to lower-case. But it does have the advantage that it would be more robust and more predictable. Also, note that patterns like IF (, WHILE (, etc. are not very common in raw prose so doing lower-casing with short names like 'if' and 'while' with a ( after them should be fine (as long as you require the pattern match of <identifier> ( with zero or more whitespace separating <identifier> and (). But manually going over this list and deleting entries could be a lot of work.

Option-2: Update lower_case_cmake.py to be more specific for the coding style in TriBITS. That is, most commands are called as <command>( with no space between the <command> identifier and the opening (. But control constructs like if ( and foreach ( often use one or more spaces between the command identifier and the opening (. I also see people like putting a space between set and (. So that could be another special case to lower-case SET ( commands as well.

Option-3: Another option is to keep do what I am doing but to manually modify the places that need to be fixed that have lower-cased too much. But that is also a lot of manual work.

It seems like 'option-2' would be pretty robust and would involve the least manual work on modified files. If it missed some lower-casing on some rare cases, then who cares. You could manually fix those later as you see them. Given the need to lower-case any code on branches, it seems like this would be the winning option.

I will look at the matches in the various files some more and think about this some before deciding on my next step.

[bartlettroscoe]

I created PR #379 (which is now merged) that adds the tool lower_case_cmake.py and I ran it on all of TriBITS and manually fixed a few things. TriBITS is now using lower-case letters for all command, function, and macro calls. It also lower-cases the names of macro() and function() definitions. You can see the updated code under:

• https://github.com/TriBITSPub/TriBITS/

and the updated documentation at:

• https://tribits.org/doc/TribitsDevelopersGuide.html

[bartlettroscoe]

This has been in review for a long time. There were a few small issues that needed to get resolved like #402 and #383 but nothing else recently.

I think this is ready to close. That turned out to be a lot of work.

[bartlettroscoe]

I don't know why I did not close this. It should have been closed a long time ago.