experimental->preview features (#3933)

* experimental->preview features

* review

* fix

Author: memsharded

common/preview_warning.inc

@@ -0,0 +1,6 @@
+.. note::
+
+    This feature is in **preview**. It means that it is very unlikely to be removed and unlikely to have
+    breaking changes. Maintainers will try as much as possible to not break it, and only do it if
+    very necessary.
+    See :ref:`the Conan stability<stability>` section for more information.

examples/commands/pkglists.rst

@@ -3,7 +3,7 @@
 Using packages-lists
 ====================
 
-.. include:: ../../common/experimental_warning.inc
+.. include:: ../../common/preview_warning.inc
 
 
 Packages lists are a powerful and convenient Conan feature that allows to automate and concatenate different Conan commands.

incubating.rst

@@ -24,6 +24,20 @@ This generator is designed as a replacement of the current ``CMakeDeps`` generat
 - Executables from ``requires`` can also be used in non cross-build scenarios. When a ``tool_requires`` to the same depependency exists, then those executables will have priority.
 - Creation of a new ``conan_cmakedeps_paths.cmake`` that contains definitions of ``<pkg>_DIR`` paths for direct finding of the dependencies. This file is also planned to be used in ``cmake-conan`` to extend its usage and avoid some current limitations due to the fact that a CMake driven installation cannot inject a toolchain later.
 
+The new fields that can be defined in the ``cpp_info`` or ``cpp_info.components``, besides the already defined in :ref:`CppInfo<conan_conanfile_model_cppinfo>` are:
+
+.. code-block:: python
+
+   # EXPERIMENTAL FIELDS, used exclusively by new CMakeDeps (-c tools.cmake.cmakedeps:new)
+   self.cpp_info.type  # The type of this artifact "shared-library", "static-library", etc (same as package_type)
+   self.cpp_info.location # full location (path and filename with extension) of the artifact
+   self.cpp_info.link_location  # Location of the import library for Windows .lib associated to a dll
+   self.cpp_info.languages # same as "languages" attribute, it can be "C", "C++"
+   self.cpp_info.exe  # Definition of an executable artifact
+
+These fields will be auto-deduced from the other ``cpp_info`` and ``components`` definitions, like the ``libs`` or ``libdirs`` fields, but the automatic deduction might have limitations. Defining them explicitly will inhibit the auto deduction and use the value as provided by the recipe.
+
+
 This feature is enabled with the ``-c tools.cmake.cmakedeps:new=will_break_next`` configuration. The value ``will_break_next`` will change in next releases to emphasize the fact that this feature is not suitable for usage beyond testing. Just by enabling this conf and forcing the build of packages that use ``CMakeDeps`` will trigger the usage of the new generator.
 
 Known current limitations:

reference/commands/formatters/graph_info_json_formatter.rst

@@ -13,9 +13,8 @@ This section is aimed to show one example of the JSON format output when using a
 
 The output shows the graph information processed by Conan in each command.
 
-.. warning::
 
-  This json output is **experimental** and subject to change.
+.. include:: ../../../common/preview_warning.inc
 
 
 The JSON output generated by :command:`conan graph info --require=zlib/1.2.11 -r=conancenter --format=json > graph.json`

reference/commands/version.rst

@@ -3,7 +3,7 @@
 conan version
 =============
 
-.. include:: ../../common/experimental_warning.inc
+.. include:: ../../common/preview_warning.inc
 
 .. autocommand::
     :command: conan version -h