What are the actual benefits of namespaced targets?

classic Classic list List threaded Threaded
6 messages Options
Reply | Threaded
Open this post in threaded view
|

What are the actual benefits of namespaced targets?

Alan W. Irwin
I am currently trying to update three CMake-based build systems (for
PLplot, ephcom, and te_gen) to use best practices following the really
useful example of best practice given at
<https://pabloariasal.github.io/2018/02/19/its-time-to-do-cmake-right/>.

That example uses the NAMESPACE signature for the
install(EXPORT ... ) command to export its targets.  I realize that is
a quite common practice, but I don't understand the motivation for
this practice. After all, the library names (and therefore the
un-namespaced associated targets) already are virtually guaranteed to
be unique (since two projects with two different libraries with a
common library name would be an invitation to nameclash disaster). So
what are the actual benefits of namespacing the exported targets
associated with libraries?

The reason why I ask is namespaced targets would add some (small)
complexity to my build systems.  For example, I would need to define a
namespaced ALIAS target for each library in my build tree to use
common CMake logic to refer to that library in the build systems for
both my build tree and install tree.  (I use that common-code practice
for all three of the above projects.) Defining such ALIAS targets
should be absolutely straightforward, but I want to make sure the
actual namespaced target benefits outweigh this small added
complexity.

Alan
__________________________
Alan W. Irwin

Astronomical research affiliation with Department of Physics and Astronomy,
University of Victoria (astrowww.phys.uvic.ca).

Programming affiliations with the FreeEOS equation-of-state
implementation for stellar interiors (freeeos.sf.net); the Time
Ephemerides project (timeephem.sf.net); PLplot scientific plotting
software package (plplot.sf.net); the libLASi project
(unifont.org/lasi); the Loads of Linux Links project (loll.sf.net);
and the Linux Brochure Project (lbproject.sf.net).
__________________________

Linux-powered Science
__________________________
--

Powered by www.kitware.com

Please keep messages on-topic and check the CMake FAQ at: http://www.cmake.org/Wiki/CMake_FAQ

Kitware offers various services to support the CMake community. For more information on each offering, please visit:

CMake Support: http://cmake.org/cmake/help/support.html
CMake Consulting: http://cmake.org/cmake/help/consulting.html
CMake Training Courses: http://cmake.org/cmake/help/training.html

Visit other Kitware open-source projects at http://www.kitware.com/opensource/opensource.html

Follow this link to subscribe/unsubscribe:
https://cmake.org/mailman/listinfo/cmake
Reply | Threaded
Open this post in threaded view
|

Re: What are the actual benefits of namespaced targets?

Nils Gladitz-2
On 08.03.2018 19:50, Alan W. Irwin wrote:
> So what are the actual benefits of namespacing the exported targets
> associated with libraries?

On the consumer side it makes linking to targets less error prone.

When you link to a library target without a namespace and e.g. get the
name or scope wrong CMake will silently assume that you want to link a
library by name (e.g. in context of gcc "foo" becomes "-lfoo").
When the library and its headers happens to be in the compiler's
standard search directories this might not even get caught at build time
right away.

When the library target has a namespace CMake will require the given
name to be a target and will fail during generation if the target is not
actually available.

Nils
--

Powered by www.kitware.com

Please keep messages on-topic and check the CMake FAQ at: http://www.cmake.org/Wiki/CMake_FAQ

Kitware offers various services to support the CMake community. For more information on each offering, please visit:

CMake Support: http://cmake.org/cmake/help/support.html
CMake Consulting: http://cmake.org/cmake/help/consulting.html
CMake Training Courses: http://cmake.org/cmake/help/training.html

Visit other Kitware open-source projects at http://www.kitware.com/opensource/opensource.html

Follow this link to subscribe/unsubscribe:
https://cmake.org/mailman/listinfo/cmake
Reply | Threaded
Open this post in threaded view
|

Re: What are the actual benefits of namespaced targets?

