Re: [CMake] [cmake-developers] How should config packages handle components?

[Alex Turbov]

In my projects I always, have external dependencies with finder module
providing exported (imported in my project) targets, so my targets (one per
file) always have a list of `Vendor::target`. Some of them are mine (i.e.
your type 2 -- built by the same project).

I wrote a helper module and a function to write an additional
`blah-blah-target-depedencies.cmake`. And this is a little bit subtle
thing...
Normally, generated `blah-blah-target.cmake` (where the `blah-blah-target`
is the export name used in call to `install(EXPORT)`) to load all installed
configurations do the following:

  file(GLOB CONFIG_FILES "${_DIR}/blah-blah-target-*.cmake")


so my additional file would be loaded "automatically" :)

My helper function accepts a target name as the only parameter. First of
all, it collects all dependencies of the given target and classifies them
as internal (same project) and external. It prepares some variables and
finally, render a `blah-blah-target-dependencies.cmake` which is a result
of the combination of 3 templates:
0) a base, header+footer and conditionally "include" the next two
1) import internal dependencies
2) import external dependencies

Note templates have random string in final names, so being running
(loading) by the same script (`blah-blah-config.cmake`) won't interfere...

As for "prepared variables" there are the following:
* "internal dependencies" is just a list of target names... having a name
is enough to form a `blah-blah-target.cmake` name to be `include()`d, cuz
we really know where this file is installed
* for external dependencies the most important a list of packages, assuming
that the initial external (imported) target had the form of
`Vendor::target`, and `Vendor` in fact is a package name suitable as the
first argument to `find_package()`.
* other variables related to external targets have a variadic part based on
upcased name of the vendor. Example:

set(_blah_blah_PACKAGES ACE;Boost)
set(_blah_blah_ACE_VENDOR ACE)
set(_blah_blah_ACE_COMPONENTS ace;ssl)
set(_blah_blah_ACE_VERSION 5.7.5)
set(_blah_blah_BOOST_VENDOR Boost)
set(_blah_blah_BOOST_COMPONENTS
chrono;filesystem;program_options;thread)
set(_blah_blah_BOOST_VERSION 1.65.0)

Now about generated `*-config.cmake`. As one may guess it handle targets to
import as `COMPONENTS` of `find_package()`, where every component is an
exported target name. So this module just `include()` it and check if
target appeared:

# Find components if requested
set(blah_FOUND_COMPONENTS)
foreach(_module ${blah_FIND_COMPONENTS})
# TODO Avoid more than once find? (But be aware that is not a
trivial `if` and skip %-)
# TODO Make sure component is supported (exists)
include(
"${CMAKE_CURRENT_LIST_DIR}/blah-${_module}-targets.cmake"
OPTIONAL
RESULT_VARIABLE blah_${_module}_FOUND
)

if(blah_${_module}_FOUND AND TARGET Blah::${_module})
list(APPEND blah_FOUND_COMPONENTS ${_module})

# Add some interface properties to all found components
string(TOUPPER "${_module}" _module_id)
string(MAKE_C_IDENTIFIER "${_module_id}" _module_id)
set_target_properties(
Blah::${_module}
PROPERTIES
# Set compatible version usage requirement
INTERFACE_BLAH_VERSION_MAJOR "${BLAH_VERSION_MAJOR}"
# What package to find
INTERFACE_BLAH_${_module_id}_PACKAGE_NAME "blah"
)
set_property(
TARGET Blah::${_module}
APPEND PROPERTY
COMPATIBLE_INTERFACE_STRING BLAH_VERSION_MAJOR
)
unset(_module_id)

else()
set(blah_${_module}_FOUND NOTFOUND)

if (blah_FIND_REQUIRED_${_module})
list(APPEND blah_NOT_FOUND_REQUIRED_COMPONENTS ${_module})
else()
list(APPEND blah_NOT_FOUND_COMPONENTS ${_module})
endif()

endif()
endforeach()
unset(_module)

When all components checked call the final package found/not-found checker:

check_required_components(blah)

