[CMake] Multiple exports for a target installation

Mon Jun 24 18:16:44 EDT 2019

Thank you for the detailed explanation! That’s really helpful and gives me a much better sense of how to think about and structure this :)

From: Craig Scott <craig.scott at crascit.com>
Date: Saturday, June 22, 2019 at 12:18 AM
To: Shoaib Meenai <smeenai at fb.com>
Cc: "cmake at cmake.org" <cmake at cmake.org>
Subject: Re: [CMake] Multiple exports for a target installation

On Tue, Jun 18, 2019 at 10:29 AM Shoaib Meenai <smeenai at fb.com<mailto:smeenai at fb.com>> wrote:
Thank you!

When you say having an export set that the other exports then depend on, do you mean the COMPONENT option of the install(EXPORT) signature, or something else? (Sadly the project I’m working with is still on CMake 3.4.3, whose documentation says something very different for the COMPONENT option than the latest version, but I’ll cross that bridge when I get to it.)

As far as components and export sets are concerned, the behavior isn't much different between CMake 3.4 and 3.14. Think of it like this:

  *   The config file for a package (i.e. its <packageName>Config.cmake file) may refer to one or more export sets. It can do this in a way that some or all of the export sets are optional, pulling them in if present, silently continuing if not. It depends on the way the project wants to define and use its export sets. For most projects, they will require all export sets they refer to to be present. The optional components of a find_package() call might map to optional export sets (just one example of how optional export sets might be used).
  *   An export set defines targets. That set of targets can span across one or more components. The export set requires all of those components to be installed/present or it is considered ill-formed (or put another way, the installation is incomplete). The install(TARGETS ... EXPORT ...) command determines what targets are in which export set. The install(EXPORT ...) command defines what component the actual export file is part of (further discussion on this below).
  *   A component can include targets, files and custom scripts to be invoked when installing that component from a build tree. Targets and files can technically be part of multiple components, but this would be relatively uncommon and may complicate the export picture. A component may depend on one or more other components, e.g. a Development component may require a Runtime component, such as Development headers requiring the Runtime shared library.
If a project decides to split up its exports across multiple export sets, there can be dependencies between them. For example, a project might define export set Algo which has components Fast and Accurate, and export set Apps which has components Gui and CLI. The project's <packageName>Config.cmake file requires the Algo export set to be present but the Apps export set is optional and only pulled in if present. In this scenario, one might have the Fast and Accurate components installed, but not the Gui or CLI components. The Algo export set represents the mandatory parts of the package that will always be needed. The Gui and CLI components might not be installed if, for example, someone just wants to build against the libraries provided by the Fast and Accurate components (i.e. they are writing their own apps rather than wanting to use the apps that are provided by the Gui and CLI components).

What can be a bit confusing is that the exported file itself is also part of a component. That exported file might or might not need to be installed, depending on whether the project is being distributed as purely runtime components or whether other projects might be building against it and therefore expect headers, package config files, etc. The exported file (which is installed by install(EXPORT ...) ) is only needed for the latter, so it is usually part of a Development component or something similarly named (hopefully named something project-specific rather than just a generic "Development"!). The <packageName>Config.cmake file is also part of a component, and may be part of the same component that the export file is in.

The above is how I think about packages, export sets and components. You could have more complicated arrangements and have some overlap between export sets, but I'd generally try to avoid that if possible. It's simpler if you can structure things with clear and unambiguous dependencies without cycles or overlaps. It's already quite involved even without those things!

HTH

From: Craig Scott <craig.scott at crascit.com<mailto:craig.scott at crascit.com>>
Date: Saturday, June 15, 2019 at 10:43 PM
To: Shoaib Meenai <smeenai at fb.com<mailto:smeenai at fb.com>>
Cc: "cmake at cmake.org<mailto:cmake at cmake.org>" <cmake at cmake.org<mailto:cmake at cmake.org>>
Subject: Re: [CMake] Multiple exports for a target installation

On Sat, Jun 15, 2019 at 9:03 PM Shoaib Meenai <smeenai at fb.com<mailto:smeenai at fb.com>> wrote:
Is it possible to associate a target with multiple exports? For example, if I'm building a project where I want to create multiple export sets, but there's some overlap in targets between those sets. I tried passing multiple EXPORT options to the install(TARGETS) signature but I just got an error: install TARGETS given unknown argument "EXPORT".

Typically, you'd want your export sets to not be overlapping and to contain no cyclic dependencies. If you have a target in multiple export sets, it suggests that you probably should factor out that target to a separate export set that other exports then depend on. That said, if you have a scenario that legitimately requires a target in multiple export sets, then you would need to use multiple install() commands to achieve this, specifying a different export set for each one.

--
Craig Scott
Melbourne, Australia
https://crascit.com<https://urldefense.proofpoint.com/v2/url?u=https-3A__crascit.com&d=DwMFaQ&c=5VD0RTtNlTh3ycd41b3MUw&r=o3kDXzdBUE3ljQXKeTWOMw&m=fbTRNztVUYoZQ3jWMZDCnjUkgyIkIY3oKUOcoSHtJhU&s=D8L2FOhY6A090QgEuF3TlSRsaoWmXEMMvLkZGqKyn60&e=>

Get the hand-book for every CMake user: Professional CMake: A Practical Guide<https://urldefense.proofpoint.com/v2/url?u=https-3A__crascit.com_professional-2Dcmake_&d=DwMFaQ&c=5VD0RTtNlTh3ycd41b3MUw&r=o3kDXzdBUE3ljQXKeTWOMw&m=fbTRNztVUYoZQ3jWMZDCnjUkgyIkIY3oKUOcoSHtJhU&s=sgkIsOcB05bpz9VPxJm34J7is5oYnwNtGYWQkbvYzuE&e=>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <https://cmake.org/pipermail/cmake/attachments/20190624/779c6dd1/attachment-0001.html>