Confused by documentation about header-only libs

[fschoenm]

The documentation about packaging header-only libraries states:

Note that this recipe has no other dependencies, settings or options. If it had any of those, it would be very convenient to add the package_id() method, to ensure that only one package with always the same ID is created, irrespective of the configurations and dependencies:

def package_id(self):
    self.info.header_only()

I'm confused by that because if I understand the statement correctly, you should specify the package_id like that to prevent multiple packages if you have dependencies, settings, or options.

Wouldn't that lead to the options of the package essentially being ignored and only one package existing that is just using the options specified in the last build?

That's what's happening in my case when I use that package_id definitions. The second package creation step overwrites the first one because the package ID is identical:

$ conan create . -o with_license=True fschoenm/testing
Exporting package recipe
catch/2.9.1@fschoenm/testing: A new conanfile.py version was exported
catch/2.9.1@fschoenm/testing: Folder: /home/fschoenm/.conan/data/catch/2.9.1/fschoenm/testing/export
catch/2.9.1@fschoenm/testing: Package recipe modified in export, forcing source folder removal
catch/2.9.1@fschoenm/testing: Use the --keep-source, -k option to skip it
Configuration:
[settings]
arch=x86_64
arch_build=x86_64
build_type=Debug
compiler=gcc
compiler.libcxx=libstdc++11
compiler.version=8
os=Linux
os_build=Linux
[options]
with_license=True
[build_requires]
[env]
CC=gcc-8
CXX=g++-8
catch/2.9.1@fschoenm/testing: Forced build from source
Installing package: catch/2.9.1@fschoenm/testing
Requirements
    catch/2.9.1@fschoenm/testing from local cache - Cache
Python requires
    LicenseHelper/1.0@vsdk/stable
Packages
    catch/2.9.1@fschoenm/testing:5ab84d6acfe1f23c4fae0ab88f26e3a396351ac9 - Build

catch/2.9.1@fschoenm/testing: Configuring sources in /home/fschoenm/.conan/data/catch/2.9.1/fschoenm/testing/source
[==================================================] 612.7KB/612.7KB  
[==================================================] 1.3KB/770B       
catch/2.9.1@fschoenm/testing: Copying sources to build folder
catch/2.9.1@fschoenm/testing: Building your package in /home/fschoenm/.conan/data/catch/2.9.1/fschoenm/testing/build/5ab84d6acfe1f23c4fae0ab88f26e3a396351ac9
catch/2.9.1@fschoenm/testing: Generator txt created conanbuildinfo.txt
catch/2.9.1@fschoenm/testing: Calling build()
catch/2.9.1@fschoenm/testing: WARN: This conanfile has no build step
catch/2.9.1@fschoenm/testing: Package '5ab84d6acfe1f23c4fae0ab88f26e3a396351ac9' built
catch/2.9.1@fschoenm/testing: Build folder /home/fschoenm/.conan/data/catch/2.9.1/fschoenm/testing/build/5ab84d6acfe1f23c4fae0ab88f26e3a396351ac9
catch/2.9.1@fschoenm/testing: Generated conaninfo.txt
catch/2.9.1@fschoenm/testing: Generated conanbuildinfo.txt
catch/2.9.1@fschoenm/testing: Generating the package
catch/2.9.1@fschoenm/testing: Package folder /home/fschoenm/.conan/data/catch/2.9.1/fschoenm/testing/package/5ab84d6acfe1f23c4fae0ab88f26e3a396351ac9
catch/2.9.1@fschoenm/testing: Calling package()
catch/2.9.1@fschoenm/testing package(): Packaged 1 '.hpp' file: catch.hpp
catch/2.9.1@fschoenm/testing package(): Packaged 1 '.lic' file: catch.lic
catch/2.9.1@fschoenm/testing: Package '5ab84d6acfe1f23c4fae0ab88f26e3a396351ac9' created
catch/2.9.1@fschoenm/testing: Created package revision 1aad708e20c9992bcc855b82cb1f46d5
$ conan create . -o with_license=False fschoenm/testing
 xporting package recipe