Yes, this particular implementation have obvious limitations to be named
"universal and generic", but it works few years for me w/o problems...
(however, I do some improvements from time to time %) It do not handle
"plain old library names"... and as I said, all my external packages
provide imported targets, where the Vendor name is the package name in
fact... so I don't care (while having no reason to improve it for this
case... maybe later %).

I'll attach my module (stripping not related and vendor specific parts) for
further inspiration... Feel free to ask for details (or more code, if
attached doesn't work... probably I miss some functions (from other parts
of my framework)).

Have fun! :)


On Tue, Sep 5, 2017 at 10:33 PM, Robert Dailey 

Re: [CMake] [cmake-developers] How should config packages handle components?

[Florent Castelli]

On 01/09/2017 20:40, Alex Turbov wrote:

Hi Robert,


On Fri, Sep 1, 2017 at 9:21 PM, Robert Dailey 
> wrote:



One problem I thought of with the former (one big target.cmake with
all import targets in there) is that if you only ask for a subset of
components in find_package(), you will still get all of them since all
imports are defined in a single file. 



In my project I have a bunch of components and do one exported target 
per component

exactly by the mentioned reason -- user didn't ask for others...

Does this go against any design
principles? 



As far as I know, there are no clear design principles :) (yet, at 
least nowadays) -- at least doing
a lot of CMake projects since 2009, I've never seen an explicit list 
of them %)
IMHO, there is a lack of "official guildelines" (or it is really hard 
to search for 'em)


Assuming this really happens, are there any negative side
effects?


I could see the impact on build time only in this case... and for me 
the most obvious is increasing
time to process the lists (which is for some reasons really slow on 
Windows, at least in our

build farm which uses vargant and VirtualBox images)
(but I don't have any particular numbers, cuz never implemented the 
first approach)


Well, there's no impact on build time. The module will provide IMPORTED 
targets, if they are not used,
they won't be used in the solution / Makefile. And I don't think CMake 
has any significant bottleneck
on having just a few more IMPORTED targets around from a find_package() 
module.


Components might be important for an old "FindFoo.cmake" module where 
you don't want to find
a lot more libraries in your path, not so much for a "FooConfig.cmake" 
which is a "dumb" file that

just defines a lot of targets and their properties.

/Florent
-- 

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:
http://public.kitware.com/mailman/listinfo/cmake

Re: [CMake] [cmake-developers] How should config packages handle components?

[Alex Turbov]

I've started to use CMake a quite long time ago, and do not search for
"standards" or "guidelines" anymore %)
But I could mention some chapters in the official documentation (in the
"Reference Manuals" section) which are really full of "secret knowledge",
but the problem is that they are too complicated for newcomers %) but
personally I read them many many times before and each time found smth
"new" to me :)

I would say that after a couple of years I started to feel comfortable w/
CMake -- when I've used almost all offered features in a different set of
platform and generators.

On Fri, Sep 1, 2017 at 9:49 PM, Robert Dailey 
wrote:

