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?
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.
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...
Related
When I see CMake libraries with namespaces they are always in the form
Parent::Component.
If I have a sufficiently large library, there may be subsections of that library that have components. I am wondering if it is possible/appropriate to do something like ParentProject::Subgouping::SpecificComponent or for a more real world example Raytracing::Math::Utils.
In short, can I use multiple namespaces in a CMake library name? If it is possible, is it a good idea?
In short, can I use multiple namespaces in a CMake library name?
Yes. A colon (:) is just like any other character in a CMake target name. However, the target_link_libraries command will interpret any argument containing :: in its name as a proper CMake target, rather than as a potential system library. So if you mis-type a target name or it otherwise doesn't exist, you'll get a useful error at configure time, rather than a broken build.
Having multiple instances of :: in the name behaves the same as having just one.
If it is possible, is it a good idea?
It's about as good an idea as nested namespaces are in C++. If it makes sense, do it. The only minor difference is that CMake has no using namespace equivalent, so they're slightly less convenient to type.
In several of my projects, I use a namespace like Project::Tools:: to hold any build-time tools (like custom code generators) that need to be built separately for the sake of cross-compilation (when CMAKE_CROSSCOMPILING_EMULATOR is not an option).
In our project we are setting CMAKE_SYSROOT depending on the selected configuration. It is so because configuration expresses (amongst others) target platform (cross-compilation - but not only, also slight behavior differences).
We would like to express this with generator expression to be friendly towards multi-configuration IDEs.
However, we haven't found a way to do so. First, you will notice that CMAKE_SYSROOT doesn't even mention such a possibility. We still tried to set it to something like this (not exact value - just a sample!):
set(CMAKE_SYSROOT $<IF:$<CONFIG:hw1>,path1,path2>)
hoping that the value is used in a context where generator expressions are supported. But apparently, it is not. Instead, it seems that the verbatim value is provided in --sysroot argument (--sysroot="\$<IF:\$<CONFIG:hw1>,path1,path2>"). Adding quotes around the value doesn't change anything.
What other options do we have?
Let me also add a note on the CMAKE_TOOLCHAIN_FILE which is mentioned in the documentation of CMAKE_SYSROOT.
I don't see the CMAKE_TOOLCHAIN_FILE being set to anything after grep-ing through files generated by cmake -DCMAKE_BUILD_TYPE=hw1 ../ and our own sources.
Apparently, the file where we set the CMAKE_SYSROOT is not pointed to by CMAKE_TOOLCHAIN_FILE. Yet, still, the --sysroot argument is being set to the expected value. (Only not by generator expression!) So, it does work somehow.
I expect we will have the same issue with other variables as well:
CMAKE_SYSTEM_NAME,
CMAKE_SYSTEM_PROCESSOR,
CMAKE_CXX_COMPILER,
CMAKE_C_COMPILER
the last two depend on the CMAKE_SYSROOT anyway (in our case).
If you really want to pass different --sysroot flags to the linker on a multi-configuration generator you'll just have to pass it via target_link_options using a generator expression. But then you might have to update rpath items yourself, but I'm not sure about that.
Variables are not used at build time and the documentation for generator expressions state:
Generator expressions are allowed in the context of many target properties...
I didn't see anything in the set command that prevents CMAKE_SYSROOT being set outside a tool-chain file. I'm guessing that the phrase This variable may only be set in a toolchain file should be This variable is normally used in a toolchain file.
It almost seems like that you are trying to use build type as a switch between two different tool chains. If that is the case then I don't see how that could work correctly with a multi-configuration generator. Most of everything you want to set is determined and used at configuration time not build time.
What is the best way to do additional stuff for all (binary) targets?
Examples:
I want to check that each library name follows a pattern.
I want to sign each executable.
I dont what the C/C++ developers to use nonstandard commands (like add_library2). I want them to use and learn the official CMake functions, but have them do additonal, project specific, stuff.
The built-in CMake functions add_library and add_executable can be overidden by defining CMake functions of the same name. E.g., to automatically sign all added executables add the following code:
function (add_executable _name)
_add_executable(${ARGV})
if (TARGET ${_name})
add_custom_command(TARGET ${_name} POST_BUILD
COMMAND sign_executable $<TARGET_FILE:${_name}>)
endif()
endfunction()
The original built-in add_executable can be invoked by prefixing it with an underscore character. The same pattern can be applied to add_library to check the name of the library.
You can overwrite any CMake command/function to extend its functionality, but please
Call Things by their Names
I strongly advocate to call the things by their names and not doing things implicitly. It will be easier for everybody using/maintaining/debugging your CMake based project.
If you want to sign your executable - and that's probably even platform specific - you create a function like add_post_build_step_sign_executable() which would add the appropriate post build steps:
add_executable(MyExe main.cpp)
if (WIN32)
add_post_build_step_sign_executable(MyExe)
endif()
And if you have to repeat yourself too often put that code snippet into a function like my_project_add_signed_executable() itself. It could still have the same parameter syntax as CMake's add_executable() command.
Runtime Checks vs. Static Code Analysis
Regarding library naming checks, I see this more like checking against your project's CMake script coding styles and would not use runtime checks for this.
For example you could use something like cmake-lint or your own external script to check for conformity.
References
How to frame the concept behind CMake?
cmake: get add_library() names
How to ensure consistent coding style for CMakeLists.txt and FindXXX.cmake
Everything is in the title, but for more context informations:
I am creating a library, where all components are independent (it's only because it's easier to manage 1 git repo, really).
In that library's root folder, I have 1 sub-folder for each part of the library's components, with exactly 3 "interesting folders" (src,tests,include/components_name). I have hardcoded those folders in a foreach loop so that all actions will be done for all modules by default.
The problem seems to be that, one of the modules is named "option_parser" which is, indeed, relatively generic, and also seems to be "reserved" by cmake, and same for everything derived from it. I've tried "option_parser_test", "option_parser_tests", and other random names based on "option_parser_" root.
So, here is my question: where I can learn how to avoid names that cmake reserves?
And how can I affect them anyway to my binaries (because, I feel like it's stupid to change a project's name because of a build system. Might be a strong enough reason to switch it.)
It's really quite simple. Use these three commands to see all reserved words:
cmake --help-command-list
cmake --help-variable-list
cmake --help-property-list
The answer of Cinder Biscuits above should probably already help you.
Additionally, you should probably read CMake's own documentation regarding the CMake language and in particular the note in the "Variables" section:
Note: CMake reserves identifiers that:
begin with CMAKE_ (upper-, lower-, or mixed-case), or
begin with _CMAKE_ (upper-, lower-, or mixed-case), or
begin with _ followed by the name of any CMake Command.
When setting link libraries in the following manner
target_link_libraries (SOME_TARGET -L/somedir -lfoo)
cmake doesn't handle RPATHs. Is using '-L' and '-l' not best practice, or actually plain wrong? When creating my own Find*.cmake I usually use find_library() but the find script I got doesn't do this and resorts to the above form using '-L' and '-l'.
The documentation doesn't really explain how RPATHs are gathered, also the documentation isn't really clear how it handles "-l" and "-L" the only pointer you get is
"Item names starting with -, but not -l or -framework, are treated as
linker flags"
Specifying toolchain-dependent flags like -l and -L is generally not recommended, as it breaks portability and might have different effects than you expect.
The correct way to set the linker path would be the link_directories command.
The idiomatic solution in CMake is to use find_library for locating the library and then pass the full path to the linker, so you do not need to worry about link directories at all.
Now, the RPATH is a different beast, as it also determines where dynamic libraries can be located at runtime. Usually, the default settings work reasonably fine here. If you ever find yourself in the unfortunate situation where it does not, there is a number of target properties and CMake variables influencing this:
There are a few properties used to specify RPATH rules. INSTALL_RPATH
is a semicolon-separated list specifying the rpath to use in installed
targets (for platforms that support it). INSTALL_RPATH_USE_LINK_PATH
is a boolean that if set to true will append directories in the linker
search path and outside the project to the INSTALL_RPATH.
SKIP_BUILD_RPATH is a boolean specifying whether to skip automatic
generation of an rpath allowing the target to run from the build tree.
BUILD_WITH_INSTALL_RPATH is a boolean specifying whether to link the
target in the build tree with the INSTALL_RPATH. This takes precedence
over SKIP_BUILD_RPATH and avoids the need for relinking before
installation. INSTALL_NAME_DIR is a string specifying the directory
portion of the “install_name” field of shared libraries on Mac OSX to
use in the installed targets. When the target is created the values of
the variables CMAKE_INSTALL_RPATH, CMAKE_INSTALL_RPATH_USE_LINK_PATH,
CMAKE_SKIP_BUILD_RPATH, CMAKE_BUILD_WITH_INSTALL_RPATH, and
CMAKE_INSTALL_NAME_DIR are used to initialize these properties.
(From the set_target_properties docs)
Also, you might want to have a look at the CMake Wiki page for RPATH handling.
The whole RPATH business is unfortunately rather complex and a thorough explanation would require far more space than is appropriate for a StackOverflow answer, but I hope this is enough to get you started.
Basically, You're using target_link_libraries() wrong. According to documentation, You should provide target, libraries and maybe some CMake specific linkage flags.
For example something like that:
target_link_libraries(my_build_target somedir/foo.so)
If You're using Your own crafted Find*.cmake solutions, it's usualy being done like this:
find_library(foo)
//build main target somewhere here
//now link it:
target_link_libraries(my_build_target ${FOO_LIBRARIES})
NOTE: I assume Your crafted Find*.cmake files follows these guidelines and fills CMake variables like SOMELIB_LIBRARIES, and/or SOMELIB_INCLUDE_DIRS, etc.
NOTE2: for my personal opinion, target_link_directories() is pain in a butt and You should avoid using it if not really needed. It's difficult to maintain and uses paths relative to current source directory.