[CMake] link_libraries() deprecated. Why?

[Brad King]

Alex,

Looking at history I see this was deprecated by a patch you sent me.
Originally we called the command 'discouraged'.  Why did we change
to 'deprecated'?

Marcel Loose wrote:
> Thanks for your reply. Your solution is ok, but it looks a bit like a
> workaround for a feature that is missing, but was once there:
> link_libraries().
> 
> To me, it's not really clear why link_libraries() has been deprecated
> and, for example, include_directories() has not. IMHO, using
> target_link_libraries() for a general library has a too fine
> granularity. 
> Suppose include_directories() were deprecated as well in favour of, say,
> target_include_directories(). That would create the same problem: carry
> around variables holding a bunch of include directories that must be
> supplied to each target.
> 
> I don't like to use deprecated features, so I would love to see the
> deprecation of link_libraries() to be reverted. But maybe I'm missing a
> good reason for not doing so.

Marcel, feel free to use link_libraries if there is no better solution.
We do not plan to take it away.  The word 'deprecated' is too strong.

One difference between link_libraries and include_directories is that
library dependencies are chained automatically.  If you write

   add_library(mylib mylib.c)
   target_link_libraries(mylib m)
   add_executable(myexe myexe.c)
   target_link_libraries(myexe mylib)

then 'myexe' will link to both 'mylib' and 'm' (-lmylib -lm).
If you write

   link_libraries(m)
   add_library(mylib mylib.c)
   add_executable(myexe myexe.c)
   target_link_libraries(myexe mylib)

then 'myexe' will link 'm', 'mylib', and then 'm' again (-lm -lmylib -lm).
The reason is that the add_executable line copies the current set of
directory-level libraries from link_libraries when it is created.  Any
target_link_libraries after that are appended.  A strict rule our link
line generator follows is that the original link line for a target is
preserved, so for 'myexe' it starts with 'm' and 'mylib'.  Then it sees
that 'mylib' depends on 'm' and appends the library to the final link line.

If your project has a hierarchy of libraries already, just use
target_link_libraries to add the globally required library to the
top-most libraries in the hierarchy.  Link dependency analysis will
take care of the rest.

-Brad

> On Wed, 2009-04-01 at 23:50 -0400, Philip Lowman wrote:
>> On Wed, Apr 1, 2009 at 5:35 PM, Marcel Loose <loose at astron.nl> wrote:
>>         Hi all,
>>         
>>         I was wondering why the link_libraries() command has been
>>         deprecated. Commands like include_directories() and
>>         link_directories() which have the same "scope" have not been
>>         deprecated. I think that link_libraries() has its virtues too.
>>         
>>         My reason for asking this, is that I wonder what's the proper
>>         way to add a library to *all* targets in a project; for
>>         example, a logging library or a threads library. Here,
>>         link_libraries() provides IMHO a much cleaner solution, than
>>         target_link_libraries(). The latter requires me to keep track
>>         of the globally used library in a variable that must be passed
>>         around; and for each target I must explicitly specify its
>>         dependency on this library by using target_link_libraries().
>>         
>>         Or, am I missing something, and is there a cleaner way to do
>>         this, without using a deprecated feature?
>>
>> Often I have seen people write functions to help with this especially
>> if you have more than one common library.
>>
>> function(link_target_against_common_libs _target)
>>    target_link_libraries(${_target} ${WHATEVER_LIBRARY})
>> endfunction()
>>
>> Another approach is if you have a low level library as part of your
>> codebase that everyone depends upon you can simply make it dependent
>> on your threading or logging libraries and anyone that is dependent
>> against it will automatically link against the threading or logging
>> library.
>>
>>
>> -- 
>> Philip Lowman
> 
> _______________________________________________
> Powered by www.kitware.com
> 
> Visit other Kitware open-source projects at http://www.kitware.com/opensource/opensource.html
> 
> Please keep messages on-topic and check the CMake FAQ at: http://www.cmake.org/Wiki/CMake_FAQ
> 
> Follow this link to subscribe/unsubscribe:
> http://www.cmake.org/mailman/listinfo/cmake