CMake function arguments -- why are they occasionally uppercase?

Question

I've been combing through the CMake documentation for a while now trying to figure out why some function arguments are capitalised and some aren't. I was hoping someone might be able to explain the pattern of things being capitalised, or at the very least point me in the direction of the documentation. This documentation https://cmake.org/cmake/help/v3.0/manual/cmake-language.7.html#cmake-language-7 gives very little in the way of explaining why certain things are capitalised.

From my current understanding, uppercase arguments can be:

• Keyword arguments of the function
• Flags
• Properties

Lowercase arguments are:

• Other types of inputs to the function

Here's an example of a CMake file which you can maybe help me dissect?

CMAKE_MINIMUM_REQUIRED(VERSION 2.8)

include(SomeLib)

include_directories(include)

add_library(mylib SHARED src/main.cpp)

target_link_libraries(mylib ${boost_LIBRARIES})

install(TARGETS mylib DESTINATION lib)

VERSION I'm guessing is a keyword, SHARED is probably also a keyword, or possibly a property, TARGETS and DESTINATION are also keywords?

Answer 1

There is no some accepted style for writing CMake code so you can encounter anything. What you usually see is a historical somewhat accepted style used by the devs (Kitware) which was adopted by many others.

Usually you use lower case for CMake command, macro and function names, so to correct your code you need to lower case for the version command: cmake_minimum_required(VERSION 2.8) because it is a command.

Some commands have named arguments, some not. Usually named arguments are in upper case. In your example TARGETS, VERSION, SHARED and DESTINATION are all named arguments (which CMake calls keywords). They can be of any case but we just used to make them uppercase. Such arguments got parsed with the cmake_parse_arguments help for functions & macros. Since all commands are implemented in C++ the argument parsing is done in C++ for them (probably with the same "command").

Apart from the command names, lower case might be used in functions for local variables but that's not established and you can find any kind of mixing in the wild.

Answer 2

This is an addon to @ixSci's answer.

Some history of CMake.

Look at this message from 2003 asking if there were plans to allow lowercase commands.

No plans on changing this.

Much has changed. Check out this commit from 9 years ago, which changed a bunch of existing code from uppercase to lowercase. Here's a quote:

Ancient CMake versions required upper-case commands. Later command names became case-insensitive. Now the preferred style is lower-case.

Nowadays, CMake commands are case-insensitive and remain backwards-compatible. However, CMake variables remain case-sensitive.

Further, CMake 2.6 introduced cmake_policy, which can be used to specify a specific syntax version. Maybe you're feeling nostalgic...