Alan W. Irwin
On 2018-03-08 20:05+0100 Nils Gladitz wrote:

> On 08.03.2018 19:50, Alan W. Irwin wrote:
>> So what are the actual benefits of namespacing the exported targets
>> associated with libraries?
>
> On the consumer side it makes linking to targets less error prone.
>
> When you link to a library target without a namespace and e.g. get the name
> or scope wrong CMake will silently assume that you want to link a library by
> name (e.g. in context of gcc "foo" becomes "-lfoo").
> When the library and its headers happens to be in the compiler's standard
> search directories this might not even get caught at build time right away.
>
> When the library target has a namespace CMake will require the given name to
> be a target and will fail during generation if the target is not actually
> available.

Hi Nils:

Thanks for that explanation which convinced me this particular "best
practice" is worth implementing along with the rest mentioned in
<https://pabloariasal.github.io/2018/02/19/its-time-to-do-cmake-right/>.

Alan
__________________________
Alan W. Irwin

Astronomical research affiliation with Department of Physics and Astronomy,
University of Victoria (astrowww.phys.uvic.ca).

Programming affiliations with the FreeEOS equation-of-state
implementation for stellar interiors (freeeos.sf.net); the Time
Ephemerides project (timeephem.sf.net); PLplot scientific plotting
software package (plplot.sf.net); the libLASi project
(unifont.org/lasi); the Loads of Linux Links project (loll.sf.net);
and the Linux Brochure Project (lbproject.sf.net).
__________________________

Linux-powered Science
__________________________
--

Powered by www.kitware.com

Please keep messages on-topic and check the CMake FAQ at: http://www.cmake.org/Wiki/CMake_FAQ

Kitware offers various services to support the CMake community. For more information on each offering, please visit:

CMake Support: http://cmake.org/cmake/help/support.html
CMake Consulting: http://cmake.org/cmake/help/consulting.html
CMake Training Courses: http://cmake.org/cmake/help/training.html

Visit other Kitware open-source projects at http://www.kitware.com/opensource/opensource.html

Follow this link to subscribe/unsubscribe:
https://cmake.org/mailman/listinfo/cmake
Reply | Threaded
Open this post in threaded view
|

Re: What are the actual benefits of namespaced targets?

Alan W. Irwin
On 2018-03-08 12:49-0800 Alan W. Irwin wrote:

> On 2018-03-08 20:05+0100 Nils Gladitz wrote:
>
>> On 08.03.2018 19:50, Alan W. Irwin wrote:
>>> So what are the actual benefits of namespacing the exported targets
>>> associated with libraries?
>>
>> On the consumer side it makes linking to targets less error prone.
>>
>> When you link to a library target without a namespace and e.g. get the name
>> or scope wrong CMake will silently assume that you want to link a library
>> by name (e.g. in context of gcc "foo" becomes "-lfoo").
>> When the library and its headers happens to be in the compiler's standard
>> search directories this might not even get caught at build time right away.
>>
>> When the library target has a namespace CMake will require the given name
>> to be a target and will fail during generation if the target is not
>> actually available.
>
> Hi Nils:
>
> Thanks for that explanation which convinced me this particular "best
> practice" is worth implementing along with the rest mentioned in
> <https://pabloariasal.github.io/2018/02/19/its-time-to-do-cmake-right/>.

Hi Nils:

