From fb0e37c20714712045b7942e4d51efea8c42ba04 Mon Sep 17 00:00:00 2001 From: Carlos Zoido Date: Wed, 22 Feb 2023 12:31:48 +0100 Subject: [PATCH 1/3] Remove warning about pre-release version (#3012) * remove warning * change target branch * output env vars * use inc * inc --- .ci/test.jenkins | 5 ++++- ...{experimental_warning.rst => experimental_warning.inc} | 2 -- .../cmake/cmake_toolchain/build_project_cmake_presets.rst | 2 +- .../cmake/cmake_toolchain/extend_own_cmake_presets.rst | 2 +- reference/commands/inspect.rst | 2 +- reference/config_files/profiles.rst | 2 +- reference/config_files/settings.rst | 2 +- reference/extensions/python_api/ConanAPI.rst | 2 +- reference/extensions/python_api/ConfigAPI.rst | 2 +- reference/extensions/python_api/DownloadAPI.rst | 2 +- reference/extensions/python_api/ExportAPI.rst | 2 +- reference/extensions/python_api/GraphAPI.rst | 2 +- reference/extensions/python_api/InstallAPI.rst | 2 +- reference/extensions/python_api/ListAPI.rst | 2 +- reference/extensions/python_api/NewAPI.rst | 2 +- reference/extensions/python_api/ProfilesAPI.rst | 2 +- reference/extensions/python_api/RemotesAPI.rst | 2 +- reference/extensions/python_api/RemoveAPI.rst | 2 +- reference/extensions/python_api/SearchAPI.rst | 2 +- reference/extensions/python_api/UploadAPI.rst | 2 +- tutorial.rst | 8 -------- .../{cmake_presets_note.rst => cmake_presets_note.inc} | 2 -- tutorial/developing_packages/editable_packages.rst | 2 +- .../local_package_development_flow.rst | 2 +- tutorial/developing_packages/package_layout.rst | 2 +- 25 files changed, 25 insertions(+), 34 deletions(-) rename common/{experimental_warning.rst => experimental_warning.inc} (88%) rename tutorial/{cmake_presets_note.rst => cmake_presets_note.inc} (98%) diff --git a/.ci/test.jenkins b/.ci/test.jenkins index 89d5b0f61fde..3acba0527745 100644 --- a/.ci/test.jenkins +++ b/.ci/test.jenkins @@ -3,7 +3,7 @@ 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' @@ -11,6 +11,9 @@ node('Linux') { 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 b/common/experimental_warning.inc similarity index 88% rename from common/experimental_warning.rst rename to common/experimental_warning.inc index 397bcd704c5e..a8d83c9bc39d 100644 --- a/common/experimental_warning.rst +++ b/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 index aa1c403d443e..25dc1c86f224 100644 --- 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 index f720aa16c913..670f06b20744 100644 --- 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 `_ in GitHub: diff --git a/reference/commands/inspect.rst b/reference/commands/inspect.rst index a67b90cce8ad..b2293e5f13b1 100644 --- 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 index e0063cb07dba..843e7ca7b339 100644 --- 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 index 3e55da950209..cc0f242ae638 100644 --- 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 index f6bc8038454b..d709a9bc8974 100644 --- 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 index 04790a9b7b10..78b5dcd7ba71 100644 --- 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 index b21b2cab573a..a6c55882f428 100644 --- 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 index e18750bddb0d..fdcb7e239d37 100644 --- 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 index 54642cf5c9e4..dceb6b4e7e1c 100644 --- 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 index defbc9035f40..98db6cd82694 100644 --- 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 index 1e65b86dcf8f..dd6a40129365 100644 --- 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 index abfe299f4b6c..c3ce5d97eee0 100644 --- 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 index e51db70db345..c85fe4218e5f 100644 --- 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 index dbfd374ae6c6..b2386b1af005 100644 --- 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 index b3a823ed11e3..187cf9d7e1f2 100644 --- 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 index df39dbc3a8b2..02cb3b68a7bd 100644 --- 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 index a380a13f8497..a949bfa389c1 100644 --- 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 index 07138c9c8101..54b1228dcc83 100644 --- 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 `_ to be compatible with - Conan 2.0. - - .. toctree:: :maxdepth: 2 diff --git a/tutorial/cmake_presets_note.rst b/tutorial/cmake_presets_note.inc similarity index 98% rename from tutorial/cmake_presets_note.rst rename to tutorial/cmake_presets_note.inc index 952b28712bef..b72804f85083 100644 --- a/tutorial/cmake_presets_note.rst +++ b/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/developing_packages/editable_packages.rst b/tutorial/developing_packages/editable_packages.rst index de1e8a2c603d..a404c37d0f8a 100644 --- 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 index 57f66639d015..bd82d8d46bb6 100644 --- 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 index 59f389cf836a..b4513a39e410 100644 --- 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: From 9fbc69b6569c5480118bb34eb732d34a15ee2e7d Mon Sep 17 00:00:00 2001 From: James Date: Wed, 22 Feb 2023 13:55:58 +0100 Subject: [PATCH 2/3] added FAQ invalid settings (#3013) --- knowledge/faq.rst | 34 ++++++++++++++++++++++++++++++++++ 1 file changed, 34 insertions(+) diff --git a/knowledge/faq.rst b/knowledge/faq.rst index fb84a48fdf06..13e93e67acb6 100644 --- a/knowledge/faq.rst +++ b/knowledge/faq.rst @@ -61,4 +61,38 @@ overcome this error: `_ + +.. _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/ From 6527af77f4804209c193066fa188c1c8c3ccf3ca Mon Sep 17 00:00:00 2001 From: czoido Date: Thu, 23 Feb 2023 14:23:18 +0100 Subject: [PATCH 3/3] update docs --- tutorial/conan_repositories.rst | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/tutorial/conan_repositories.rst b/tutorial/conan_repositories.rst index a1ac75f13a0b..2f46fb4b4fe1 100644 --- 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