Discussion: establishing common rules for unofficial cmake configs

[Pospelove]

While working on some of the ports, I noticed that there are easily missable things in CMake config files including the following.

• if(NOT TARGET ...) should be present in config in order to prevent fatal errors in case of calling find_package multiple times
• Configs should set IMPORTED_LOCATION_RELEASE and/or IMPORTED_LOCATION_DEBUG properties respecting VCPKG_BUILD_TYPE values release, debug and <empty string> (please correct me if I'm wrong)
• Configs should set the IMPORTED_CONFIGURATIONS property
• Configs should not use find_path to find include dirs
• Configs should prefer find_dependency over find_package
• If configure_file is used, unofficial-<port>-config.cmake.in should be used as a file name

Ports for reference:

• node-api
• node-addon-api
• isal
• chakracore

Please feel free to correct me and/or suggest more.

I think such rules may be added to the PR review checklist. Maybe even to the port linter.

[Pospelove]

@dg0yt What do you think?

[dg0yt]

It would be nice to write it down.

• Upstreaming CMake config support is preferred over adding unofficial config.

• Existing official pkg-config support is preferred over unofficial config.

• Wrapping official (Kitware) CMake modules is preferred over unofficial config.

• Targets are preferred over variables.

• Export from CMake build systems is preferred over implementation using find_....

• Configs should use find_library in very restricted ways (using PATHS, NO_DEFAULT_PATH, and (with alternative names) NAMES_PER_DIR).

• If configure_file is used, unofficial-<port>-config.cmake.in should be used as a file name

  I would prefer to stay with unofficial-<port>-config.cmake, for better syntax support in editors (e.g. VS Code).

[Neumann-A]

I would prefer to stay with unofficial--config.cmake, for better syntax support in editors (e.g. VS Code).

That is the reason why i sometimes use *.in.cmake instead of *.cmake.in.

Personal and probably unpopular opinion: unofficial-<port>-config.cmake should just go completely. If vcpkg add manual configs/modules those should be generated from the portfile automatically by looking what actually got installed. I would prefer modules instead of configs since those could be written in a package manager agnostic way and simply copied out of vcpkg.

[Pospelove]

@Neumann-A did anyone try generating configs based on includes/libs installed?

[dg0yt]

Personal and probably unpopular opinion: unofficial-<port>-config.cmake should just go completely. If vcpkg add manual configs/modules those should be generated from the portfile automatically by looking what actually got installed. I would prefer modules instead of configs since those could be written in a package manager agnostic way and simply copied out of vcpkg.

I'm not convinced. What the exported config can give is precise transitive usage requirements corresponding to the chosen feature set. This is information which is readily available in the exported information for fairly regular cmake projects.
But given how intrusive vcpkg already is (overloading cmake functions), there might be alternatives for capturing this information during the port build without patching.

Also, I prefer config packages over find modules. The package form doesn't imply a particular implementation, but it impacts search procedures. Config mode is much more flexible in this regard. And Find modules cannot use find_dependency.

However, I would throw away the wrappers. This could be handled by generate Find modules. This would allow more use without putting vcpkg into CMAKE_TOOLCHAIN_FILE.

[dg0yt]

@Neumann-A did anyone try generating configs based on includes/libs installed?

This can't work well unless building in a minimal install tree, and AFAICS it can't handle system package dependencies.

(OT)
The minimal install tree would be good thing anyways, and wouldn't be too hard. It involves (time and space) cost for setup and teardown, but given the artifact cache, it shouldn't be too expensive. (Space could be gained from better cleanup in packages and buildtrees.) It might also solve the issue of vcpkg upgrade failing in the middle if the ultimate installed tree is only updated after successfully building and caching all required artifacts.