From bcba0cc1d0e41cba5af278e5d538cfe6ff1d57d6 Mon Sep 17 00:00:00 2001 From: "Javier G. Sogo" Date: Fri, 13 Sep 2019 08:16:06 +0200 Subject: [PATCH] add deprecation warnings to user/channel (#1413) --- reference/conanfile/attributes.rst | 35 ++++++++++++++++++++---------- reference/env_vars.rst | 17 ++++++++++----- 2 files changed, 35 insertions(+), 17 deletions(-) diff --git a/reference/conanfile/attributes.rst b/reference/conanfile/attributes.rst index c56781dbe853..ccb701f63142 100644 --- a/reference/conanfile/attributes.rst +++ b/reference/conanfile/attributes.rst @@ -147,10 +147,11 @@ This is an optional attribute. user, channel ------------- -The fields ``user`` and ``channel`` can be accessed from within a ``conanfile.py``. -Though their usage is usually not encouraged, it could be useful in different cases, -e.g. to define requirements with the same user and -channel as the current package, which could be achieved with something like: +**These fields are optional in a Conan reference**, they could be useful to identify a forked recipe +from the community with changes specific for your company. Using these fields you may keep the +same ``name`` and ``version`` and use the ``user/channel`` to disambiguate your recipe. + +The value of these fields can be accessed from within a ``conanfile.py``: .. code-block:: python @@ -161,24 +162,36 @@ channel as the current package, which could be achieved with something like: version = "0.1" def requirements(self): - self.requires("Say/0.1@%s/%s" % (self.user, self.channel)) + self.requires("common-lib/version") + if self.user and self.channel: + # If the recipe is using them, I want to consume my fork. + self.requires("Say/0.1@%s/%s" % (self.user, self.channel)) + else: + # otherwise, I'll consume the community one + self.requires("Say/0.1") -Only package recipes that are in the conan local cache (i.e. "exported") have a user/channel assigned. -For package recipes working in user space, there is no current user/channel by default. They can be -defined at ``conan install`` time with: + +Only packages that have already been exported (packages in the local cache or in a remote server) +can have a user/channel assigned. For package recipes working in the user space, there is no +current user/channel by default, although they can be defined at ``conan install`` time with: .. code-block:: bash $ conan install user/channel -If they are not defined via command line, the properties ``self.user`` and ``self.channel`` will then look -for environment variables ``CONAN_USERNAME`` and ``CONAN_CHANNEL`` respectively. If they are not defined, -an error will be raised unless ``default_user`` and ``default_channel`` are declared in the recipe. .. seealso:: FAQ: :ref:`faq_recommendation_user_channel` + +.. warning:: + + Environment variables ``CONAN_USERNAME`` and ``CONAN_CHANNEL`` that were used to assign a value + to these fields are now deprecated and will be removed in Conan 2.0. Don't use them to + populate the value of ``self.user`` and ``self.channel``. + + default_user, default_channel ----------------------------- diff --git a/reference/env_vars.rst b/reference/env_vars.rst index 61e92190d33d..9a7022367133 100644 --- a/reference/env_vars.rst +++ b/reference/env_vars.rst @@ -437,8 +437,9 @@ CONAN_SKIP_VS_PROJECTS_UPGRADE **Defaulted to**: ``False``/``0`` -When set to ``True``/``1``, the :ref:`tools_build_sln_command`, the :ref:`tools_msvc_build_command` -and the :ref:`MSBuild()` build helper, will not call ``devenv`` command to upgrade the ``sln`` project, irrespective of +When set to ``True``/``1``, the :ref:`tools.build_sln_command() `, +the :ref:`tools.msvc_build_command() ` +and the :ref:`MSBuild() ` build helper, will not call ``devenv`` command to upgrade the ``sln`` project, irrespective of the ``upgrade_project`` parameter value. CONAN_SYSREQUIRES_MODE @@ -506,12 +507,16 @@ The logger will append the traces until the ``CONAN_TRACE_FILE`` variable is uns CONAN_USERNAME, CONAN_CHANNEL ----------------------------- -These environment variables will be checked when using ``self.user`` or ``self.channel`` in package recipes in user space, where the user -and channel have not been assigned yet (they are assigned when exported in the local cache). +.. warning:: -.. seealso:: + Environment variables ``CONAN_USERNAME`` and ``CONAN_CHANNEL`` are deprecated and will be + removed in Conan 2.0. Don't use them to populate the value of ``self.user`` and ``self.channel``. + +These environment variables will be checked when using ``self.user`` or ``self.channel`` in package +recipes in user space, where the user and channel have not been assigned yet (they are assigned +when exported in the local cache). More about these variables in +the :ref:`attributes reference `. - Read more about it in :ref:`user_channel` CONAN_USER_HOME ---------------