Document CppInfo components and new attributes

[danimtb]

Docs for conan-io/conan#6653
Issue conan-io/conan#5090

[lasote]

I miss three ideas to be transmitted in the components section:

1. When you are creating a Conan package it is recommended to package only 1 library file (lib, a, so, dll...), but sometimes, especially with third-party projects like Boost, Poco or even OpenSSL, they contain several libraries inside.
2. Then it is sometimes necessary to model relations between the libraries of the same Conan package. Typically a library will be a component so if a library depends on another in the same package, you can declare the dependence relationship. The consumer will receive the correct linking order.
3. It will allow (NOT IMPLEMENTED YET) to the generators to be more advance in the future. Some examples:
   • The CMake find_package scripts could allow working with COMPONENTS.
   • The name field declared could determine the name of the xxx-config.cmake file or the name of the xxx.pc file for pkg-config and so on.

[memsharded]

2 important notes are needed here:

• That no global definition is possible if you are using components
• That the feature so far is not fully implemented, and at the moment is is only the definition in the conanfile, but is transparent and has no effect on consumers at all, and that is ongoing work.

[memsharded]

Actually I would prefer the reference the other way round:

• The attribute is only a placeholder, with a link
• The package_info() method is the section of the docs that contains all the detailed information about cpp_info and components.

Not to be changed now, but to have the idea in mind for the future.

[danimtb]

Ok, will take this into account for next refactors of the documentation

[jgsogo]

I'm not sure this is something we should mention. Probably all components should go in the same file (is it not possible for any generator?). If the components generate their own file, we can have collisions and Conan won't be able to handle them.

And, as this is totally speculative, I would vote to remove this example

[danimtb]

You are right. This was here when the feature was introduced together with the cpp_info.name attribute. But I think it is better to remove this from the reference right now and explain it better in a dedicated section in the future. Thanks!

[memsharded]

Yes, please remove that.

[jgsogo]

This is linking to this same section 🤔 Probably we can remove this seealso section, right?

[danimtb]

you are right

[fulara]

These docs dont explain at all how to use these paths in the consuming recipes, they are very arbitraty.

The documentation states:

    def build(self):
        # Get the include directories of the SSL component of openssl package
        self.deps_cpp_info["openssl"].components["ssl"].include_paths

And it does not link to anything anywhere how to propagate these in cmake or any generator.
I tried searching by lib_paths include_paths but to my knowledge there is no such documentation.

Can we get some real example somewhere please?

comment really to the work itself:
On top of that even though the package offers consumers if in the clients package someone uses CONAN_PKG::providing_pkg
they will depend on all of those