[cmake-developers] target_link_libraries not callable from other directory scopes

[Craig Scott]

On Thu, Apr 26, 2018 at 4:22 AM, Patrick Stotko <
stotko at informatik.uni-bonn.de> wrote:

> Hi,
>
> this nice post (https://crascit.com/2016/01/3
> 1/enhanced-source-file-handling-with-target_sources/) mentions some
> modern usage of target_sources(), but also shows some discrepancy between
> target_link_libraries and the remaining target_* functions. In particlar,
> CMake does not allow linking to a target outside its creation scope whereas
> all the other ones do. There exists a workaround with include(), but it
> seems not the correct and clean way to handle this.
>
> So I think lifting this limitation would escepially help large-scale
> projects and improve modularization by handling third-party dependencies in
> the specific modules (as long as only this particular module needs it).
>
> So what is your experience regarding this linking restriction, especially
> in larger projects? I also opened an issue for this (see
> https://gitlab.kitware.com/cmake/cmake/issues/17943).
>
>
And from Brad's comment on that gitlab issue:

This limitation has been intentional since target_link_libraries was first
created long before the others. It is the oldest of the target_ commands.
The original justification is that we don't want to allow this because it
makes it very easy for non-local commands to drastically change the way a
target is built. That the newer target_ commands allow non-local targets
was an oversight.

Maybe the limitation could be lifted but I'd like to see a strong
justification and example use case.


Perhaps it was an oversight that newer target_... commands don't have the
same restriction as target_link_libraries(), but it is a very useful
oversight! As the linked blog article explains, it allows much better
modularity of the project. Extracting part of one of my comments on the
above-linked article:

For a real world example, consider a library or executable that has many
source files and where some functionality is optional and/or depends on the
availability of some external toolkit. Code related to such an optional
feature can be put in its own sub directory and conditionally included in
the library or executable. That sub directory can hold all the logic
related to that feature, including any external libraries that need to be
linked in. This is good modularisation since it localised the logic instead
of polluting the main CMakeLists.txt file.

It isn’t always possible or desirable to split out such an optional feature
to its own library (eg to ensure aspects of the implementation are not
revealed by exported symbol names or similar concerns). Thus, being able to
incorporate it directly into the main library or executable could be a
requirement. Being able to still isolate everything related to that feature
in its own sub directory can help keep things organised and easy to manage.


Being able to use add_subdirectory() instead of include() allows the
subdirectory to be more isolated, since any variables changed in the
subdirectory's scope won't affect the current scope. For new users,
add_subdirectory() also tends to feel more natural than include() and lead
to fewer errors. When using include(), you have to be very careful to use
CMAKE_CURRENT_LIST_DIR instead of CMAKE_CURRENT_SOURCE_DIR whenever you
need to construct an absolute path to something in the same (source)
directory, but new users often seem to not really know about
CMAKE_CURRENT_LIST_DIR. There's also no corresponding binary directory if
you use include(), unlike add_subdirectory() which nicely reproduces the
source directory structure in the build directory. Basically you can do
things with include() if you are careful, but add_subdirectory() is more
intuitive and more forgiving. The current restriction on
target_link_libraries() is the one hold-out for being able to make
subdirectories fully self-contained as far as building things goes.

Adding to the above quoted comment from the article, my experience on some
large projects has been that I can modularise optional parts of libraries
quite well using the various target_...() commands, but then I have to
duplicate some of the logic just because I still have to put the
target_link_libraries() call in the same directory as where the target is
defined. That's been a thorn in my side, because the modularity made
possible by target_sources() and the other target_...() commands have
otherwise allowed me to make the CMakeLists.txt files in each subdirectory
quite focused on just what that directory supplies. I found that using
include() instead of add_subdirectory() was confusing for some of our
users, so I tend to prefer to use add_subdirectory() and live with the
target_link_libraries() calls being leaked to the main directory, but I
would really love to avoid having to do that.

-- 
Craig Scott
Melbourne, Australia
https://crascit.com
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <https://cmake.org/pipermail/cmake-developers/attachments/20180427/eedab47f/attachment.html>