> On Fri, Sep 1, 2017 at 1:40 PM, Alex Turbov  wrote:
> > Hi Robert,
> >
> >
> > On Fri, Sep 1, 2017 at 9:21 PM, Robert Dailey 
> > wrote:
> >>
> >>
> >> One problem I thought of with the former (one big target.cmake with
> >> all import targets in there) is that if you only ask for a subset of
> >> components in find_package(), you will still get all of them since all
> >> imports are defined in a single file.
> >
> >
> > In my project I have a bunch of components and do one exported target per
> > component
> > exactly by the mentioned reason -- user didn't ask for others...
> >
> >>
> >> Does this go against any design
> >> principles?
> >
> >
> > As far as I know, there are no clear design principles :) (yet, at least
> > nowadays) -- at least doing
> > a lot of CMake projects since 2009, I've never seen an explicit list of
> them
> > %)
> > IMHO, there is a lack of "official guildelines" (or it is really hard to
> > search for 'em)
> >
> >> Assuming this really happens, are there any negative side
> >> effects?
> >
> >
> > I could see the impact on build time only in this case... and for me the
> > most obvious is increasing
> > time to process the lists (which is for some reasons really slow on
> Windows,
> > at least in our
> > build farm which uses vargant and VirtualBox images)
> > (but I don't have any particular numbers, cuz never implemented the first
> > approach)
>
> Thanks for the quick response. The "official guidelines" or "package
> standard" is really exactly what we need I think. What worries me the
> most is that it seems like this is deep knowledge that is stuck in the
> brains of folks like Brad King and David Cole. I think somehow getting
> a knowledge dump from them into a documentation page would be a
> valuable task. I think for something as complex and variable as
> packages in CMake (install process in general) deserves some
> standardization, because we need the ability to distinguish between
> practices that we should follow for legacy (backward compatibility)
> reasons, non-cmake project reasons, and fully "modern" cmake packages.
>
-- 

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:
http://public.kitware.com/mailman/listinfo/cmake

Re: [CMake] [cmake-developers] How should config packages handle components?

[Robert Dailey]

On Fri, Sep 1, 2017 at 1:40 PM, Alex Turbov  wrote:
> Hi Robert,
>
>
> On Fri, Sep 1, 2017 at 9:21 PM, Robert Dailey 
> wrote:
>>
>>
>> One problem I thought of with the former (one big target.cmake with
>> all import targets in there) is that if you only ask for a subset of
>> components in find_package(), you will still get all of them since all
>> imports are defined in a single file.
>
>
> In my project I have a bunch of components and do one exported target per
> component
> exactly by the mentioned reason -- user didn't ask for others...
>
>>
>> Does this go against any design
>> principles?
>
>
> As far as I know, there are no clear design principles :) (yet, at least
> nowadays) -- at least doing
> a lot of CMake projects since 2009, I've never seen an explicit list of them
> %)
> IMHO, there is a lack of "official guildelines" (or it is really hard to
> search for 'em)
>
>> Assuming this really happens, are there any negative side
>> effects?
>
>
> I could see the impact on build time only in this case... and for me the
> most obvious is increasing
> time to process the lists (which is for some reasons really slow on Windows,
> at least in our
> build farm which uses vargant and VirtualBox images)
> (but I don't have any particular numbers, cuz never implemented the first
> approach)

Thanks for the quick response. The "official guidelines" or "package
standard" is really exactly what we need I think. What worries me the
most is that it seems like this is deep knowledge that is stuck in the
brains of folks like Brad King and David Cole. I think somehow getting
a knowledge dump from them into a documentation page would be a
valuable task. I think for something as complex and variable as
packages in CMake (install process in general) deserves some
standardization, because we need the ability to distinguish between
practices that we should follow for legacy (backward compatibility)
reasons, non-cmake project reasons, and fully "modern" cmake packages.
-- 

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:
http://public.kitware.com/mailman/listinfo/cmake

Re: [CMake] [cmake-developers] How should config packages handle components?

[Alex Turbov]

Hi Robert,


On Fri, Sep 1, 2017 at 9:21 PM, Robert Dailey 
wrote:

>
> One problem I thought of with the former (one big target.cmake with
> all import targets in there) is that if you only ask for a subset of
> components in find_package(), you will still get all of them since all
> imports are defined in a single file.


In my project I have a bunch of components and do one exported target per
component
exactly by the mentioned reason -- user didn't ask for others...


> Does this go against any design
> principles?


As far as I know, there are no clear design principles :) (yet, at least
nowadays) -- at least doing
a lot of CMake projects since 2009, I've never seen an explicit list of
them %)
IMHO, there is a lack of "official guildelines" (or it is really hard to
search for 'em)

Assuming this really happens, are there any negative side
> effects?
>

I could see the impact on build time only in this case... and for me the
most obvious is increasing
time to process the lists (which is for some reasons really slow on
Windows, at least in our
build farm which uses vargant and VirtualBox images)
(but I don't have any particular numbers, cuz never implemented the first
approach)




--
>
> 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:
> http://public.kitware.com/mailman/listinfo/cmake-developers
>
-- 

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:
http://public.kitware.com/mailman/listinfo/cmake