Merge branch 'release/2.0' into develop2

conan-io · Feb 23, 2023 · 36f8acd · 36f8acd
2 parents 40fd000 + 6527af7
commit 36f8acd
Show file tree

Hide file tree

Showing 27 changed files with 64 additions and 39 deletions.
diff --git a/.ci/test.jenkins b/.ci/test.jenkins
@@ -3,14 +3,17 @@
 node('Linux') {
 
     boolean publishDocs = env.BRANCH_NAME.startsWith("release/2.")
-    def targetBranch = env.CHANGE_BRANCH ? env.CHANGE_BRANCH : env.BRANCH_NAME
+    def targetBranch = env.CHANGE_TARGET ? env.CHANGE_TARGET : env.BRANCH_NAME
 
     // We also have to clone conan sources for the sphinx autodoc extension
     def conanBranch = targetBranch.startsWith("release/2.") ? targetBranch : 'develop2'
     def conan_repo_url = 'https://github.com/conan-io/conan.git'
 
     echo "Docs target branch: ${targetBranch}"
     echo "Conan target branch: ${conanBranch}"
+    echo "env.BRANCH_NAME: ${env.BRANCH_NAME}"
+    echo "env.CHANGE_BRANCH: ${env.CHANGE_BRANCH}"
+    echo "env.CHANGE_TARGET: ${env.CHANGE_TARGET}"
 
     stage('Clone sources') {
         checkout scm

diff --git a/common/experimental_warning.rst → common/experimental_warning.inc b/common/experimental_warning.rst → common/experimental_warning.inc
@@ -1,4 +1,2 @@
-:orphan:
-
 .. warning::
     This feature is experimental and subject to breaking changes.
diff --git a/examples/tools/cmake/cmake_toolchain/build_project_cmake_presets.rst b/examples/tools/cmake/cmake_toolchain/build_project_cmake_presets.rst
@@ -43,7 +43,7 @@ The ``CMakePresets.json`` contain information about the ``conan_toolchain.cmake`
 and even the ``binaryDir`` set with the output directory.
 
 
-.. include:: ../../../../tutorial/cmake_presets_note.rst
+.. include:: ../../../../tutorial/cmake_presets_note.inc
 
 
 If you are using a multi-configuration generator:

diff --git a/examples/tools/cmake/cmake_toolchain/extend_own_cmake_presets.rst b/examples/tools/cmake/cmake_toolchain/extend_own_cmake_presets.rst
@@ -6,7 +6,7 @@ CMakeToolchain: Extending your CMakePresets with Conan generated ones
 In this example we are going to see how to extend your own CMakePresets to include Conan
 generated ones.
 
-.. include:: ../../../../tutorial/cmake_presets_note.rst
+.. include:: ../../../../tutorial/cmake_presets_note.inc
 
 Please, first of all, clone the sources to recreate this project. You can find them in the
 `examples2.0 repository <https://github.com/conan-io/examples2>`_ in GitHub:

diff --git a/knowledge/faq.rst b/knowledge/faq.rst
@@ -61,4 +61,38 @@ overcome this error:
   <https://github.com/conan-io/conan-center-index>`_
 
 
+
+.. _error_invalid_setting:
+
+ERROR: Invalid setting
+^^^^^^^^^^^^^^^^^^^^^^
+
+It might happen sometimes, when you specify a setting not present in the defaults
+that you receive a message like this:
+
+.. code-block:: bash
+
+    $ conan install . -s compiler.version=4.19 ...
+
+    ERROR: Invalid setting '4.19' is not a valid 'settings.compiler.version' value.
+    Possible values are ['4.4', '4.5', '4.6', '4.7', '4.8', '4.9', '5.1', '5.2', '5.3', '5.4', '6.1', '6.2']
+
+
+This doesn't mean that such compiler version is not supported by Conan, it is just that it is not present in the actual
+defaults settings. You can find in your user home folder ``~/.conan2/settings.yml`` a settings file that you
+can modify, edit, add any setting or any value, with any nesting if necessary. See :ref:`reference_config_files_settings_yml` to learn
+how you can customize your settings to model your binaries at your will.
+
+As long as your team or users have the same settings (``settings.yml`` and ``settings_user.yml`` an be easily shared with the
+``conan config install`` command), everything will work. The *settings.yml* file is just a
+mechanism so users agree on a common spelling for typical settings. Also, if you think that some settings would
+be useful for many other conan users, please submit it as an issue or a pull request, so it is included in future
+releases.
+
+It is possible that some built-in helper or integrations, like ``CMake`` or ``CMakeToolchain`` will not understand the new added settings,
+don't use them or even fail if you added some new unexpected value to existing settings. 
+Such helpers as ``CMake`` are simple utilities to translate from conan settings to the respective
+build system syntax and command line arguments, so they can be extended or replaced with your own
+one that would handle your own private settings.
+
 .. _`Cpplang Slack`: https://cppalliance.org/slack/
diff --git a/reference/commands/inspect.rst b/reference/commands/inspect.rst
@@ -3,7 +3,7 @@
 conan inspect
 =============
 
-.. include:: ../../common/experimental_warning.rst
+.. include:: ../../common/experimental_warning.inc
 
 .. code-block:: text
 

diff --git a/reference/config_files/profiles.rst b/reference/config_files/profiles.rst
@@ -217,7 +217,7 @@ List of ``tool_requires`` required by your recipe or its dependencies:
 [system_tools]
 +++++++++++++++
 
-.. include:: ../../common/experimental_warning.rst
+.. include:: ../../common/experimental_warning.inc
 
 This section is similar to the previous one, **[tool_requires]**, but it's intended to list only the tool requires
 that are already in your own system and you don't want Conan to search for, neither remotely nor locally.

diff --git a/reference/config_files/settings.rst b/reference/config_files/settings.rst
@@ -208,7 +208,7 @@ to the ``update`` subsetting in ``settings.yml``.
 intel-cc
 ++++++++
 
-.. include:: ../../common/experimental_warning.rst
+.. include:: ../../common/experimental_warning.inc
 
 This compiler is aimed to handle the new Intel oneAPI DPC++/C++/Classic compilers. Instead of having *n* different compilers,
 you have 3 different **modes** of working:

diff --git a/reference/extensions/python_api/ConanAPI.rst b/reference/extensions/python_api/ConanAPI.rst
@@ -3,7 +3,7 @@
 Conan API Reference
 ===================
 
-.. include:: ../../../common/experimental_warning.rst
+.. include:: ../../../common/experimental_warning.inc
 
 .. currentmodule:: conan.api.conan_api
 

diff --git a/reference/extensions/python_api/ConfigAPI.rst b/reference/extensions/python_api/ConfigAPI.rst
@@ -1,7 +1,7 @@
 Config API
 ==========
 
-.. include:: ../../../common/experimental_warning.rst
+.. include:: ../../../common/experimental_warning.inc
 
 .. currentmodule:: conan.api.subapi.config
 

diff --git a/reference/extensions/python_api/DownloadAPI.rst b/reference/extensions/python_api/DownloadAPI.rst
@@ -1,7 +1,7 @@
 Download API
 ============
 
-.. include:: ../../../common/experimental_warning.rst
+.. include:: ../../../common/experimental_warning.inc
 
 .. currentmodule:: conan.api.subapi.download
 

diff --git a/reference/extensions/python_api/ExportAPI.rst b/reference/extensions/python_api/ExportAPI.rst
@@ -1,7 +1,7 @@
 Export API
 ==========
 
-.. include:: ../../../common/experimental_warning.rst
+.. include:: ../../../common/experimental_warning.inc
 
 .. currentmodule:: conan.api.subapi.export
 

diff --git a/reference/extensions/python_api/GraphAPI.rst b/reference/extensions/python_api/GraphAPI.rst
@@ -1,7 +1,7 @@
 Graph API
 =========
 
-.. include:: ../../../common/experimental_warning.rst
+.. include:: ../../../common/experimental_warning.inc
 
 .. currentmodule:: conan.api.subapi.graph
 

diff --git a/reference/extensions/python_api/InstallAPI.rst b/reference/extensions/python_api/InstallAPI.rst
@@ -1,7 +1,7 @@
 Install API
 ===========
 
-.. include:: ../../../common/experimental_warning.rst
+.. include:: ../../../common/experimental_warning.inc
 
 .. currentmodule:: conan.api.subapi.install
 

diff --git a/reference/extensions/python_api/ListAPI.rst b/reference/extensions/python_api/ListAPI.rst
@@ -1,7 +1,7 @@
 List API
 ========
 
-.. include:: ../../../common/experimental_warning.rst
+.. include:: ../../../common/experimental_warning.inc
 
 .. currentmodule:: conan.api.subapi.list
 

diff --git a/reference/extensions/python_api/NewAPI.rst b/reference/extensions/python_api/NewAPI.rst
@@ -1,7 +1,7 @@
 New API
 =======
 
-.. include:: ../../../common/experimental_warning.rst
+.. include:: ../../../common/experimental_warning.inc
 
 .. currentmodule:: conan.api.subapi.new
 

diff --git a/reference/extensions/python_api/ProfilesAPI.rst b/reference/extensions/python_api/ProfilesAPI.rst
@@ -1,7 +1,7 @@
 Profiles API
 ============
 
-.. include:: ../../../common/experimental_warning.rst
+.. include:: ../../../common/experimental_warning.inc
 
 .. currentmodule:: conan.api.subapi.profiles
 

diff --git a/reference/extensions/python_api/RemotesAPI.rst b/reference/extensions/python_api/RemotesAPI.rst
@@ -1,7 +1,7 @@
 Remotes API
 ===========
 
-.. include:: ../../../common/experimental_warning.rst
+.. include:: ../../../common/experimental_warning.inc
 
 .. currentmodule:: conan.api.subapi.remotes
 

diff --git a/reference/extensions/python_api/RemoveAPI.rst b/reference/extensions/python_api/RemoveAPI.rst
@@ -1,7 +1,7 @@
 Remove API
 ==========
 
-.. include:: ../../../common/experimental_warning.rst
+.. include:: ../../../common/experimental_warning.inc
 
 .. currentmodule:: conan.api.subapi.remove
 

diff --git a/reference/extensions/python_api/SearchAPI.rst b/reference/extensions/python_api/SearchAPI.rst
@@ -1,7 +1,7 @@
 Search API
 ==========
 
-.. include:: ../../../common/experimental_warning.rst
+.. include:: ../../../common/experimental_warning.inc
 
 .. currentmodule:: conan.api.subapi.search
 

diff --git a/reference/extensions/python_api/UploadAPI.rst b/reference/extensions/python_api/UploadAPI.rst
@@ -1,7 +1,7 @@
 Upload API
 ==========
 
-.. include:: ../../../common/experimental_warning.rst
+.. include:: ../../../common/experimental_warning.inc
 
 .. currentmodule:: conan.api.subapi.upload
 

diff --git a/tutorial.rst b/tutorial.rst
@@ -8,14 +8,6 @@ The purpose of this section is to guide you through the most important Conan fea
 practical examples. From using libraries already packaged by Conan, to how to package your
 libraries and store them in a remote server alongside all the precompiled binaries.
 
-.. important::
-
-    This tutorial is part of the Conan 2.0 documentation. Conan 2.0 is still in alpha state. Some
-    details, like the repositories and libraries used for the tutorial, will change as we
-    update the `current 1.X Conan packages <https://conan.io/center/>`_ to be compatible with
-    Conan 2.0.
-
-
 .. toctree::
    :maxdepth: 2
 

diff --git a/tutorial/cmake_presets_note.rst → tutorial/cmake_presets_note.inc b/tutorial/cmake_presets_note.rst → tutorial/cmake_presets_note.inc
@@ -1,5 +1,3 @@
-:orphan:
-
 .. note::
 
     We use CMake presets in this example. This requires CMake >= 3.23 because the

diff --git a/tutorial/conan_repositories.rst b/tutorial/conan_repositories.rst
@@ -11,11 +11,11 @@ In this section we cover how you can use the Conan repositories to upload your
 recipes and binaries and store them for later use on another machine, project, or for
 sharing purposes.
 
-First we will cover how you can setup a Conan repository locally or cloud-hosted
-(you can skip this part if you already have a Conan remote configured). Then we will
-explain how to upload packages to your own repositories and how to operate when you have
-multiple Conan remotes configured. Finally, we will briefly cover how you can contribute
-to the Conan Center central repository. 
+First we will cover how you can setup a Conan repository locally (you can skip this part
+if you already have a Conan remote configured). Then we will explain how to upload
+packages to your own repositories and how to operate when you have multiple Conan remotes
+configured. Finally, we will briefly cover how you can contribute to the Conan Center
+central repository. 
 
 .. toctree::
    :maxdepth: 2

diff --git a/tutorial/developing_packages/editable_packages.rst b/tutorial/developing_packages/editable_packages.rst
@@ -79,7 +79,7 @@ depending on the platform and generator used.
 
 Now that the ``say/1.0`` package is in editable mode, let's build it locally:
 
-.. include:: ../cmake_presets_note.rst
+.. include:: ../cmake_presets_note.inc
 
 .. code-block:: bash
 

diff --git a/tutorial/developing_packages/local_package_development_flow.rst b/tutorial/developing_packages/local_package_development_flow.rst
@@ -241,7 +241,7 @@ preset. Let's try it:
 You can check that the results of invoking CMake directly are equivalent to the ones we
 got using the :command:`conan build` command.
 
-.. include:: ../cmake_presets_note.rst
+.. include:: ../cmake_presets_note.inc
 
 conan export-pkg
 ----------------

diff --git a/tutorial/developing_packages/package_layout.rst b/tutorial/developing_packages/package_layout.rst
@@ -21,7 +21,7 @@ Please, first of all, clone the sources to recreate this project. You can find t
     $ git clone https://github.com/conan-io/examples2.git
     $ cd examples2/tutorial/developing_packages/package_layout
 
-.. include:: ../cmake_presets_note.rst
+.. include:: ../cmake_presets_note.inc
 
 As you can see, the main folder structure is the same: