diff --git a/conan_v2.rst b/conan_v2.rst index ae8bb0be38c3..09a3453705e7 100644 --- a/conan_v2.rst +++ b/conan_v2.rst @@ -1,4 +1,3 @@ -.. _conan_v2: .. _conan2_migration_guide: diff --git a/configuration/download_cache.rst b/configuration/download_cache.rst index 49a7b405e143..f7985bb87bc1 100644 --- a/configuration/download_cache.rst +++ b/configuration/download_cache.rst @@ -66,7 +66,7 @@ Concurrency, multiple caches and CI The downloads cache implements exclusive locks for concurrency, so it can be shared among different concurrent Conan instances. This is a typical scenario in CI servers, in which each job uses a different Conan package cache (defined by ``CONAN_USER_HOME`` environment -variable). Every different Conan instance could configure its download cache to share the same storage. The download cache implements interprocess +variable). Every different Conan instance could configure its download cache to share the same storage. The download cache implements inter-process exclusive locks, so only 1 process will access at a time to a given cached artifact. If other processes needs the same artifact, they will wait until it is released, avoiding multiple downloads of the same file, even if they were requested almost simultaneously. diff --git a/creating_packages/define_abi_compatibility.rst b/creating_packages/define_abi_compatibility.rst index 6e81a1cf89e6..8e5655ca0b10 100644 --- a/creating_packages/define_abi_compatibility.rst +++ b/creating_packages/define_abi_compatibility.rst @@ -171,7 +171,8 @@ Compatible packages .. warning:: - This is an **experimental** feature subject to breaking changes in future releases. + Some parts of this feature are **deprecated**. Please refer to the :ref:`Migration Guidelines` + to find the feature that will carry over. The :ref:`method_compatibility` documented below is the current recommendation. The above approach defined 1 package ID for different input configurations. For example, all ``gcc`` versions in the range ``(v >= "4.5" and v < "5.0")`` will have exactly the same package ID, no matter what was the gcc version @@ -244,7 +245,7 @@ Check the :ref:`Compatible Compilers` section to see anoth **New conanfile.compatibility() method** The *conanfile.compatible_packages* will be substituted by the new -:ref:`method_compatibility` experimental method in Conan 2.0. This method allows you to +:ref:`method_compatibility` method in Conan 2.0. This method allows you to declare compatibility in a similar way: .. code-block:: python @@ -741,7 +742,7 @@ generated with the ``recipe_revision_mode`` can be resolved if no package for th Enabling full transitivity in package_id modes ++++++++++++++++++++++++++++++++++++++++++++++ -.. warning:: +.. attention:: This will become the default behavior in the future (Conan 2.0). It is recommended to activate it when possible (it might require rebuilding some packages, as their package IDs will change) diff --git a/creating_packages/external_repo.rst b/creating_packages/external_repo.rst index c09b8114e8c0..9ccf38aabb75 100644 --- a/creating_packages/external_repo.rst +++ b/creating_packages/external_repo.rst @@ -39,7 +39,8 @@ You can also use the :ref:`tools.Git ` class: .. warning:: - This is an **experimental** feature subject to breaking changes in future releases. + This is a **deprecated** feature. Please refer to the :ref:`Migration Guidelines` + to find the feature that replaces this one. .. code-block:: python diff --git a/creating_packages/getting_started.rst b/creating_packages/getting_started.rst index 9622d6025f71..5b0fc1206a73 100644 --- a/creating_packages/getting_started.rst +++ b/creating_packages/getting_started.rst @@ -14,9 +14,10 @@ packages from sources in your computer. It is not strictly required by Conan to create packages, you can use other build systems (as VS, Meson, Autotools and even your own) to do that, without any dependency to CMake. - Some of the features used in this section are **experimental**, like ``CMakeToolchain`` or ``cmake_layout()``, - and they might change in future releases. There are other alternative tools that are stable, please check - the :ref:`reference section` for more information. + + Some of the features used in this section are still **under development**, like ``CMakeToolchain`` or ``cmake_layout()``, + while they are recommended and usable and we will try not to break them in future releases, some breaking + changes might still happen if necessary to prepare for the *Conan 2.0 release*. Using the :command:`conan new` command will create a "Hello World" C++ library example project for us: diff --git a/creating_packages/package_approaches.rst b/creating_packages/package_approaches.rst index a04b2cb798a2..d393cf963e0a 100644 --- a/creating_packages/package_approaches.rst +++ b/creating_packages/package_approaches.rst @@ -1,6 +1,12 @@ Packaging Approaches ==================== +.. caution:: + + We are actively working to finalize the *Conan 2.0 Release*. Some of the information on this page references + **deprecated** features which will not be carried forward with the new release. It's important to check the + :ref:`Migration Guidelines` to ensure you are using the most up to date features. + Package recipes have three methods for controlling the package's binary compatibility and for implementing different packaging approaches: :ref:`method_package_id`, :ref:`method_build_id` and :ref:`method_package_info`. diff --git a/creating_packages/package_information.rst b/creating_packages/package_information.rst index 1d98d7a9258f..26f835fc0f53 100644 --- a/creating_packages/package_information.rst +++ b/creating_packages/package_information.rst @@ -3,6 +3,12 @@ Define the package information ============================== +.. caution:: + + We are actively working to finalize the *Conan 2.0 Release*. Some of the information on this page references + **deprecated** features which will not be carried forward with the new release. It's important to check the + :ref:`Migration Guidelines` to ensure you are using the most up to date features. + When creating a recipe to package a library, it is important to define the information about the package so consumers can get the information correctly. Conan achieves this by decoupling the information of the package from the format needed using :ref:`generators_reference`, that translate the generic information into the appropriate format file. @@ -21,7 +27,7 @@ like the location of the header files, library names, defines, flags... def package_info(self): self.cpp_info.includedirs = ["include/cool"] self.cpp_info.libs = ["libcool"] - self.cpp_info.defines= ["DEFINE_COOL=1"] + self.cpp_info.defines = ["DEFINE_COOL=1"] The package information is done using the attributes of the :ref:`cpp_info_attributes_reference` object. This information will be aggregated by Conan and exposed via ``self.deps_cpp_info`` to consumers and generators. @@ -45,10 +51,6 @@ Using Components If your package contains more than one library or you want to define separated components so consumers can have more granular information, you can use components in your :ref:`method_package_info` method. -.. warning:: - - This is a **experimental** feature subject to breaking changes in future releases. - When you are creating a Conan package, it is recommended to have only one library (*.lib*, *.a*, *.so*, *.dll*...) per package. However, especially with third-party projects like Boost, Poco or OpenSSL, they would contain several libraries inside. diff --git a/creating_packages/package_repo.rst b/creating_packages/package_repo.rst index cd416aed4eaa..2d64e191cd14 100644 --- a/creating_packages/package_repo.rst +++ b/creating_packages/package_repo.rst @@ -3,6 +3,12 @@ Recipe and Sources in the Same Repo =================================== +.. caution:: + + We are actively working to finalize the *Conan 2.0 Release*. Some of the information on this page references + **deprecated** features which will not be carried forward with the new release. It's important to check the + :ref:`Migration Guidelines` to ensure you are using the most up to date features. + Sometimes it is more convenient to have the recipe and source code together in the same repository. This is true especially if you are developing and packaging your own library, and not one from a third-party. @@ -101,9 +107,8 @@ Capturing the Remote and Commit: ``scm`` .. warning:: - This is an **experimental** feature subject to breaking changes in future releases. Although this - is an experimental feature, the use of the feature using ``scm_to_conandata`` is considered - stable. + This is a **deprecated** feature. Please refer to the :ref:`Migration Guidelines` + to find the feature that replaces this one. You can use the :ref:`scm attribute ` with the ``url`` and ``revision`` field set to ``auto``. When you export the recipe (or when :command:`conan create` is called) the exported recipe will capture the diff --git a/creating_packages/package_tools.rst b/creating_packages/package_tools.rst index badc65d30c60..205e57404ff0 100644 --- a/creating_packages/package_tools.rst +++ b/creating_packages/package_tools.rst @@ -1,7 +1,7 @@ .. _package_tools: Package Creator Tools -========================== +===================== Using Python (or just pure shell or bash) scripting, allows you to easily automate the whole package creation and testing process, for many different configurations. For example you could put the @@ -33,6 +33,14 @@ This is a pure Python script, not related to Conan, and should be run as such: $ python build.py + +Conan Package Tools +------------------- + +.. caution:: + + According to the project's README, there is no planned support for the upcoming *Conan 2.0 release*. + We have developed another FOSS tool for package creators, the **Conan Package Tools** to help you generate multiple binary packages from a package recipe. It offers a simple way to define the different configurations and to call :command:`conan test`. In addition to offering CI integration like **Travis CI, Appveyor and Bamboo**, for cloud-based automated diff --git a/creating_packages/toolchains.rst b/creating_packages/toolchains.rst index 87180911bb27..d389319f140f 100644 --- a/creating_packages/toolchains.rst +++ b/creating_packages/toolchains.rst @@ -1,23 +1,7 @@ Toolchains ========== -.. warning: - - This is a very **EXPERIMENTAL** feature, introduced in Conan 1.26, with limited functionality, - and subject to breaking changes in the future. - The current goal is to gather experience and feedback - to evolve it, while adding more build systems. - - Please try it and provide feedback at: https://github.com/conan-io/conan/issues - -.. warning: - - Starting in Conan 1.32 ``toolchain()`` method and ``toolchain`` attribute have been - deprecated. They will be removed in Conan 1.33, please use ``generate()`` instead of - ``toolchain()`` and ``generators = "ToolChainClassName"`` instead of - ``toolchain`` attribute. - -Toolchains are the new, experimental way to integrate with build systems in Conan. +Toolchains are the new way to integrate with build systems in Conan. Recipes can define a ``generate()`` method that will return an object which can generate files from the current configuration that can be used by the build systems. Conan *generators* provide information about dependencies, while toolchains provide a @@ -38,10 +22,9 @@ For example, for using the CMake toolchain this should be declared in the recipe generators = "CMakeToolchain" -.. note:: +.. tip:: - At the moment (Conan 1.32), the available built-in toolchains are ``CMakeToolchain``, - ``MSBuildToolchain`` and ``MesonToolchain``. + You can explore available toolchains in the :ref:`new tools section` But in the more general case, and if it needs any specific configuration beyond the default one: @@ -62,7 +45,7 @@ deduced from the current configuration of ``self.settings`` and ``self.options`` .. code:: python - from conans.tools import save + from conan.tools.files import save def generate(self): # Based on the self.settings, self.options, the user @@ -104,6 +87,3 @@ the documentation of each toolchain to check the associated build helper availab # NOTE: This is a simplified helper # Not all arguments attributes and methods might be available cmake = CMake(self) - - -To learn more about existing built-in toolchains, read the reference in :ref:`conan_tools`. diff --git a/developing_packages/editable_packages.rst b/developing_packages/editable_packages.rst index 0b145874e0ff..9cabcd2447f9 100644 --- a/developing_packages/editable_packages.rst +++ b/developing_packages/editable_packages.rst @@ -6,8 +6,10 @@ Packages in editable mode .. important:: This is a **tutorial** section. You are encouraged to execute these commands. - Some of the features used in this section are **experimental**, like ``layout()`` or ``CMakeToolchain``, - and they might change in future releases. Check the :ref:`reference section` for more information. + + Some of the features used in this section are still **under development**, like ``layout()`` or ``CMakeToolchain``, + while they are recommended and usable and we will try not to break them in future releases, some breaking + changes might still happen if necessary to prepare for the *Conan 2.0 release*. When working in big projects with several functionalities interconnected it is recommended to avoid the one-and-only huge project approach in favor of several libraries, each one specialized diff --git a/developing_packages/package_layout.rst b/developing_packages/package_layout.rst index 9179048a8e06..cd22d162769d 100644 --- a/developing_packages/package_layout.rst +++ b/developing_packages/package_layout.rst @@ -3,9 +3,14 @@ Package layout ============== -.. warning:: +.. important:: + + Some of the features used in this section are still **under development**, while they are + recommended and usable and we will try not to break them in future releases, some breaking + changes might still happen if necessary to prepare for the *Conan 2.0 release*. + +.. tip:: - This is an **experimental** feature subject to breaking changes in future releases. The ``layout()`` feature will be fully functional only in the new build system integrations (:ref:`in the conan.tools space `). If you are using other integrations, they might not fully support this feature. @@ -146,7 +151,7 @@ When we call ``conan create``, this is a simplified description of what happens: :caption: conanfile.py import os - from conans import ConanFile + from conan import ConanFile from conan.tools.cmake import CMake @@ -273,7 +278,7 @@ Let's see how we describe our project in the ``layout()`` method: :caption: conanfile.py import os - from conans import ConanFile + from conan import ConanFile from conan.tools.cmake import CMake diff --git a/devtools/build_requires.rst b/devtools/build_requires.rst index f00c3af1ecc3..b9d48ff3aa1f 100644 --- a/devtools/build_requires.rst +++ b/devtools/build_requires.rst @@ -95,10 +95,10 @@ profile, it will overwrite the tool requirements defined in package recipes that Build and Host contexts ----------------------- -.. warning:: +.. note:: - This section refers to the **experimental feature** that is activated when using ``--profile:build`` and ``--profile:host`` - in the command-line. It is currently under development, features can be added or removed in the following versions. + This section refers to the feature that is activated when using ``--profile:build`` and ``--profile:host`` + in the command-line. Conan v1.24 differentiates between the ``build`` context and the ``host`` context in the dependency graph (read more about @@ -269,7 +269,8 @@ same ``tool_requires`` package. Something like: .. code-block:: python - from conans import ConanFile + from conan import ConanFile + class Pkg(ConanFile): python_requires ="tool/[>=0.0]" tool_requires ="tool/[>=0.0]" @@ -284,11 +285,12 @@ be used to compute the ``package_id`` following the ``default_python_requires_id Testing tool_requires ---------------------- -.. warning:: +.. important:: - This is an **experimental** feature, subject to future breaking changes + This feature is still **under development**, while it is recommended and usable and we will try not to break them in future releases, + some breaking changes might still happen if necessary to prepare for the *Conan 2.0 release*. -Available since: `1.44.0 `_ +Available since: `1.44.0 `_ From Conan 1.44, it is possible to test ``tool_requires`` with the ``test_package`` functionality. In the ``test_package/conanfile.py``, specify the ``test_type = "explicit"`` and use the variable @@ -297,7 +299,7 @@ as a ``tool_requires`` or ``test_requires``: .. code-block:: python - from conans import ConanFile + from conan import ConanFile class Pkg(ConanFile): test_type = "explicit" @@ -311,7 +313,7 @@ then it is possible to specify: .. code-block:: python - from conans import ConanFile + from conan import ConanFile class Pkg(ConanFile): test_type = "explicit" diff --git a/devtools/create_installer_packages.rst b/devtools/create_installer_packages.rst index 76dc945bd927..87fab51674a9 100644 --- a/devtools/create_installer_packages.rst +++ b/devtools/create_installer_packages.rst @@ -3,6 +3,12 @@ Creating conan packages to install dev tools ============================================ +.. caution:: + + We are actively working to finalize the *Conan 2.0 Release*. Some of the information on this page references + **deprecated** features which will not be carried forward with the new release. It's important to check the + :ref:`Migration Guidelines` to ensure you are using the most up to date features. + One of the most useful features of Conan is to package executables like compilers or build tools and distribute them in a controlled way to the team of developers. This way Conan helps not only with the graph of dependencies of the application itself, but also with all the ecosystem needed to generate the @@ -82,10 +88,10 @@ This two simple declarations are enough to reuse this tool in the scenarios we a Using the tool packages in other recipes ---------------------------------------- -.. warning:: +.. note:: - This section refers to the **experimental feature** that is activated when using ``--profile:build`` and ``--profile:host`` - in the command-line. It is currently under development, features can be added or removed in the following versions. + This section refers to the feature that is activated when using ``--profile:build`` and ``--profile:host`` + in the command-line. These kind of tools are not usually part of the application graph itself, they are needed only to build the library, so diff --git a/devtools/running_packages.rst b/devtools/running_packages.rst index a112575ffe18..9da9f92efda3 100644 --- a/devtools/running_packages.rst +++ b/devtools/running_packages.rst @@ -3,6 +3,12 @@ Running and deploying packages ============================== +.. caution:: + + We are actively working to finalize the *Conan 2.0 Release*. Some of the information on this page references + **deprecated** features which will not be carried forward with the new release. It's important to check the + :ref:`Migration Guidelines` to ensure you are using the most up to date features. + Executables and applications including shared libraries can also be distributed, deployed and run with Conan. This might have some advantages compared to deploying with other systems: diff --git a/extending/python_requires.rst b/extending/python_requires.rst index a508fb120d0e..969e4fffd170 100644 --- a/extending/python_requires.rst +++ b/extending/python_requires.rst @@ -3,9 +3,10 @@ Python requires =============== -.. warning:: +.. important:: - This is an **experimental** feature subject to breaking changes in future releases. + This feature is still **under development**, while it is recommended and usable and we will try not to break them in future releases, + some breaking changes might still happen if necessary to prepare for the *Conan 2.0 release*. .. note:: diff --git a/extending/python_requires_legacy.rst b/extending/python_requires_legacy.rst index 15665f2fe3f0..0c9932963200 100644 --- a/extending/python_requires_legacy.rst +++ b/extending/python_requires_legacy.rst @@ -5,9 +5,13 @@ Python requires (legacy) .. warning:: - This feature has been superseded by the new :ref:`python_requires`. Even if this is an **experimental** - feature subject to breaking changes in future releases, this legacy ``python_requires`` syntax has not - been removed yet, but it will be removed in Conan 2.0. + + This is a **deprecated** feature by the new :ref:`python_requires`. Please refer to the :ref:`Migration Guidelines` + to find the feature that replaced this one. + + The new, **under development** While they are + recommended and usable and we will try not to break them in future releases, some breaking + changes might still happen if necessary to prepare for the *Conan 2.0 release*. The ``python_requires()`` feature is a very convenient way to share files and code between different recipes. A *Python Requires* is just like any other recipe, it is the way it is diff --git a/extending/template_system/info_graph.rst b/extending/template_system/info_graph.rst index 56cdc3af0174..31569c616a0c 100644 --- a/extending/template_system/info_graph.rst +++ b/extending/template_system/info_graph.rst @@ -6,9 +6,8 @@ Graph output for :command:`conan info` command .. warning:: - This has to be considered as an **experimental** feature, we might - change the context provided to these templates once we have more examples - from the community. + This is a **migrated** feature. Please refer to :ref:`conan_v2_graph_info` learn about the changes. + Most of the functionality remains intact and the main changes are to the command line. The :ref:`conan_info` command can generate a visualization of the dependency graph, it diff --git a/getting_started.rst b/getting_started.rst index 296c930c4fee..aae4cf0b2d92 100644 --- a/getting_started.rst +++ b/getting_started.rst @@ -3,6 +3,12 @@ Getting Started =============== +.. caution:: + + We are actively working to finalize the *Conan 2.0 Release*. Some of the information on this page references + **deprecated** features which will not be carried forward with the new release. It's important to check the + :ref:`Migration Guidelines` to ensure you are using the most up to date features. + Let's get started with an example: We are going to create an MD5 hash calculator app that uses one of the most popular C++ libraries: Poco_. @@ -178,10 +184,9 @@ An MD5 hash calculator using the Poco Libraries .. warning:: - There are prebuilt binaries for several mainstream compilers and versions available in Conan Center repository, - such as Visual Studio 14, 15, Linux GCC 4.9 and Apple Clang 3.5. Up to >130 different binaries for different - configurations can be available in ConanCenter. - But if your current configuration is not pre-built in ConanCenter, Conan will raise a "BinaryMissing" error. Please + There are prebuilt binaries for several mainstream compilers and versions available in ConanCenter repository, + a list is keep in `the repository's documentation `_ + If your current configuration is not pre-built in ConanCenter, Conan will raise a "Binary Missing" error. Please read carefully the error messages. You can build the binary package from sources using :command:`conan install .. --build=missing`, it will succeed if your configuration is supported by the recipe (it is possible that some ConanCenter recipes fail to build for some platforms). You will find more info in the :ref:`getting_started_other_configurations` section. @@ -189,6 +194,10 @@ An MD5 hash calculator using the Poco Libraries 6. Now let's create our build file. To inject the Conan information, include the generated *conanbuildinfo.cmake* file like this: + .. caution:: + + The :ref:`Creating Packages's Getting Started` is a more up-to-date version of this section. + .. code-block:: cmake :caption: **CMakeLists.txt** diff --git a/howtos/custom_generators.rst b/howtos/custom_generators.rst index 8c08ac7989e8..31d0cd8a07f9 100644 --- a/howtos/custom_generators.rst +++ b/howtos/custom_generators.rst @@ -3,6 +3,11 @@ How to create and share a custom generator with generator packages ================================================================== +.. warning:: + + This is a **deprecated** feature. Please refer to the :ref:`Migration Guidelines` + to find the feature that replaced this one. + There are several built-in generators, like ``cmake``, ``visual_studio``, ``xcode``... But what if your build system is not included or the existing built-in ones doesn't satisfy your needs? This **how to** will show you how to create a generator for Premake_ build system. @@ -233,7 +238,8 @@ Storing generators in the Conan local cache .. warning:: - This is an **experimental** feature subject to breaking changes in future releases. + This is a **deprecated** feature. Please refer to the :ref:`Migration Guidelines` + to find the feature that replaced this one. In addition to distributing them using Conan packages, custom generators can be stored in the generators folder in the Conan local cache (by default ``~/.conan/generators``). diff --git a/howtos/manage_cpp_standard.rst b/howtos/manage_cpp_standard.rst index 9ead2dabf0dd..f42718342176 100644 --- a/howtos/manage_cpp_standard.rst +++ b/howtos/manage_cpp_standard.rst @@ -1,13 +1,17 @@ .. _manage_cpp_standard: -How to manage C++ standard [EXPERIMENTAL] -========================================= +How to manage C++ standard +========================== -.. warning:: +.. caution:: - This is an **experimental** feature subject to breaking changes in future releases. - Previously, it was implemented as a first level setting ``cppstd``, we encourage - you to adopt the new subsetting and update your recipes if they were including the + We are actively working to finalize the *Conan 2.0 Release*. Some of the information on this page references + **deprecated** features which will not be carried forward with the new release. It's important to check the + :ref:`Migration Guidelines` to ensure you are using the most up to date features. + +.. tip:: + + We encourage you to adopt the new subsetting and update your recipes if they were including the deprecated one in its :ref:`settings_property` attribute. diff --git a/index.rst b/index.rst index 0a5a4f6df04d..b22ec34e89d8 100644 --- a/index.rst +++ b/index.rst @@ -6,7 +6,7 @@ Welcome to Conan C/C++ Package Manager Documentation Conan is universal and portable. It works in all operating systems including Windows, Linux, OSX, FreeBSD, Solaris, and others, and it can target any platform, including desktop, server, and cross-building for embedded and bare metal devices. It integrates with other tools like Docker, MinGW, WSL, and with all build systems such as CMake, MSBuild, -Makefiles, Meson, SCons. It can even integrate with any proprietary build systems. +Makefiles, Meson, SCons. It can even integrate with proprietary build systems. Conan is completely `free and open source `_ and fully decentralized. It has native integration with JFrog Artifactory, including the free @@ -21,7 +21,7 @@ upload and download binaries with the same commands and flows on every platform, in development and continuous integration. The binary compatibility can even be configured and customized on a per-package basis. Conan has a very large and active community, especially in `Github repositories `_ -and `Slack #conan channel `_. This community also creates and maintains +and the `Slack #conan channel `_. This community also creates and maintains packages in ConanCenter. Conan is used in production by thousands of companies, and consequently, it has a commitment to stability, with no breaking changes across all Conan 1.X versions. diff --git a/integrations/build_system/cmake.rst b/integrations/build_system/cmake.rst index 09109d045351..9824854cb89d 100644 --- a/integrations/build_system/cmake.rst +++ b/integrations/build_system/cmake.rst @@ -3,13 +3,17 @@ |cmake_logo| CMake ================== -.. note:: +Conan can be integrated with CMake using different generators, build helpers and custom *findXXX.cmake* files: - The new, experimental integration with CMake can be found in :ref:`conan_tools_cmake`. This is the integration that will - become the standard one in Conan 2.0, and the below generators and integrations will be deprecated and removed. +.. warning:: + This is a **deprecated** feature. Please refer to the :ref:`Migration Guidelines` + to find the feature that replaced this one. -Conan can be integrated with CMake using different generators, build helpers and custom *findXXX.cmake* files: + The new, **under development** integration with CMake can be found in :ref:`conan_tools_cmake`. This is the integration that will + become the standard one in Conan 2.0, and the below generators and integrations will be deprecated and removed. While they are + recommended and usable and we will try not to break them in future releases, some breaking + changes might still happen if necessary to prepare for the *Conan 2.0 release*. .. toctree:: diff --git a/integrations/build_system/cmake/cmake_find_package_multi_generator.rst b/integrations/build_system/cmake/cmake_find_package_multi_generator.rst index 88c39c57e06a..fff01a3d752b 100644 --- a/integrations/build_system/cmake/cmake_find_package_multi_generator.rst +++ b/integrations/build_system/cmake/cmake_find_package_multi_generator.rst @@ -8,7 +8,8 @@ .. warning:: - This is an **experimental** feature subject to breaking changes in future releases. + This is a **deprecated** feature. Please refer to the :ref:`Migration Guidelines` + to find the feature that replaced this one. This generator is similar to the :ref:`cmake_find_package` generator but it allows working with multi-configuration projects like ``Visual Studio`` with both ``Debug`` and ``Release``. But there are some differences: diff --git a/integrations/build_system/cmake/cmake_multi_generator.rst b/integrations/build_system/cmake/cmake_multi_generator.rst index 1ef4b9f6b884..65205192dc8b 100644 --- a/integrations/build_system/cmake/cmake_multi_generator.rst +++ b/integrations/build_system/cmake/cmake_multi_generator.rst @@ -3,6 +3,11 @@ ``cmake_multi`` generator ========================= +.. caution:: + + We are actively working to finalize the *Conan 2.0 Release*. Some of the information on this page references + **deprecated** features which will not be carried forward with the new release. It's important to check the + :ref:`Migration Guidelines` to ensure you are using the most up to date features. ``cmake_multi`` generator is intended for CMake multi-configuration environments, like Visual Studio and Xcode IDEs that do not configure for a specific ``build_type``, like Debug or Release, but rather can be used for both and switch among Debug and Release configurations with a combo box or similar control. @@ -37,7 +42,7 @@ switch among configurations: However, end consumers with heavy usage of the IDE, might want a multi-configuration build. The -``cmake_multi`` **experimental** generator is able to do that. First, both Debug and Release +``cmake_multi`` generator is able to do that. First, both Debug and Release dependencies have to be installed: .. code-block:: bash diff --git a/integrations/build_system/msbuild.rst b/integrations/build_system/msbuild.rst index 683ab03af378..ea9aab799207 100644 --- a/integrations/build_system/msbuild.rst +++ b/integrations/build_system/msbuild.rst @@ -4,18 +4,23 @@ |visual_logo| MSBuild (Visual Studio) ===================================== +.. warning:: + + This is a **deprecated** feature. Please refer to the :ref:`Migration Guidelines` + to find the feature that replaced this one. + + The new, **under development** Using the ``conan.tools.microsoft`` tools: ``MSBuildDeps``, ``MSBuildToolchain`` and + ``MSBuild`` helpers to generate properties files for your project, containing information about the project dependencies + and toolchain. Go to :ref:`conan_tools_microsoft` for more information. While they are recommended and usable and + we will try not to break them in future releases, some breaking changes might still happen if necessary to prepare for + the *Conan 2.0 release*. + If you are using CMake to generate your Visual Studio projects, this is not the right section, go to :ref:`cmake` instead. This section is about native integration with Microsoft MSBuild, using properties files. -Conan can be integrated with **MSBuild** natively, the build system of Visual Studio in different ways: +Conan can be integrated with **MSBuild** natively, the build system of Visual Studio by: - -- Using the ``conan.tools.microsoft`` tools: ``MSBuildDeps``, ``MSBuildToolchain`` and ``MSBuild`` helpers to generate properties - files for your project, containing information about the project dependencies and toolchain. This is the new integration that is - experimental but will become the standard one in Conan 2.0. Go to :ref:`conan_tools_microsoft` for more information. - Using the ``visual_studio`` or ``visual_studio_multi`` generators to create a MSBuild properties *conanbuildinfo.props* file. - This is the older integration, it is more stable now, but it wil be deprecated and removed in Conan 2.0. Keep reading this page for more information. - With *visual_studio* generator ------------------------------ diff --git a/integrations/ide/android_studio.rst b/integrations/ide/android_studio.rst index 6c00de325920..0d1c0872119a 100644 --- a/integrations/ide/android_studio.rst +++ b/integrations/ide/android_studio.rst @@ -86,30 +86,25 @@ that will call :command:`conan install` to install the requirements: - After the android block: -.. code-block:: text +.. code-block:: groovy - task conanInstall { - def buildDir = new File("app/conan_build") - buildDir.mkdirs() - // if you have problems running the command try to specify the absolute - // path to conan (Known problem in MacOSX) /usr/local/bin/conan -       def cmmd = "conan install ../conanfile.txt --profile android_21_arm_clang --build missing " - print(">> ${cmmd} \n") - - def sout = new StringBuilder(), serr = new StringBuilder() - def proc = cmmd.execute(null, buildDir) - proc.consumeProcessOutput(sout, serr) - proc.waitFor() - println "$sout $serr" - if(proc.exitValue() != 0){ - throw new Exception("out> $sout err> $serr" + "\nCommand: ${cmmd}") - } - } + task conanInstall(type: Exec) { + executable "conan" // on MacOSX may need to specify the absolute path, i.e. `/usr/local/bin/conan` + args = ["install", "conanfile.txt", + "--profile=android_21_arm_clang", + "--install-folder=${new File("conan_build").tap { mkdirs() }}", + "--build=missing"] + standardInput = System.in + } +9. Make your Android build depend on the NDK build, so Conan install is called each time you're building the Android app. In the same *.gradle* file: + +.. code-block:: groovy + preBuild.dependsOn conanInstall +10. Finally open the default example cpp library in ``app/src/main/cpp/native-lib.cpp`` and include some lines using your library. -9. Finally open the default example cpp library in ``app/src/main/cpp/native-lib.cpp`` and include some lines using your library. Be careful with the JNICALL name if you used another app name in the wizard: diff --git a/mastering/conanfile_py.rst b/mastering/conanfile_py.rst index 82b2622594c3..2c8569167277 100644 --- a/mastering/conanfile_py.rst +++ b/mastering/conanfile_py.rst @@ -1,11 +1,12 @@ -.. spelling:: - - mytimer - - Use conanfile.py for consumers =============================== +.. caution:: + + We are actively working to finalize the *Conan 2.0 Release*. Some of the information on this page references + **deprecated** features which will not be carried forward with the new release. It's important to check the + :ref:`Migration Guidelines` to ensure you are using the most up to date features. + You can use a ``conanfile.py`` for installing/consuming packages, even if you are not creating a package with it. You can also use the existing ``conanfile.py`` in a given package while developing it to install dependencies. There's no need to have a separate ``conanfile.txt``. Let's take a look at the complete ``conanfile.txt`` from the previous *timer* example with POCO library, in which we have added a couple of extra generators diff --git a/mastering/conditional.rst b/mastering/conditional.rst index 4f2731e4570e..6c16d9c21289 100644 --- a/mastering/conditional.rst +++ b/mastering/conditional.rst @@ -92,7 +92,7 @@ There are two approaches for this situation: .. note:: - For managing invalid configurations, please check the new experimental ``validate()`` method (:ref:`method_validate`). + For managing invalid configurations, please check the new ``validate()`` method (:ref:`method_validate`). - **Constrain settings inside a recipe**: diff --git a/mastering/envvars.rst b/mastering/envvars.rst index 05e51c295e5e..e12ef7875173 100644 --- a/mastering/envvars.rst +++ b/mastering/envvars.rst @@ -1,6 +1,12 @@ Environment variables ======================= +.. caution:: + + We are actively working to finalize the *Conan 2.0 Release*. Some of the information on this page references + **deprecated** features which will not be carried forward with the new release. It's important to check the + :ref:`Migration Guidelines` to ensure you are using the most up to date features. + There are several use cases for environment variables: - Conan global configuration environment variables (e.g. ``CONAN_COMPRESSION_LEVEL``). They can be configured in *conan.conf* or as system diff --git a/mastering/virtualenv.rst b/mastering/virtualenv.rst index 1a7fb9cd7491..2571b0f04282 100644 --- a/mastering/virtualenv.rst +++ b/mastering/virtualenv.rst @@ -4,6 +4,12 @@ Virtual Environments ==================== +.. caution:: + + We are actively working to finalize the *Conan 2.0 Release*. Some of the information on this page references + **deprecated** features which will not be carried forward with the new release. It's important to check the + :ref:`Migration Guidelines` to ensure you are using the most up to date features. + Conan offers three special Conan generators to create virtual environments: - ``virtualenv``: Declares the :ref:`self.env_info` variables of the requirements. diff --git a/migrating_to_2.0/commands.rst b/migrating_to_2.0/commands.rst index 0013de540c47..50b9fecc195a 100644 --- a/migrating_to_2.0/commands.rst +++ b/migrating_to_2.0/commands.rst @@ -31,7 +31,7 @@ Same changes as `conan install`: $ conan create . [--name=mylib] [--version=1.0] [-pr:b=build_profile] [-pr:h=host_profile] - +.. _conan_v2_graph_info: conan graph info ^^^^^^^^^^^^^^^^ diff --git a/migrating_to_2.0/general.rst b/migrating_to_2.0/general.rst index c882a82611bb..464b44ebb987 100644 --- a/migrating_to_2.0/general.rst +++ b/migrating_to_2.0/general.rst @@ -52,4 +52,9 @@ Work in progress Extensions ---------- -Work in progress \ No newline at end of file +Work in progress + +Environment Variables +--------------------- + +Work in progress diff --git a/migrating_to_2.0/recipes.rst b/migrating_to_2.0/recipes.rst index a1456d780f2e..4701f70d88b7 100644 --- a/migrating_to_2.0/recipes.rst +++ b/migrating_to_2.0/recipes.rst @@ -97,7 +97,7 @@ Settings ... def validate(self): - if self.info.settings.os == "Macos": + if self.settings.os == "Macos": raise ConanInvalidConfiguration("Macos not supported") @@ -182,9 +182,9 @@ In case the default value is ``None``, then it should be added as possible value The validate() method --------------------- -Use always the ``self.info.settings`` instead of ``self.settings`` and ``self.info.options`` instead of ``self.options``. -Otherwise, the compatibility mechanism won't be able to verify if the configurations of potential ``compatible`` packages -are valid. +Use always the ``self.settings`` instead of ``self.info.settings`` and ``self.options`` instead of ``self.info.options``. +The compatibility mechanism are not needed to verify if the configurations of potential ``compatible`` packages +are valid after the graph has been built. .. code-block:: python :caption: **From:** @@ -192,7 +192,7 @@ are valid. class Pkg(Conanfile): def validate(self): - if self.settings.os == "Windows": + if self.info.settings.os == "Windows": raise ConanInvalidConfiguration("This package is not compatible with Windows") @@ -202,12 +202,25 @@ are valid. class Pkg(Conanfile): def validate(self): - if self.info.settings.os == "Windows": + if self.settings.os == "Windows": raise ConanInvalidConfiguration("This package is not compatible with Windows") +.. note:: + + For recipes where settings are cleared, using ``self.settings`` is still valid. For example, + this applies to header only recipes that check for a specific ``self.settings.cppstd`` like: + + .. code-block:: python + + def package_id(self): + self.info.clear() + + def validate(self): + if self.settings.get_safe("compiler.cppstd"): + check_min_cppstd(self, 17) If you are not checking if the resulting binary is valid for the current configuration but need to check if a package -can be built or not for a specific configuration you must use the ``validate_build()`` method instead of using ``self.settings`` +can be built or not for a specific configuration you must use the ``validate_build()`` method using ``self.settings`` and ``self.options`` to perform the checks: diff --git a/reference.rst b/reference.rst index c1a752813244..0e34ddf1a1b9 100644 --- a/reference.rst +++ b/reference.rst @@ -20,4 +20,3 @@ Contents: reference/config_files reference/env_vars reference/hooks - reference/conan_v2_mode diff --git a/reference/build_helpers/cmake.rst b/reference/build_helpers/cmake.rst index 09c14799c04e..4be13b982e06 100644 --- a/reference/build_helpers/cmake.rst +++ b/reference/build_helpers/cmake.rst @@ -364,8 +364,8 @@ Parameters: .. _patch_config_paths: -patch_config_paths() [EXPERIMENTAL] -+++++++++++++++++++++++++++++++++++ +patch_config_paths() +++++++++++++++++++++ .. code-block:: python @@ -373,7 +373,8 @@ patch_config_paths() [EXPERIMENTAL] .. warning:: - This is an **experimental** feature subject to breaking changes in future releases. + This is a **deprecated** feature. Please refer to the :ref:`Migration Guidelines` + to find the feature that replaced this one. This method changes references to the absolute path of the installed package in exported CMake config files to the appropriate Conan variable. Method also changes references to other packages installation paths in export CMake config files to Conan variable diff --git a/reference/commands/consumer/install.rst b/reference/commands/consumer/install.rst index 54822b53d2d3..83f31c226fc7 100644 --- a/reference/commands/consumer/install.rst +++ b/reference/commands/consumer/install.rst @@ -155,27 +155,34 @@ generators. 1. ``config_options()`` 2. ``configure()`` -3. ``requirements()`` -4. ``package_id()`` -5. ``package_info()`` -6. ``deploy()`` +3. ``layout()`` +4. ``requirements()`` +5. ``package_id()`` +6. ``validate()`` +7. ``validate_build()`` +8. ``package_info()`` +9. ``deploy()`` Note this describes the process of installing a pre-built binary package. If the package has to be built, :command:`conan install --build` executes the following: 1. ``config_options()`` 2. ``configure()`` -3. ``requirements()`` -4. ``package_id()`` -5. ``build_requirements()`` -6. ``build_id()`` -7. ``system_requirements()`` -8. ``source()`` -9. ``imports()`` -10. ``build()`` -11. ``package()`` -12. ``package_info()`` -13. ``deploy()`` +3. ``layout()`` +4. ``requirements()`` +5. ``package_id()`` +6. ``validate()`` +7. ``validate_build()`` +8. ``build_requirements()`` +9. ``build_id()`` +10. ``system_requirements()`` +11. ``source()`` +12. ``generate()`` +13. ``imports()`` +14. ``build()`` +15. ``package()`` +16. ``package_info()`` +17. ``deploy()`` **Examples** @@ -331,9 +338,10 @@ because the consumer conanfile might not declare a `name` so it would be impossi folders ------- -.. warning:: +.. important:: - This is an **experimental** feature subject to breaking changes in future releases. + This feature is still **under development**, while it is recommended and usable and we will try not to break them in future releases, + some breaking changes might still happen if necessary to prepare for the *Conan 2.0 release*. The ``--output-folder`` define together with the ``layout()`` recipe @@ -346,9 +354,10 @@ such as ``CMakeToolchain`` or ``PkgConfigDeps`` will be created in the folder de conf ---- -.. warning:: +.. important:: - This is an **experimental** feature subject to breaking changes in future releases. + This feature is still **under development**, while it is recommended and usable and we will try not to break them in future releases, + some breaking changes might still happen if necessary to prepare for the *Conan 2.0 release*. With the :command:`-c` parameters you can define specific tool configurations. @@ -403,12 +412,14 @@ The ``install`` command accepts several arguments related to :ref:`lockfiles`_ + +The ``--build-require`` allows to install the package using the configuration and settings of the "build" context, as it was a ``build_require``. Lets see it with an example: We have a ``mycmake/1.0`` package, which bundles cmake executable, and we are cross-compiling from Windows @@ -434,11 +445,8 @@ as necessary without needing to change the profiles at all. --require-override ------------------ -.. warning:: - - This is an **experimental** feature subject to breaking changes in future releases. -New from **Conan 1.39** +Available since: `1.39.0 `_ The ``--require-override`` argument allows to inject an override requirement to the consumer conanfile being called by this command, that would be equivalent to: diff --git a/reference/commands/creator/create.rst b/reference/commands/creator/create.rst index b367fddbae1a..f36a5dc67019 100644 --- a/reference/commands/creator/create.rst +++ b/reference/commands/creator/create.rst @@ -186,34 +186,35 @@ Methods execution order :command:`conan create` executes methods of a *conanfile.py* in the following order: -1. ``export_sources()`` -2. ``config_options()`` -3. ``configure()`` -4. ``layout()`` -5. ``requirements()`` -6. ``package_id()`` -7. ``validate()`` -8. ``validate_build()`` -9. ``build_requirements()`` -10. ``build_id()`` -11. ``system_requirements()`` -12. ``source()`` -13. ``generate()`` -14. ``imports()`` -15. ``build()`` -16. ``package()`` -17. ``package_info()`` - -In case of installing a pre-built binary, steps from 8 to 16 will be skipped. Note that ``deploy()`` method is only used in +1. ``export()`` +2. ``export_sources()`` +3. ``config_options()`` +4. ``configure()`` +5. ``layout()`` +6. ``requirements()`` +7. ``package_id()`` +8. ``validate()`` +9. ``validate_build()`` +10. ``build_requirements()`` +11. ``build_id()`` +12. ``system_requirements()`` +13. ``source()`` +14. ``generate()`` +15. ``imports()`` +16. ``build()`` +17. ``package()`` +18. ``package_info()`` + +In case of installing a pre-built binary, steps from 9 to 17 will be skipped. Note that ``deploy()`` method is only used in :command:`conan install`. .. note:: Installation of binaries can be accelerated setting up parallel downloads with the ``general.parallel_download`` - **experimental** configuration in :ref:`conan_conf`. + **under development** configuration in :ref:`conan_conf`. -The ``--build-require``, new in Conan 1.37, is experimental. It allows to create the package using the +The ``--build-require``, new in Conan 1.37, allows to create the package using the configuration and settings of the "build" context, as it was a ``build_require``. This feature allows to create packages in a way that is consistent to the way they will be used later. When there is a ``test_package``, it is possible to use there the ``test_type="explicit"`` and ``self.test_requires(self.tested_reference_str)``. @@ -223,10 +224,6 @@ There is no need to provide it in the command line, :ref:`check "testing tool re --require-override ------------------ -.. warning:: - - This is an **experimental** feature subject to breaking changes in future releases. - -New from **Conan 1.39**. +Available since: `1.39.0 `_ This argument is the same, and has the same behavior as the :ref:`conan install command`. diff --git a/reference/commands/creator/export-pkg.rst b/reference/commands/creator/export-pkg.rst index 1433b735ea9e..f517e7b0318d 100644 --- a/reference/commands/creator/export-pkg.rst +++ b/reference/commands/creator/export-pkg.rst @@ -148,7 +148,7 @@ There are different scenarios where this command could look like useful: Packages created with ``conan export-pkg`` cannot be rebuilt from sources in the cache with the ``--build`` command line argument. It is possible to specify the class attribute ``build_policy="never"`` in this recipes -(this is an experimental feature, available from Conan 1.37) to avoid the ``--build=*`` or ``--build`` argument to try to rebuild them from sources +(this is an feature, available from Conan 1.37) to avoid the ``--build=*`` or ``--build`` argument to try to rebuild them from sources as part of a dependency graph. diff --git a/reference/commands/output/config.rst b/reference/commands/output/config.rst index c7f6c9bf5828..8abd68b1fd9e 100644 --- a/reference/commands/output/config.rst +++ b/reference/commands/output/config.rst @@ -5,9 +5,11 @@ Config output ------------- -.. warning:: +.. caution:: - This is an **experimental** feature subject to breaking changes in future releases. + We are actively working to finalize the *Conan 2.0 Release*. Some of the information on this page references + **deprecated** features which will not be carried forward with the new release. It's important to check the + :ref:`Migration Guidelines` to ensure you are using the most up to date features. The :command:`conan config home` provides a ``--json`` parameter to generate a file containing the information of the conan home directory. diff --git a/reference/conan_v2_mode.rst b/reference/conan_v2_mode.rst deleted file mode 100644 index c3a0fc1c3c94..000000000000 --- a/reference/conan_v2_mode.rst +++ /dev/null @@ -1,79 +0,0 @@ -.. _conan_v2_mode: - - -CONAN_V2_MODE -============= - -If defined in the environment, this variable will raise errors whenever a :ref:`Conan 2.0 ` deprecated feature -is used. It is a good mechanism to check the recipes future Conan 2.0 "compliance". Activating it should -not change behavior in any way, just raise error for deprecated things, but if it works, the same -result should be achieved. The number of deprecated features will increase in future Conan 1.X releases, -it could be a good practice to have it activated in some nightly job or the like, to report on current -status of your recipes. - -So, if you are ready to experiment add the variable ``CONAN_V2_MODE`` to your -environment and, please, report your feedback about it. - - -The following is a current known list of features that will change in Conan 2.0 and might start raising -errors if CONAN_V2_MODE is activated: - - -Changes related to the default configuration --------------------------------------------- - -* First level setting `cppstd` is removed. -* Revisions are enabled by default (adds ``revisions_enabled=1`` to *conan.conf*). -* No hooks activated by default. -* SCM data will be stored into *conandata.yml*. -* GCC >= 5 autodetected profile will use ``libstdc++11``. -* Directory ``/python`` is not added to Python ``sys.path``. - - -Changes in recipes ------------------- - -These changes could break existing recipes: - -* Forbid access to ``self.cpp_info`` in ``conanfile::package_id()`` method. -* Deprecate ``conanfile::config()`` method. -* Deprecate old ``python_requires`` syntax. -* Forbid access to ``self.info`` in ``conanfile.package()``. -* ``default_options`` are required to be a dictionary. -* Raise if setting ``cppstd`` appears in the recipe. -* Forbid ``self.settings`` and ``self.options`` in ``conanfile::source()`` method. -* Deprecate ``tools.msvc_build_command``. -* Deprecate ``tools.build_sln_command``. -* Deprecate ``cpp_info.cppflags`` (use ``cxxflags`` instead). -* Deprecate environment variables ``CONAN_USERNAME`` and ``CONAN_CHANNEL``. -* ``PYTHONPATH`` is not added automatically to the environment before running consumer functions. -* Attribute ``self.version`` is ensured to be a string in all the functions and scenarios. -* Access to member ``name`` in ``deps_cpp_info`` objects is forbidden, use ``get_name()`` - with the name of the generator. - - -Changes in profiles -------------------- - -Could break existing profiles: - -* Deprecate ``scopes`` section in profiles. - - -Other changes -------------- - -* Package name used by the ``pkg_config`` generator uses the same rules as any other generator. - Previously, if it was not explicit, it was using lowercase ``cpp_info.name`` when it was different - from the package name. -* If ``build_type`` or ``compiler`` are not defined when using build helpers Conan will raise an error. - -* New compiler detection algorithm is used (e.g. when running ``conan profile new --detect``). - Previously, `` --version`` was parsed to detect the compiler and its version. Now, using - ``CONAN_V2_MODE``, Conan will try to detect the compiler and its version via compiler's built-in macro definitions. - -.. note:: - - More changes will be added, some of them could be reverted and the behavior may - change without further noticing. If you are using ``CONAN_V2_MODE``, **thanks!** We - really appreciate your feedback about the future of Conan. diff --git a/reference/conanfile/methods.rst b/reference/conanfile/methods.rst index 58a3abf6fcd7..ae38e8c76191 100644 --- a/reference/conanfile/methods.rst +++ b/reference/conanfile/methods.rst @@ -522,9 +522,9 @@ Invalid configuration +++++++++++++++++++++ Conan allows the recipe creator to declare invalid configurations, those that are known not to work -with the library being packaged. There is an especial kind of exception that can be raised from -the ``validate()`` method to state this situation: ``conans.errors.ConanInvalidConfiguration``. Here -it is an example of a recipe for a library that doesn't support Windows operating system: +with the library being packaged. There is a special kind of exception that can be raised from +the ``validate()`` method to state this situation: ``conan.errors.ConanInvalidConfiguration``. Here +is an example of a recipe for a library that supports only Windows operating system: .. code-block:: python @@ -648,8 +648,8 @@ Available since: `1.51.0 The ``validate_build()`` method is used to verify if a configuration is valid for building a package. It is different from the ``validate()`` method that checks if the binary package is "impossible" or invalid for a given configuration. -In Conan 2.0, the ``validate()`` method should do the checks of the settings and options using the ``self.info.settings`` -and ``self.info.options``. +In Conan 2.0, the ``validate()`` method should do the checks of the settings and options using the ``self.settings`` +and ``self.options``. The ``validate_build()`` method has to use always the ``self.settings`` and ``self.options``: @@ -1581,11 +1581,9 @@ self.folders - **self.folders.source** (Defaulted to ""): Specifies a subfolder where the sources are. The ``self.source_folder`` attribute - inside the ``source(self)`` and ``build(self)`` methods will be set with this subfolder. But the *current working directory* - in the ``source(self)`` method will not include this subfolder, because it is intended to describe where the sources are after - downloading (zip, git...) them, not to force where the sources should be. As well, the `export_sources`, `exports` and `scm` sources - will be copied to the root source directory, being the **self.folders.source** variable the way to describe if the fetched sources - are still in a subfolder. + inside the ``source(self)`` and ``build(self)`` methods will be set with this subfolder. The *current working directory* + in the ``source(self)`` method will include this subfolder. The `export_sources`, `exports` and `scm` sources + will also be copied to the root source directory. It is used in the cache when running :command:`conan create` (relative to the cache source folder) as well as in a local folder when running :command:`conan build` (relative to the local current folder). diff --git a/reference/conanfile/tools.rst b/reference/conanfile/tools.rst index f8891845cf15..910d14e568ae 100644 --- a/reference/conanfile/tools.rst +++ b/reference/conanfile/tools.rst @@ -5,15 +5,15 @@ tools Tools are all things that can be imported and used in Conan recipes. -.. warning:: - - These tools are **experimental** and subject to breaking changes. - .. important:: This is the current design for Conan 2.0, and these will be the supported tools. Only the tools documented in this section will be available in Conan 2.0. + Some of the features used in this section are still **under development**, while they are + recommended and usable and we will try not to break them in future releases, some breaking + changes might still happen if necessary to prepare for the *Conan 2.0 release*. + Most of the utilities defined in "conan.tools" will require very soon to define both the "host" and "build" profiles. It is very recommended to start defining both profiles immediately to avoid future breaking. Furthermore, some features, like trying to cross-compile might not work at all if the "build" profile is not provided. diff --git a/reference/conanfile/tools/apple.rst b/reference/conanfile/tools/apple.rst index 12fc9d7e8bab..dc139722e927 100644 --- a/reference/conanfile/tools/apple.rst +++ b/reference/conanfile/tools/apple.rst @@ -3,10 +3,11 @@ conan.tools.apple ================= -.. warning:: +.. important:: - These tools are still **experimental** (so subject to breaking changes) but with very stable syntax. - We encourage their usage to be prepared for Conan 2.0. + Some of the features used in this section are still **under development**, while they are + recommended and usable and we will try not to break them in future releases, some breaking + changes might still happen if necessary to prepare for the *Conan 2.0 release*. .. _conan_tools_apple_xcodedeps: diff --git a/reference/conanfile/tools/cmake/cmake.rst b/reference/conanfile/tools/cmake/cmake.rst index 568ab530b8a6..fbf620c017f2 100644 --- a/reference/conanfile/tools/cmake/cmake.rst +++ b/reference/conanfile/tools/cmake/cmake.rst @@ -3,10 +3,11 @@ CMake ----- -.. warning:: +.. important:: - These tools are still **experimental** (so subject to breaking changes) but with very stable syntax. - We encourage their usage to be prepared for Conan 2.0. + Some of the features used in this section are still **under development**, while they are + recommended and usable and we will try not to break them in future releases, some breaking + changes might still happen if necessary to prepare for the *Conan 2.0 release*. Available since: `1.32.0 `_ diff --git a/reference/conanfile/tools/cmake/cmake_layout.rst b/reference/conanfile/tools/cmake/cmake_layout.rst index 9c499d25d996..64eca036115e 100644 --- a/reference/conanfile/tools/cmake/cmake_layout.rst +++ b/reference/conanfile/tools/cmake/cmake_layout.rst @@ -3,10 +3,11 @@ cmake_layout ------------ -.. warning:: +.. important:: - These tools are still **experimental** (so subject to breaking changes) but with very stable syntax. - We encourage their usage to be prepared for Conan 2.0. + Some of the features used in this section are still **under development**, while they are + recommended and usable and we will try not to break them in future releases, some breaking + changes might still happen if necessary to prepare for the *Conan 2.0 release*. Available since: `1.45.0 `_ diff --git a/reference/conanfile/tools/cmake/cmakedeps.rst b/reference/conanfile/tools/cmake/cmakedeps.rst index 6e9f6c2b8337..0cd0163b8d0f 100644 --- a/reference/conanfile/tools/cmake/cmakedeps.rst +++ b/reference/conanfile/tools/cmake/cmakedeps.rst @@ -3,10 +3,11 @@ CMakeDeps --------- -.. warning:: +.. important:: - These tools are still **experimental** (so subject to breaking changes) but with very stable syntax. - We encourage their usage to be prepared for Conan 2.0. + Some of the features used in this section are still **under development**, while they are + recommended and usable and we will try not to break them in future releases, some breaking + changes might still happen if necessary to prepare for the *Conan 2.0 release*. Available since: `1.33.0 `_ diff --git a/reference/conanfile/tools/cmake/cmaketoolchain.rst b/reference/conanfile/tools/cmake/cmaketoolchain.rst index 0bc15aa4119d..a37d3cfd0eee 100644 --- a/reference/conanfile/tools/cmake/cmaketoolchain.rst +++ b/reference/conanfile/tools/cmake/cmaketoolchain.rst @@ -3,10 +3,11 @@ CMakeToolchain -------------- -.. warning:: +.. important:: - These tools are still **experimental** (so subject to breaking changes) but with very stable syntax. - We encourage their usage to be prepared for Conan 2.0. + Some of the features used in this section are still **under development**, while they are + recommended and usable and we will try not to break them in future releases, some breaking + changes might still happen if necessary to prepare for the *Conan 2.0 release*. Available since: `1.32.0 `_ @@ -108,9 +109,10 @@ constructor .. code:: python - def __init__(self, conanfile): + def __init__(self, conanfile, generator=None): - ``conanfile``: the current recipe object. Always use ``self``. +- ``generator``: CMake generator to be used by cmake CLI (e.g. "Ninja"). By default it will use ``tools.cmake.cmaketoolchain:generator`` conf. preprocessor_definitions @@ -526,8 +528,6 @@ Blocks can be customized in different ways: tc.blocks["mynewblock"] = MyBlock -Recall that this is a very **experimental** feature, and these interfaces might change in the following releases. - For more information about these blocks, please have a look at the source code. diff --git a/reference/conanfile/tools/env.rst b/reference/conanfile/tools/env.rst index f38147ffd590..bc96925a9ce2 100644 --- a/reference/conanfile/tools/env.rst +++ b/reference/conanfile/tools/env.rst @@ -3,10 +3,11 @@ conan.tools.env =============== -.. warning:: +.. important:: - These tools are still **experimental** (so subject to breaking changes) but with very stable syntax. - We encourage their usage to be prepared for Conan 2.0. + Some of the features used in this section are still **under development**, while they are + recommended and usable and we will try not to break them in future releases, some breaking + changes might still happen if necessary to prepare for the *Conan 2.0 release*. .. toctree:: diff --git a/reference/conanfile/tools/env/environment.rst b/reference/conanfile/tools/env/environment.rst index 4374b7de52ee..071961853fbb 100644 --- a/reference/conanfile/tools/env/environment.rst +++ b/reference/conanfile/tools/env/environment.rst @@ -3,10 +3,11 @@ Environment =========== -.. warning:: +.. important:: - These tools are still **experimental** (so subject to breaking changes) but with very stable syntax. - We encourage their usage to be prepared for Conan 2.0. + Some of the features used in this section are still **under development**, while they are + recommended and usable and we will try not to break them in future releases, some breaking + changes might still happen if necessary to prepare for the *Conan 2.0 release*. Available since: `1.35.0 `_ diff --git a/reference/conanfile/tools/env/envvars.rst b/reference/conanfile/tools/env/envvars.rst index 64f5e21e0ddf..da4d833622b6 100644 --- a/reference/conanfile/tools/env/envvars.rst +++ b/reference/conanfile/tools/env/envvars.rst @@ -1,10 +1,11 @@ EnvVars ======= -.. warning:: +.. important:: - These tools are still **experimental** (so subject to breaking changes) but with very stable syntax. - We encourage their usage to be prepared for Conan 2.0. + Some of the features used in this section are still **under development**, while they are + recommended and usable and we will try not to break them in future releases, some breaking + changes might still happen if necessary to prepare for the *Conan 2.0 release*. ``EnvVars`` is a class that represents an instance of environment variables for a given system. diff --git a/reference/conanfile/tools/env/virtualbuildenv.rst b/reference/conanfile/tools/env/virtualbuildenv.rst index 5953b9eab6a8..fd75bf061f59 100644 --- a/reference/conanfile/tools/env/virtualbuildenv.rst +++ b/reference/conanfile/tools/env/virtualbuildenv.rst @@ -3,10 +3,11 @@ VirtualBuildEnv =============== -.. warning:: +.. important:: - These tools are still **experimental** (so subject to breaking changes) but with very stable syntax. - We encourage their usage to be prepared for Conan 2.0. + Some of the features used in this section are still **under development**, while they are + recommended and usable and we will try not to break them in future releases, some breaking + changes might still happen if necessary to prepare for the *Conan 2.0 release*. Available since: `1.39.0 `_ diff --git a/reference/conanfile/tools/env/virtualrunenv.rst b/reference/conanfile/tools/env/virtualrunenv.rst index 181e74624a6a..235358c04df1 100644 --- a/reference/conanfile/tools/env/virtualrunenv.rst +++ b/reference/conanfile/tools/env/virtualrunenv.rst @@ -3,10 +3,11 @@ VirtualRunEnv =============== -.. warning:: +.. important:: - These tools are still **experimental** (so subject to breaking changes) but with very stable syntax. - We encourage their usage to be prepared for Conan 2.0. + Some of the features used in this section are still **under development**, while they are + recommended and usable and we will try not to break them in future releases, some breaking + changes might still happen if necessary to prepare for the *Conan 2.0 release*. Available since: `1.39.0 `_ diff --git a/reference/conanfile/tools/files.rst b/reference/conanfile/tools/files.rst index 8ef0afae180a..fd1a0fb89762 100644 --- a/reference/conanfile/tools/files.rst +++ b/reference/conanfile/tools/files.rst @@ -3,10 +3,11 @@ conan.tools.files ================== -.. warning:: +.. important:: - These tools are still **experimental** (so subject to breaking changes) but with very stable syntax. - We encourage their usage to be prepared for Conan 2.0. + Some of the features used in this section are still **under development**, while they are + recommended and usable and we will try not to break them in future releases, some breaking + changes might still happen if necessary to prepare for the *Conan 2.0 release*. .. toctree:: diff --git a/reference/conanfile/tools/files/basic.rst b/reference/conanfile/tools/files/basic.rst index b13d34dd1ac8..77e368cb2c64 100644 --- a/reference/conanfile/tools/files/basic.rst +++ b/reference/conanfile/tools/files/basic.rst @@ -1,10 +1,11 @@ conan.tools.files basic operations ================================== +.. important:: -.. warning:: - - These tools are **experimental** and subject to breaking changes. + Some of the features used in this section are still **under development**, while they are + recommended and usable and we will try not to break them in future releases, some breaking + changes might still happen if necessary to prepare for the *Conan 2.0 release*. .. _conan_tools_files_copy: diff --git a/reference/conanfile/tools/files/checksum.rst b/reference/conanfile/tools/files/checksum.rst index aaa35abc8d4d..7a3edafe2229 100644 --- a/reference/conanfile/tools/files/checksum.rst +++ b/reference/conanfile/tools/files/checksum.rst @@ -1,10 +1,11 @@ conan.tools.files checksums =========================== +.. important:: -.. warning:: - - These tools are **experimental** and subject to breaking changes. + Some of the features used in this section are still **under development**, while they are + recommended and usable and we will try not to break them in future releases, some breaking + changes might still happen if necessary to prepare for the *Conan 2.0 release*. conan.tools.files.check_md5() diff --git a/reference/conanfile/tools/files/downloads.rst b/reference/conanfile/tools/files/downloads.rst index 07303df0dc10..60dc08eb5850 100644 --- a/reference/conanfile/tools/files/downloads.rst +++ b/reference/conanfile/tools/files/downloads.rst @@ -1,10 +1,11 @@ conan.tools.files downloads =========================== -.. warning:: - - These tools are **experimental** and subject to breaking changes. +.. important:: + Some of the features used in this section are still **under development**, while they are + recommended and usable and we will try not to break them in future releases, some breaking + changes might still happen if necessary to prepare for the *Conan 2.0 release*. conan.tools.files.get() diff --git a/reference/conanfile/tools/gnu/autotools.rst b/reference/conanfile/tools/gnu/autotools.rst index f37b54fafa6a..5c8080e4b1de 100644 --- a/reference/conanfile/tools/gnu/autotools.rst +++ b/reference/conanfile/tools/gnu/autotools.rst @@ -3,10 +3,11 @@ Autotools ========= -.. warning:: +.. important:: - These tools are still **experimental** (so subject to breaking changes) but with very stable syntax. - We encourage their usage to be prepared for Conan 2.0. + Some of the features used in this section are still **under development**, while they are + recommended and usable and we will try not to break them in future releases, some breaking + changes might still happen if necessary to prepare for the *Conan 2.0 release*. Available since: `1.35.0 `_ diff --git a/reference/conanfile/tools/gnu/autotoolsdeps.rst b/reference/conanfile/tools/gnu/autotoolsdeps.rst index 6a9716788b07..a6218762bf98 100644 --- a/reference/conanfile/tools/gnu/autotoolsdeps.rst +++ b/reference/conanfile/tools/gnu/autotoolsdeps.rst @@ -1,10 +1,11 @@ AutotoolsDeps ============= -.. warning:: +.. important:: - These tools are still **experimental** (so subject to breaking changes) but with very stable syntax. - We encourage their usage to be prepared for Conan 2.0. + Some of the features used in this section are still **under development**, while they are + recommended and usable and we will try not to break them in future releases, some breaking + changes might still happen if necessary to prepare for the *Conan 2.0 release*. Available since: `1.35.0 `_ diff --git a/reference/conanfile/tools/gnu/autotoolstoolchain.rst b/reference/conanfile/tools/gnu/autotoolstoolchain.rst index 2a720d5fa69c..6d3e2937f70b 100644 --- a/reference/conanfile/tools/gnu/autotoolstoolchain.rst +++ b/reference/conanfile/tools/gnu/autotoolstoolchain.rst @@ -3,10 +3,11 @@ AutotoolsToolchain ================== -.. warning:: +.. important:: - These tools are still **experimental** (so subject to breaking changes) but with very stable syntax. - We encourage their usage to be prepared for Conan 2.0. + Some of the features used in this section are still **under development**, while they are + recommended and usable and we will try not to break them in future releases, some breaking + changes might still happen if necessary to prepare for the *Conan 2.0 release*. Available since: `1.35.0 `_ diff --git a/reference/conanfile/tools/layout.rst b/reference/conanfile/tools/layout.rst index d7359997a601..3eccc4795182 100644 --- a/reference/conanfile/tools/layout.rst +++ b/reference/conanfile/tools/layout.rst @@ -3,10 +3,12 @@ conan.tools.layout ================== -.. warning:: +.. important:: - These tools are still **experimental** (so subject to breaking changes) but with very stable syntax. - We encourage their usage to be prepared for Conan 2.0. + Some of the features used in this section are still **under development**, while they are + recommended and usable and we will try not to break them in future releases, some breaking + changes might still happen if necessary to prepare for the *Conan 2.0 release*. + The ``layout()`` feature will be fully functional only in the new build system integrations (:ref:`in the conan.tools space `). If you are using other integrations, they might not fully support this feature. diff --git a/reference/conanfile/tools/microsoft.rst b/reference/conanfile/tools/microsoft.rst index 70ed1715ef3b..8b5a1e4721c9 100644 --- a/reference/conanfile/tools/microsoft.rst +++ b/reference/conanfile/tools/microsoft.rst @@ -7,10 +7,11 @@ conan.tools.microsoft These tools allow a native integration for Microsoft Visual Studio, natively (without using CMake, but using directly Visual Studio solutions, projects and property files). -.. warning:: +.. important:: - These tools are still **experimental** (so subject to breaking changes) but with very stable syntax. - We encourage their usage to be prepared for Conan 2.0. + Some of the features used in this section are still **under development**, while they are + recommended and usable and we will try not to break them in future releases, some breaking + changes might still happen if necessary to prepare for the *Conan 2.0 release*. .. _conan_tools_microsoft_msbuilddeps: diff --git a/reference/generators/cmake_find_package.rst b/reference/generators/cmake_find_package.rst index 54ddf4c27464..d122ebd36467 100644 --- a/reference/generators/cmake_find_package.rst +++ b/reference/generators/cmake_find_package.rst @@ -50,7 +50,7 @@ Being ```` the package name used in the reference (by default) or the This file uses `_BUILD_MODULES` values to include the files using the `include(...)` CMake directive after the targets are created. This makes functions or utilities exported by the package available for consumers just by setting `find_package()` in the -*CMakeLists.txt*. +*CMakeLists.txt*. Specify the modules that you want to be included in attribute ``cpp_info.build_modules`` in function ``package_info()``. Moreover, this also adjusts `CMAKE_MODULE_PATH` and `CMAKE_PREFIX_PATH` to the values declared by the package in ``cpp_info.buildirs``, so modules in those directories can be found. @@ -87,4 +87,4 @@ Moreover, a global target ``::`` will be declared with the f **Name conflicts**: If the name of the global target is the same for different packages, Conan will aggregate into this global target all the components from all those different packages. This means that this global target will contain information coming from different - packages. For the components themselves, a name conflict will result in one of them being inaccessible without further notice. \ No newline at end of file + packages. For the components themselves, a name conflict will result in one of them being inaccessible without further notice. diff --git a/reference/profiles.rst b/reference/profiles.rst index f0368003dbbd..c149c19ffa5d 100644 --- a/reference/profiles.rst +++ b/reference/profiles.rst @@ -120,7 +120,7 @@ They accept patterns too, like ``-s *@myuser/*``, which means that packages that compiler.version=4.9 compiler.libcxx=libstdc++11 -Also, as a **experimental** feature, `&` can be specified as the package name. It will apply only to the consumer conanfile (.py or .txt). +Also `&` can be specified as the package name. It will apply only to the consumer conanfile (.py or .txt). This is a special case because the consumer conanfile might not declare a `name` so it would be impossible to reference it. .. code-block:: text @@ -219,9 +219,10 @@ variables. Tools configurations -------------------- -.. warning:: +.. important:: - This is an **experimental** feature subject to breaking changes in future releases. + This feature is still **under development**, while it is recommended and usable and we will try not to break them in future releases, + some breaking changes might still happen if necessary to prepare for the *Conan 2.0 release*. Tools configurations can also be used in profile files and *global.conf* one. Profile values will have priority over globally defined ones in *global.conf*, and can be defined as: @@ -347,10 +348,6 @@ variables will be available: Build profiles and host profiles -------------------------------- -.. warning:: - - This is an **experimental feature** subject to breaking changes in future releases. - All the commands that take a profile as an argument, from Conan v1.24 are starting to accept two profiles with command line arguments ``-pr:h``/``--profile:host`` and ``-pr:b``/``--profile:build``. If both profiles are @@ -376,9 +373,10 @@ The default host profile can be defaulted as well using this configuration metho Profile templates ----------------- -.. warning:: +.. important:: - This is an **experimental** feature subject to breaking changes in future releases. + This feature is still **under development**, while it is recommended and usable and we will try not to break them in future releases, + some breaking changes might still happen if necessary to prepare for the *Conan 2.0 release*. From Conan 1.38 it is possible to use **jinja2** template engine for profiles. This feature is diff --git a/reference/tools.rst b/reference/tools.rst index 326ff5cb4016..8d0c32a63a78 100644 --- a/reference/tools.rst +++ b/reference/tools.rst @@ -8,6 +8,12 @@ Tools ===== +.. caution:: + + We are actively working to finalize the *Conan 2.0 Release*. Some of the information on this page references + **deprecated** features which will not be carried forward with the new release. It's important to check the + :ref:`Migration Guidelines` to ensure you are using the most up to date features. + Under the tools module there are several functions and utilities that can be used in Conan package recipes: .. code-block:: python @@ -1472,7 +1478,8 @@ tools.Git() .. warning:: - This is an **experimental** feature subject to breaking changes in future releases. + This is a **deprecated** feature. Please refer to the :ref:`Migration Guidelines` + to find the feature that replaced this one. .. code-block:: python @@ -1522,7 +1529,8 @@ tools.SVN() .. warning:: - This is an **experimental** feature subject to breaking changes in future releases. + This is a **deprecated** feature. Please refer to the :ref:`Migration Guidelines` + to find the feature that replaced this one. .. code-block:: python @@ -1847,7 +1855,8 @@ tools.intel_compilervars_command() .. warning:: - This is an **experimental** feature subject to breaking changes in future releases. + This is a **deprecated** feature. Please refer to the :ref:`Migration Guidelines` + to find the feature that replaced this one. .. code-block:: python @@ -1890,7 +1899,8 @@ tools.intel_compilervars_dict() .. warning:: - This is an **experimental** feature subject to breaking changes in future releases. + This is a **deprecated** feature. Please refer to the :ref:`Migration Guidelines` + to find the feature that replaced this one. .. code-block:: python @@ -1925,7 +1935,8 @@ tools.intel_compilervars() .. warning:: - This is an **experimental** feature subject to breaking changes in future releases. + This is a **deprecated** feature. Please refer to the :ref:`Migration Guidelines` + to find the feature that replaced this one. .. code-block:: python @@ -1949,7 +1960,8 @@ tools.intel_installation_path() .. warning:: - This is an **experimental** feature subject to breaking changes in future releases. + This is a **deprecated** feature. Please refer to the :ref:`Migration Guidelines` + to find the feature that replaced this one. .. code-block:: python @@ -2010,7 +2022,8 @@ tools.fix_symlinks(): .. warning:: - This is an **experimental** feature subject to breaking changes in future releases. + This is a **deprecated** feature. Please refer to the :ref:`Migration Guidelines` + to find the feature that replaced this one. .. code-block:: python diff --git a/systems_cross_building/cross_building.rst b/systems_cross_building/cross_building.rst index 999ab846edf3..56579a8340a5 100644 --- a/systems_cross_building/cross_building.rst +++ b/systems_cross_building/cross_building.rst @@ -62,6 +62,12 @@ the ``host`` platform when we are using it to build binaries. Cross building with Conan ------------------------- +.. caution:: + + We are actively working to finalize the *Conan 2.0 Release*. Some of the information on this page references + **deprecated** features which will not be carried forward with the new release. It's important to check the + :ref:`Migration Guidelines` to ensure you are using the most up to date features. + If you want to cross build a Conan package (for example using your Linux machine) to build the ``zlib`` Conan package for Windows, you need to tell Conan where to find your toolchain/cross compiler. @@ -138,8 +144,8 @@ Using tool requires .. warning:: - This section refers to the **experimental feature** that is activated when using ``--profile:build`` and ``--profile:host`` - in the command-line. It is currently under development, features can be added or removed in the following versions. + This section refers to the feature that is activated when using ``--profile:build`` and ``--profile:host`` + in the command-line. Instead of manually downloading the toolchain and creating a profile, you can create a Conan package @@ -150,6 +156,12 @@ this should be a regular recipe, for older versions some more work is needed. Conan v1.24 and newer ..................... +.. caution:: + + We are actively working to finalize the *Conan 2.0 Release*. Some of the information on this page references + **deprecated** features which will not be carried forward with the new release. It's important to check the + :ref:`Migration Guidelines` to ensure you are using the most up to date features. + A recipe with a toolchain is like any other recipe with a binary executable: .. code-block:: python @@ -306,12 +318,11 @@ if the tool requirements has other Conan dependencies. Host settings ``os_build``, ``arch_build``, ``os_target`` and ``arch_target`` +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ +.. caution:: -.. warning:: - - **These settings are being reviewed and might be deprecated in the future**, we encourage you to try not to use - them. If you need help with your use case, please `open an issue in the Conan repository `_ - and we will help you. + We are actively working to finalize the *Conan 2.0 Release*. Some of the information on this page references + **deprecated** features which will not be carried forward with the new release. It's important to check the + :ref:`Migration Guidelines` to ensure you are using the most up to date features. Before Conan v1.24 the recommended way to deal with cross building was to use some extra settings like @@ -547,6 +558,12 @@ Example of an Windows CE conan profile: Linux/Windows/macOS to Android .............................. +.. caution:: + + We are actively working to finalize the *Conan 2.0 Release*. Some of the information on this page references + **deprecated** features which will not be carried forward with the new release. It's important to check the + :ref:`Migration Guidelines` to ensure you are using the most up to date features. + Cross-building a library for Android is very similar to the previous examples, except the complexity of managing different architectures (armeabi, armeabi-v7a, x86, arm64-v8a) and the Android API levels. diff --git a/systems_cross_building/windows_subsystems.rst b/systems_cross_building/windows_subsystems.rst index 84d9757776ce..d8a0638f7d83 100644 --- a/systems_cross_building/windows_subsystems.rst +++ b/systems_cross_building/windows_subsystems.rst @@ -43,7 +43,14 @@ Running commands inside the subsystem self.win_bash _____________ -This is an experimental feature introduced in Conan 1.39. It supersedes the ``run(..., win_bash=True)`` argument but +Available since: `1.39.0 `_ + +.. important:: + + This feature is still **under development**, while it is recommended and usable and we will try not to break them in future releases, + some breaking changes might still happen if necessary to prepare for the *Conan 2.0 release*. + +This is a feature that supersedes the ``run(..., win_bash=True)`` argument but if the ``run(..., win_bash=True)`` is used, it will have priority so the compatibility with the previous behavior is guaranteed. @@ -101,6 +108,11 @@ run the ``configure`` and ``make`` commands inside a bash. Controlling the build environment --------------------------------- +.. warning:: + + Some parts of this section are **deprecated**. Please refer to the :ref:`Migration Guidelines` + to find the feature that will carry over. + Building software in a Windows subsystem for a different compiler than MinGW can sometimes be painful. The reason is how the subsystem finds your compiler/tools in your system. diff --git a/uploading_packages/artifactory/artifactory_ce.rst b/uploading_packages/artifactory/artifactory_ce.rst index 5180c7fa23d4..e923962c955f 100644 --- a/uploading_packages/artifactory/artifactory_ce.rst +++ b/uploading_packages/artifactory/artifactory_ce.rst @@ -15,7 +15,7 @@ Running Artifactory CE ---------------------- There are several ways to download and run Artifactory CE. The simplest one might be to download and unzip the -designated zip file, though other installers, including also installing from a Docker image. +designated zip file, though other installers, including also installing from a Docker image. The `Download Page `_ has a link for you to follow. When the file is unzipped, launch Artifactory by double clicking the artifactory.bat(Windows) or artifactory.sh script in the *app/bin* subfolder, depending on the OS. Artifactory comes with JDK bundled, please `read Artifactory requirements `_. diff --git a/uploading_packages/artifactory/conan_center_guide.rst b/uploading_packages/artifactory/conan_center_guide.rst index a338d0919872..7b375768e229 100644 --- a/uploading_packages/artifactory/conan_center_guide.rst +++ b/uploading_packages/artifactory/conan_center_guide.rst @@ -7,4 +7,4 @@ Contribution of packages to ConanCenter is done via pull requests to the Github https://github.com/conan-io/conan-center-index. The C3I (ConanCenter Continuous Integration) service will build binaries automatically from those pull requests, and once merged, will upload them to ConanCenter package repository. -Read more about how to `submit a pull request to conan-center-index `_ source repository. +Read more about how to `submit a pull request to conan-center-index `_ source repository. diff --git a/uploading_packages/remotes.rst b/uploading_packages/remotes.rst index a47b83c40443..45977caa2f9b 100644 --- a/uploading_packages/remotes.rst +++ b/uploading_packages/remotes.rst @@ -52,27 +52,5 @@ build service: C3I (ConanCenter Continuous Integration). To contribute packages to ConanCenter, read the :ref:`ConanCenter guide ` for more information. -conan-center [deprecated] -------------------------- - -**conan-center** was the official repository but is **no longer a default remote** in the Conan client and **its usage is completely -discouraged**. This documentation is kept here only for reference purposes. - -.. code-block:: bash - - $ conan-center: https://conan.bintray.com [Verify SSL: True] - -It contains all the packages that were uploaded to ConanCenter before July 1st (new packages are no longer uploaded to this remote), -as well as **legacy packages with full reference** (`zlib/1.2.11@conan/stable`). These package binaries were created by users in their own -Bintray repositories and included in this main repository. This flow of contributing packages to ConanCenter is no longer available and -packages are **not recommended** and should be considered as **legacy**. - -.. important:: - - This remote contains packages that are no longer maintained. We strongly encourage users to use `conancenter` and swift to the official - package references without **user/channel** - (`zlib/1.2.11@conan/stable` -> `zlib/1.2.11`). - - .. _`conancenter`: https://conan.io/center .. _Artifactory documentation: https://www.jfrog.com/confluence/display/JFROG/JFrog+Artifactory diff --git a/using_packages/conanfile_txt.rst b/using_packages/conanfile_txt.rst index 8edbb96d6df8..e9ea0c90d678 100644 --- a/using_packages/conanfile_txt.rst +++ b/using_packages/conanfile_txt.rst @@ -3,6 +3,12 @@ Installing dependencies ----------------------- +.. caution:: + + We are actively working to finalize the *Conan 2.0 Release*. Some of the information on this page references + **deprecated** features which will not be carried forward with the new release. It's important to check the + :ref:`Migration Guidelines` to ensure you are using the most up to date features. + In :ref:`Getting started` we used the :command:`conan install` command to download the **Poco** library and build an example. @@ -61,11 +67,6 @@ Where: Optional user/channel _____________________ - -.. warning:: - - This is an **experimental** feature subject to breaking changes in future releases. - If the package was created and uploaded without specifying the ``user`` and ``channel`` you can omit the ``user/channel`` when specifying a reference: @@ -246,6 +247,11 @@ example, in Linux, we could use the `objdump` tool and see the *Dynamic section* Imports ....... +.. warning:: + + This is a **deprecated** feature. Please refer to the :ref:`Migration Guidelines` + to find the feature that replaces this one. + There are some differences between shared libraries on Linux (\*.so), Windows (\*.dll) and MacOS (\*.dylib). The shared libraries must be located in a folder where they can be found, either by the linker, or by the OS runtime. diff --git a/using_packages/using_profiles.rst b/using_packages/using_profiles.rst index 2015e9617017..a2f4a9460fe2 100644 --- a/using_packages/using_profiles.rst +++ b/using_packages/using_profiles.rst @@ -3,6 +3,12 @@ Using profiles -------------- +.. caution:: + + We are actively working to finalize the *Conan 2.0 Release*. Some of the information on this page references + **deprecated** features which will not be carried forward with the new release. It's important to check the + :ref:`Migration Guidelines` to ensure you are using the most up to date features. + So far, we have used the default settings stored in ``~/.conan/profiles/default`` and defined custom values for some of them as command line arguments. However, in large projects, configurations can get complex, settings can be very different, and we need an easy way to switch between different configurations with different settings, options etc. diff --git a/using_packages/workflows.rst b/using_packages/workflows.rst index 360595fe367c..0e8877850263 100644 --- a/using_packages/workflows.rst +++ b/using_packages/workflows.rst @@ -3,6 +3,12 @@ Workflows ========= +.. caution:: + + We are actively working to finalize the *Conan 2.0 Release*. Some of the information on this page references + **deprecated** features which will not be carried forward with the new release. It's important to check the + :ref:`Migration Guidelines` to ensure you are using the most up to date features. + This section summarizes some possible layouts and workflows when using Conan together with other tools as an end-user for installing and consuming existing packages. To create your own packages, please refer to :ref:`Creating Packages `. diff --git a/versioning/introduction.rst b/versioning/introduction.rst index 2c8856d1eaae..0865b8da3a9b 100644 --- a/versioning/introduction.rst +++ b/versioning/introduction.rst @@ -80,12 +80,12 @@ for normal dependencies versions management.** .. note:: - From Conan 1.39, a new **experimental** syntax for requiring alias packages has been + From Conan 1.39, a new syntax for requiring alias packages has been introduced, to make explicit its usage and solve several issues with alias: .. code-block:: python - from conans import ConanFile + from conan import ConanFile class Pkg(ConanFile): # Previous syntax, implicit, nothing in the reference tells it is an alias