Here are some further questions about best practice with regard to
namespaced targets.  The three different build systems I am updating
in this regard have some common CMake code between the build-tree and
install-tree cases (to build examples and run various commands for the
two cases) so for that common code I need to use a namespaced ALIAS
library for the rather large number of libraries and modules (e.g.,
PLplot device driver dll's) that are built by those three projects in
order for the namespaced targets to also be available in the
build-tree case.

But since I am already going to the trouble of creating those ALIAS
libraries for each of my real libraries and modules, what is best
practice for use of those ALIAS libraries and modules in the build
tree?

For example, should I just confine their use to common
target_link_libraries and add_dependencies commands for the build-tree
and install-tree cases?

Or would you recommend I expand their use further for the build tree
case alone?  For example, would you recommend the following change:


OLD method:

add_library(a ...)
add_executable(b ...)
target_link_libraries(b a)

NEW method (where <namespace> would be one of PLPLOT::, EPHCOM::, or
TE_GEN:: depending on project):


add_library(a ...)
add_library(<namespace>a ALIAS a)
add_executable(b ...)
target_link_libraries(b <namespace>a)

?

This *could* be considered best practice since similar motivations
apply ("a" could be the name of a system library so using <namespace>a
as a target_link_libraries item *could* find a build system bug (where
some naive build system developer was happily referring to what he
thought was an internal library when in fact the system version was
being used because of some misspelling issue when creating the
library.) But I think such misspelling issues would be quickly found
for build systems in any case so my feeling is you will say this is
"one step too far" since there is lots of editing involved (for all
code, not just the common code) for very little added benefit.

Anyhow, your thoughts would be appreciated for reasonable best
practice limits on how far (if any) beyond the common code case you
would go to convert an old project to use
ALIAS libraries and modules in the build tree that have to be
implemented in any case for CMake code that is common to
both the build tree and install tree.

Alan
__________________________
Alan W. Irwin

Astronomical research affiliation with Department of Physics and Astronomy,
University of Victoria (astrowww.phys.uvic.ca).

Programming affiliations with the FreeEOS equation-of-state
implementation for stellar interiors (freeeos.sf.net); the Time
Ephemerides project (timeephem.sf.net); PLplot scientific plotting
software package (plplot.sf.net); the libLASi project
(unifont.org/lasi); the Loads of Linux Links project (loll.sf.net);
and the Linux Brochure Project (lbproject.sf.net).
__________________________

Linux-powered Science
__________________________
--

Powered by www.kitware.com

Please keep messages on-topic and check the CMake FAQ at: http://www.cmake.org/Wiki/CMake_FAQ

Kitware offers various services to support the CMake community. For more information on each offering, please visit:

CMake Support: http://cmake.org/cmake/help/support.html
CMake Consulting: http://cmake.org/cmake/help/consulting.html
CMake Training Courses: http://cmake.org/cmake/help/training.html

Visit other Kitware open-source projects at http://www.kitware.com/opensource/opensource.html

Follow this link to subscribe/unsubscribe:
https://cmake.org/mailman/listinfo/cmake
Reply | Threaded
Open this post in threaded view
|

Re: What are the actual benefits of namespaced targets?

Nils Gladitz-2
On 10.03.2018 23:01, Alan W. Irwin wrote:
> Anyhow, your thoughts would be appreciated for reasonable best
> practice limits on how far (if any) beyond the common code case you
> would go to convert an old project to use
> ALIAS libraries and modules in the build tree that have to be
> implemented in any case for CMake code that is common to
> both the build tree and install tree.


Hello Alan,

I agree with your assessments.

Assuming a project that is highly structured through directory scopes I
might consider the following.

Any target is defined in exactly one directory scope.
Any command that extends the definition of a target has to use the
original target name and should be in the same directory scope.

In all other directory scopes I'd consider consistent use of a target's
alias.

While it is less likely for a seasoned developer to trip over the
interpretation ambiguity in link libraries (due to familiarity and the
fact that they probably already tripped over this and know the symptoms)
it might still be beneficial for new / casual contributors which as
likely consumers might also already be familiar with the aliases.

One minor additional benefit might be that you are also not allowed to
modify the original target through an alias.
As such this would prevent you (assuming you stick to the namespaced
names) from modifying targets from within foreign scopes which I think
is a good thing to enforce.

Beyond that consumers might be looking at your code base for examples on
how to use the libraries in their own code where consistency might be
beneficial.
It might also help (slightly) if you ever decided to split off parts of
your project into new projects (which then would become consumers of the
exported targets).

Nils
--

Powered by www.kitware.com

Please keep messages on-topic and check the CMake FAQ at: http://www.cmake.org/Wiki/CMake_FAQ

Kitware offers various services to support the CMake community. For more information on each offering, please visit:

CMake Support: http://cmake.org/cmake/help/support.html
CMake Consulting: http://cmake.org/cmake/help/consulting.html
CMake Training Courses: http://cmake.org/cmake/help/training.html

Visit other Kitware open-source projects at http://www.kitware.com/opensource/opensource.html

Follow this link to subscribe/unsubscribe:
https://cmake.org/mailman/listinfo/cmake
Reply | Threaded
Open this post in threaded view
|

Re: What are the actual benefits of namespaced targets?

Alan W. Irwin
On 2018-03-11 10:15+0100 Nils Gladitz wrote:

> On 10.03.2018 23:01, Alan W. Irwin wrote:
>> Anyhow, your thoughts would be appreciated for reasonable best
>> practice limits on how far (if any) beyond the common code case you
>> would go to convert an old project to use
>> ALIAS libraries and modules in the build tree that have to be
>> implemented in any case for CMake code that is common to
>> both the build tree and install tree.
>
>
> Hello Alan,
>
> I agree with your assessments.
>
> Assuming a project that is highly structured through directory scopes I might
> consider the following.
>
> Any target is defined in exactly one directory scope.
> Any command that extends the definition of a target has to use the original
> target name and should be in the same directory scope.
>
> In all other directory scopes I'd consider consistent use of a target's
> alias.

Hi Nils:

I think your suggestions prior to the last one above make perfect
sense, and as far as I know my three projects already conform to them.

But I have now considered your last suggestion (replacing read-only
library and module targets in the build tree with the relevant
namespaced target alias), but I have decided the cost/benefit ratio is
too high in the PLplot case.  The cost issue is PLplot has some 330
different build system files (those named "CMakeLists.txt", "*.cmake",
or "*in") and something like 30 different library and module targets.
An additional complication is all libraries include "plplot" in the
target name (including our principal library whose target name is
"plplot") but "plplot" also occurs in all sorts of other contexts in
those 330 files.  So making this change in the PLplot case would
require a massive mentally concentrated editing exercise for what I
think is a rather small and mostly stylistic benefit.  So for PLplot I
plan to limit use of namespaced targets to just the
target_link_libraries and add_dependencies commands that are common to
the build-tree and install-tree build systems.

In contrast to the PLplot case, the costs of your last suggestion are
much lower for the ephcom and te_gen cases (many fewer build-system
files, libraries, and modules) so in those cases I might go all the
way with converting the present read-only library and module targets
with namespaced targets.  And similarly when implementing new projects
since the costs are even lower in those cases.

Alan
__________________________
Alan W. Irwin

Astronomical research affiliation with Department of Physics and Astronomy,
University of Victoria (astrowww.phys.uvic.ca).

Programming affiliations with the FreeEOS equation-of-state
implementation for stellar interiors (freeeos.sf.net); the Time
Ephemerides project (timeephem.sf.net); PLplot scientific plotting
software package (plplot.sf.net); the libLASi project
(unifont.org/lasi); the Loads of Linux Links project (loll.sf.net);
and the Linux Brochure Project (lbproject.sf.net).
__________________________

Linux-powered Science
__________________________
--

Powered by www.kitware.com

Please keep messages on-topic and check the CMake FAQ at: http://www.cmake.org/Wiki/CMake_FAQ

Kitware offers various services to support the CMake community. For more information on each offering, please visit:

CMake Support: http://cmake.org/cmake/help/support.html
CMake Consulting: http://cmake.org/cmake/help/consulting.html
CMake Training Courses: http://cmake.org/cmake/help/training.html

Visit other Kitware open-source projects at http://www.kitware.com/opensource/opensource.html

Follow this link to subscribe/unsubscribe:
https://cmake.org/mailman/listinfo/cmake