catch/2.9.1@fschoenm/testing: The stored package has not changed
Configuration:
[settings]
arch=x86_64
arch_build=x86_64
build_type=Debug
compiler=gcc
compiler.libcxx=libstdc++11
compiler.version=8
os=Linux
os_build=Linux
[options]
with_license=False
[build_requires]
[env]
CC=gcc-8
CXX=g++-8
catch/2.9.1@fschoenm/testing: Forced build from source
Installing package: catch/2.9.1@fschoenm/testing
Requirements
    catch/2.9.1@fschoenm/testing from local cache - Cache
Python requires
    LicenseHelper/1.0@vsdk/stable
Packages
    catch/2.9.1@fschoenm/testing:5ab84d6acfe1f23c4fae0ab88f26e3a396351ac9 - Build

catch/2.9.1@fschoenm/testing: Copying sources to build folder
catch/2.9.1@fschoenm/testing: Building your package in /home/fschoenm/.conan/data/catch/2.9.1/fschoenm/testing/build/5ab84d6acfe1f23c4fae0ab88f26e3a396351ac9
catch/2.9.1@fschoenm/testing: Generator txt created conanbuildinfo.txt
catch/2.9.1@fschoenm/testing: Calling build()
catch/2.9.1@fschoenm/testing: WARN: This conanfile has no build step
catch/2.9.1@fschoenm/testing: Package '5ab84d6acfe1f23c4fae0ab88f26e3a396351ac9' built
catch/2.9.1@fschoenm/testing: Build folder /home/fschoenm/.conan/data/catch/2.9.1/fschoenm/testing/build/5ab84d6acfe1f23c4fae0ab88f26e3a396351ac9
catch/2.9.1@fschoenm/testing: Generated conaninfo.txt
catch/2.9.1@fschoenm/testing: Generated conanbuildinfo.txt
catch/2.9.1@fschoenm/testing: Generating the package
catch/2.9.1@fschoenm/testing: Package folder /home/fschoenm/.conan/data/catch/2.9.1/fschoenm/testing/package/5ab84d6acfe1f23c4fae0ab88f26e3a396351ac9
catch/2.9.1@fschoenm/testing: Calling package()
catch/2.9.1@fschoenm/testing package(): Packaged 1 '.hpp' file: catch.hpp
catch/2.9.1@fschoenm/testing: Package '5ab84d6acfe1f23c4fae0ab88f26e3a396351ac9' created
catch/2.9.1@fschoenm/testing: Created package revision c95783ad4ceaa58fe00444fae5390e43

To help us debug your issue please explain:

• I've read the CONTRIBUTING guide.
• I've specified the Conan version, operating system version and any tool that can be relevant.
• I've explained the steps to reproduce the error or the motivation/use case of the question/suggestion.

[Minimonium]

Wouldn't that lead to the options of the package essentially being ignored and only one package existing that is just using the options specified in the last build?

Yes, header_only() is implemented as:

def header_only(self):
        self.settings.clear()
        self.options.clear()
        self.requires.clear()

It would obviously not work for header-only packages that produce different packages depending on the configuration. You'd need to delete configurations manually to adjust the package_id.

If you have feedback on how to improve the documentation please help the project at 🙂 :
https://github.com/conan-io/docs

[fschoenm]

I wonder if that's a reasonable approach. In my case, I wanted to use an option for a header-only library to specify if the package should contain the LICENSE file of the library but I can imagine other use cases for options (e.g. leaving out parts of library).

Why do conan and conan's documentation assume that header-only libs don't need/have any options?

[Minimonium]

I'm not sure "why", but it'd be a breaking change to "fix" that behaviour.
So the only possible option I see to help users is to extend the documentation on that moment. Maybe even to better explain package_id.

[fschoenm]

In that case, maybe it would be useful to print a warning if the package has options or if options are used to notify the user that his options are going to be ignored?

Improving the documentation would also help because the information from there is what confused me in the first place.

[danimtb]

I agree it is confusing. I think this was implemented like this as many header-only libs have options to compile an run the tests.

I will transfer this issue to the docs repository to document this behavior clearly.

Thanks a lot for the feedback and the suggestions!