From 60306b7bb9078abb988f95b9173f7ff82b82cdb8 Mon Sep 17 00:00:00 2001 From: czoido Date: Tue, 1 Dec 2020 12:45:01 +0100 Subject: [PATCH 1/8] change names --- creating_packages/toolchains.rst | 35 ++++++++++++++++-------- creating_packages/toolchains/cmake.rst | 10 +++---- creating_packages/toolchains/make.rst | 10 +++---- creating_packages/toolchains/msbuild.rst | 8 +++--- integrations/build_system/make.rst | 8 +++--- 5 files changed, 42 insertions(+), 29 deletions(-) diff --git a/creating_packages/toolchains.rst b/creating_packages/toolchains.rst index bbeecc23ea1..79821847c47 100644 --- a/creating_packages/toolchains.rst +++ b/creating_packages/toolchains.rst @@ -10,25 +10,38 @@ Toolchains Please try it and provide feedback at: https://github.com/conan-io/conan/issues +.. warning: + + Starting in Conan 1.32 ``write_toolchain_files()`` method and ``toolchain`` attribute have been + deprecated. They will be removed in Conan 1.33, please use ``generate()`` instead of + ``write_toolchain_files()`` and ``generate`` or ``generators = "ToolChainClassName"`` instead of + ``toolchain`` attribute instead. Toolchains are the new, experimental way to integrate with build systems in Conan. -Recipes can define a ``toolchain()`` method that will return an object which +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 "translation" from the Conan settings and options, and the recipe defined configuration to something that the build system can understand. A recipe that does not have dependencies does not need a generator, but can still use a toolchain. -A toolchain can be defined, among the built-ins toolchains, with an attribute: +A toolchain can be defined, among the built-ins toolchains, with an attribute with the name of the +toolchain class to use. .. code:: python - toolchain = "cmake" + generators = "ToolChainClassName" -.. note:: +For example, for using the CMake toolchain this should be declared in the recipe: - At the moment (Conan 1.26), the only available built-in toolchain is the CMake one. +.. code:: python + + generators = "CMakeToolchain" + +.. note:: + At the moment (Conan 1.32), the available built-in toolchains are ``CMakeToolchain``, ``MakeToolchain``, + ``MSBuildToolchain`` and ``MesonToolchain``. But in the more general case, and if it needs any specific configuration beyond the default one: @@ -38,13 +51,13 @@ one: from conans import CMakeToolchain - def toolchain(self): + def generate(self): tc = CMakeToolchain(self) # customize toolchain "tc" - tc.write_toolchain_files() + tc.generate() -It is possible to use the ``toolchain()`` method to create your own files, which will typically be +It is possible to use the ``generate()`` method to create your own files, which will typically be deduced from the current configuration of ``self.settings`` and ``self.options``. .. code:: python @@ -52,7 +65,7 @@ deduced from the current configuration of ``self.settings`` and ``self.options`` from conans import CMakeToolchain from conans.tools import save - def toolchain(self): + def generate(self): # Based on the self.settings, self.options, the user # can generate their own files: save("mytoolchain.tool", "my own toolchain contents, deduced from the settings and options") @@ -83,10 +96,10 @@ the documentation of each toolchain to check the associated build helper availab from conans import CMakeToolchain, CMake - def toolchain(self): + def generate(self): tc = CMakeToolchain(self) # customize toolchain "tc" - tc.write_toolchain_files() + tc.generate() def build(self): # NOTE: This is a simplified helper diff --git a/creating_packages/toolchains/cmake.rst b/creating_packages/toolchains/cmake.rst index 2741776577c..939406aedd4 100644 --- a/creating_packages/toolchains/cmake.rst +++ b/creating_packages/toolchains/cmake.rst @@ -9,7 +9,7 @@ CMakeToolchain This is an **experimental** feature subject to breaking changes in future releases. -The ``CMakeToolchain`` can be used in the ``toolchain()`` method: +The ``CMakeToolchain`` can be used in the ``generate()`` method: .. code:: python @@ -23,9 +23,9 @@ The ``CMakeToolchain`` can be used in the ``toolchain()`` method: options = {"shared": [True, False], "fPIC": [True, False]} default_options = {"shared": False, "fPIC": True} - def toolchain(self): + def generate(self): tc = CMakeToolchain(self) - tc.write_toolchain_files() + tc.generate() The ``CMakeToolchain`` will generate 2 files, after a ``conan install`` command (or @@ -70,12 +70,12 @@ This attribute allows defining CMake variables, for multiple configurations (Deb .. code:: python - def toolchain(self): + def generate(self): tc = CMakeToolchain(self) tc.preprocessor_definitions["MYVAR"] = "MyValue" tc.preprocessor_definitions.debug["MYCONFIGVAR"] = "MyDebugValue" tc.preprocessor_definitions.release["MYCONFIGVAR"] = "MyReleaseValue" - tc.write_toolchain_files() + tc.generate() This will be translated to: diff --git a/creating_packages/toolchains/make.rst b/creating_packages/toolchains/make.rst index 27846b06cc5..e1c3465c917 100644 --- a/creating_packages/toolchains/make.rst +++ b/creating_packages/toolchains/make.rst @@ -8,7 +8,7 @@ MakeToolchain ============== -The `MakeToolchain` can be used in the ``toolchain()`` method of +The `MakeToolchain` can be used in the ``generate()`` method of ``conanfile.py``: @@ -22,9 +22,9 @@ The `MakeToolchain` can be used in the ``toolchain()`` method of options = {"shared": [True, False], "fPIC": [True, False]} default_options = {"shared": False, "fPIC": True} - def toolchain(self): + def generate(self): tc = Make(self) - tc.write_toolchain_files() + tc.generate() The ``MakeToolchain`` will generate the following file during ``conan install`` @@ -136,10 +136,10 @@ This attribute allows defining preprocessor definitions the same way that build .. code:: python - def toolchain(self): + def generate(self): tc = MakeToolchain(self) tc.definitions["MYVAR"] = "MyValue" - tc.write_toolchain_files() + tc.generate() This will be translated to: diff --git a/creating_packages/toolchains/msbuild.rst b/creating_packages/toolchains/msbuild.rst index 57dad7911f5..0665826039a 100644 --- a/creating_packages/toolchains/msbuild.rst +++ b/creating_packages/toolchains/msbuild.rst @@ -6,7 +6,7 @@ MSBuildToolchain This is an **experimental** feature subject to breaking changes in future releases. -The ``MSBuildToolchain`` can be used in the ``toolchain()`` method: +The ``MSBuildToolchain`` can be used in the ``generate()`` method: .. code:: python @@ -20,9 +20,9 @@ The ``MSBuildToolchain`` can be used in the ``toolchain()`` method: options = {"shared": [True, False]} default_options = {"shared": False} - def toolchain(self): + def generate(self): tc = MSBuildToolchain(self) - tc.write_toolchain_files() + tc.generate() The ``MSBuildToolchain`` will generate two files after a ``conan install`` command or @@ -91,7 +91,7 @@ The ``MSBuild`` helper can be used like: class App(ConanFile): settings = "os", "arch", "compiler", "build_type" - def toolchain(self): + def generate(self): ... def build(self): diff --git a/integrations/build_system/make.rst b/integrations/build_system/make.rst index a56212e9c0b..8ff9fb2f20f 100644 --- a/integrations/build_system/make.rst +++ b/integrations/build_system/make.rst @@ -41,9 +41,9 @@ To use the toolchain, add the following function to your ``conanfile``: class MyConan(ConanFile): ... - def toolchain(self): + def generate(self): tc = Make(self) - tc.write_toolchain_files() + tc.generate() **NOTE**: This can only be used in a ``conanfile.py`` and not ``conanfile.txt``. @@ -91,9 +91,9 @@ workflow. generators = "make" exports_sources = "*" - def toolchain(self): + def generate(self): tc = Make(self) - tc.write_toolchain_files() + tc.generate() def build(self): pass From 0efcd6e52d051b90b8fec5b32dc94c156e80565d Mon Sep 17 00:00:00 2001 From: czoido Date: Tue, 1 Dec 2020 13:02:31 +0100 Subject: [PATCH 2/8] change imports --- creating_packages/toolchains.rst | 8 ++++---- creating_packages/toolchains/cmake.rst | 9 ++++++++- creating_packages/toolchains/make.rst | 10 +++++++++- creating_packages/toolchains/msbuild.rst | 9 ++++++++- integrations/build_system/make.rst | 3 ++- 5 files changed, 31 insertions(+), 8 deletions(-) diff --git a/creating_packages/toolchains.rst b/creating_packages/toolchains.rst index 79821847c47..66e0894e1a1 100644 --- a/creating_packages/toolchains.rst +++ b/creating_packages/toolchains.rst @@ -13,7 +13,7 @@ Toolchains .. warning: Starting in Conan 1.32 ``write_toolchain_files()`` method and ``toolchain`` attribute have been - deprecated. They will be removed in Conan 1.33, please use ``generate()`` instead of + deprecated and moved. They will be removed in Conan 1.33, please use ``generate()`` instead of ``write_toolchain_files()`` and ``generate`` or ``generators = "ToolChainClassName"`` instead of ``toolchain`` attribute instead. @@ -49,7 +49,7 @@ one: .. code:: python - from conans import CMakeToolchain + from conan.tools.cmake import CMakeToolchain def generate(self): tc = CMakeToolchain(self) @@ -62,7 +62,7 @@ deduced from the current configuration of ``self.settings`` and ``self.options`` .. code:: python - from conans import CMakeToolchain + from conan.tools.cmake import CMakeToolchain from conans.tools import save def generate(self): @@ -94,7 +94,7 @@ the documentation of each toolchain to check the associated build helper availab .. code:: python - from conans import CMakeToolchain, CMake + from conan.tools.cmake import CMakeToolchain, CMake def generate(self): tc = CMakeToolchain(self) diff --git a/creating_packages/toolchains/cmake.rst b/creating_packages/toolchains/cmake.rst index 939406aedd4..2ed20f0e88d 100644 --- a/creating_packages/toolchains/cmake.rst +++ b/creating_packages/toolchains/cmake.rst @@ -8,13 +8,20 @@ CMakeToolchain This is an **experimental** feature subject to breaking changes in future releases. +.. warning: + + Starting in Conan 1.32 ``write_toolchain_files()`` method and ``toolchain`` attribute have been + deprecated and moved. They will be removed in Conan 1.33, please use ``generate()`` instead of + ``write_toolchain_files()`` and ``generate`` or ``generators = "ToolChainClassName"`` instead of + ``toolchain`` attribute instead. The ``CMakeToolchain`` can be used in the ``generate()`` method: .. code:: python - from conans import ConanFile, CMake, CMakeToolchain + from conans import ConanFile + from conan.tools.cmake import CMake, CMakeToolchain class App(ConanFile): settings = "os", "arch", "compiler", "build_type" diff --git a/creating_packages/toolchains/make.rst b/creating_packages/toolchains/make.rst index e1c3465c917..7266b721028 100644 --- a/creating_packages/toolchains/make.rst +++ b/creating_packages/toolchains/make.rst @@ -5,6 +5,13 @@ This is an **experimental** feature subject to breaking changes in future releases. +.. warning: + + Starting in Conan 1.32 ``write_toolchain_files()`` method and ``toolchain`` attribute have been + deprecated and moved. They will be removed in Conan 1.33, please use ``generate()`` instead of + ``write_toolchain_files()`` and ``generate`` or ``generators = "ToolChainClassName"`` instead of + ``toolchain`` attribute instead. + MakeToolchain ============== @@ -14,7 +21,8 @@ The `MakeToolchain` can be used in the ``generate()`` method of .. code:: python - from conans import ConanFile, MakeToolchain + from conans import ConanFile + from conan.tools.gnu import MakeToolchain class App(ConanFile): settings = "os", "arch", "compiler", "build_type" diff --git a/creating_packages/toolchains/msbuild.rst b/creating_packages/toolchains/msbuild.rst index 0665826039a..0c6a2bec2c8 100644 --- a/creating_packages/toolchains/msbuild.rst +++ b/creating_packages/toolchains/msbuild.rst @@ -5,13 +5,20 @@ MSBuildToolchain This is an **experimental** feature subject to breaking changes in future releases. +.. warning: + + Starting in Conan 1.32 ``write_toolchain_files()`` method and ``toolchain`` attribute have been + deprecated and moved. They will be removed in Conan 1.33, please use ``generate()`` instead of + ``write_toolchain_files()`` and ``generate`` or ``generators = "ToolChainClassName"`` instead of + ``toolchain`` attribute instead. The ``MSBuildToolchain`` can be used in the ``generate()`` method: .. code:: python - from conans import ConanFile, MSBuildToolchain + from conans import ConanFile + from conan.tools.microsoft import MSBuildToolchain class App(ConanFile): settings = "os", "arch", "compiler", "build_type" diff --git a/integrations/build_system/make.rst b/integrations/build_system/make.rst index 8ff9fb2f20f..a185c503e4b 100644 --- a/integrations/build_system/make.rst +++ b/integrations/build_system/make.rst @@ -82,7 +82,8 @@ workflow. .. code-block:: python :caption: *conanfile.py* - from conans import ConanFile, MakeToolchain + from conans import ConanFile + from conan.tools.gnu import MakeToolchain class MyConan(ConanFile): name = "myconan" From 6b456231c6aa451b0167f5e7f195b560d2d0cfb2 Mon Sep 17 00:00:00 2001 From: czoido Date: Tue, 1 Dec 2020 13:04:02 +0100 Subject: [PATCH 3/8] minor changes --- creating_packages/toolchains.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/creating_packages/toolchains.rst b/creating_packages/toolchains.rst index 66e0894e1a1..a2d5c7746c2 100644 --- a/creating_packages/toolchains.rst +++ b/creating_packages/toolchains.rst @@ -30,7 +30,7 @@ toolchain class to use. .. code:: python - generators = "ToolChainClassName" + generators = "" For example, for using the CMake toolchain this should be declared in the recipe: From e2b950c7d036af0f4aef0bf83a8dc0c960deba59 Mon Sep 17 00:00:00 2001 From: czoido Date: Wed, 2 Dec 2020 13:33:13 +0100 Subject: [PATCH 4/8] revisions --- creating_packages/toolchains.rst | 2 +- creating_packages/toolchains/cmake.rst | 2 +- creating_packages/toolchains/make.rst | 2 +- creating_packages/toolchains/msbuild.rst | 2 +- 4 files changed, 4 insertions(+), 4 deletions(-) diff --git a/creating_packages/toolchains.rst b/creating_packages/toolchains.rst index a2d5c7746c2..6548147259e 100644 --- a/creating_packages/toolchains.rst +++ b/creating_packages/toolchains.rst @@ -15,7 +15,7 @@ Toolchains Starting in Conan 1.32 ``write_toolchain_files()`` method and ``toolchain`` attribute have been deprecated and moved. They will be removed in Conan 1.33, please use ``generate()`` instead of ``write_toolchain_files()`` and ``generate`` or ``generators = "ToolChainClassName"`` instead of - ``toolchain`` attribute instead. + ``toolchain`` attribute. Toolchains are the new, experimental way to integrate with build systems in Conan. Recipes can define a ``generate()`` method that will return an object which diff --git a/creating_packages/toolchains/cmake.rst b/creating_packages/toolchains/cmake.rst index 2ed20f0e88d..a07b22a6752 100644 --- a/creating_packages/toolchains/cmake.rst +++ b/creating_packages/toolchains/cmake.rst @@ -13,7 +13,7 @@ CMakeToolchain Starting in Conan 1.32 ``write_toolchain_files()`` method and ``toolchain`` attribute have been deprecated and moved. They will be removed in Conan 1.33, please use ``generate()`` instead of ``write_toolchain_files()`` and ``generate`` or ``generators = "ToolChainClassName"`` instead of - ``toolchain`` attribute instead. + ``toolchain`` attribute. The ``CMakeToolchain`` can be used in the ``generate()`` method: diff --git a/creating_packages/toolchains/make.rst b/creating_packages/toolchains/make.rst index 7266b721028..37428c281ca 100644 --- a/creating_packages/toolchains/make.rst +++ b/creating_packages/toolchains/make.rst @@ -10,7 +10,7 @@ Starting in Conan 1.32 ``write_toolchain_files()`` method and ``toolchain`` attribute have been deprecated and moved. They will be removed in Conan 1.33, please use ``generate()`` instead of ``write_toolchain_files()`` and ``generate`` or ``generators = "ToolChainClassName"`` instead of - ``toolchain`` attribute instead. + ``toolchain`` attribute. MakeToolchain ============== diff --git a/creating_packages/toolchains/msbuild.rst b/creating_packages/toolchains/msbuild.rst index 0c6a2bec2c8..eb350e84bdd 100644 --- a/creating_packages/toolchains/msbuild.rst +++ b/creating_packages/toolchains/msbuild.rst @@ -10,7 +10,7 @@ MSBuildToolchain Starting in Conan 1.32 ``write_toolchain_files()`` method and ``toolchain`` attribute have been deprecated and moved. They will be removed in Conan 1.33, please use ``generate()`` instead of ``write_toolchain_files()`` and ``generate`` or ``generators = "ToolChainClassName"`` instead of - ``toolchain`` attribute instead. + ``toolchain`` attribute. The ``MSBuildToolchain`` can be used in the ``generate()`` method: From 12f92db9be10027a24356756280c96ba99b0109e Mon Sep 17 00:00:00 2001 From: Carlos Zoido Date: Wed, 2 Dec 2020 13:40:46 +0100 Subject: [PATCH 5/8] Update creating_packages/toolchains.rst Co-authored-by: Javier G. Sogo --- creating_packages/toolchains.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/creating_packages/toolchains.rst b/creating_packages/toolchains.rst index 6548147259e..de9d04f9339 100644 --- a/creating_packages/toolchains.rst +++ b/creating_packages/toolchains.rst @@ -13,7 +13,7 @@ Toolchains .. warning: Starting in Conan 1.32 ``write_toolchain_files()`` method and ``toolchain`` attribute have been - deprecated and moved. They will be removed in Conan 1.33, please use ``generate()`` instead of + deprecated. They will be removed in Conan 1.33, please use ``generate()`` instead of ``write_toolchain_files()`` and ``generate`` or ``generators = "ToolChainClassName"`` instead of ``toolchain`` attribute. From a71226d65279b9ac09ad9efb5214bdb2091a820a Mon Sep 17 00:00:00 2001 From: Carlos Zoido Date: Wed, 2 Dec 2020 13:40:52 +0100 Subject: [PATCH 6/8] Update creating_packages/toolchains.rst Co-authored-by: Javier G. Sogo --- creating_packages/toolchains.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/creating_packages/toolchains.rst b/creating_packages/toolchains.rst index de9d04f9339..1aa2a23f759 100644 --- a/creating_packages/toolchains.rst +++ b/creating_packages/toolchains.rst @@ -12,7 +12,7 @@ Toolchains .. warning: - Starting in Conan 1.32 ``write_toolchain_files()`` method and ``toolchain`` attribute have been + 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 ``write_toolchain_files()`` and ``generate`` or ``generators = "ToolChainClassName"`` instead of ``toolchain`` attribute. From 26a9e32dea9413894ed3ed322fc9cba2cc52d6fd Mon Sep 17 00:00:00 2001 From: Carlos Zoido Date: Wed, 2 Dec 2020 13:40:59 +0100 Subject: [PATCH 7/8] Update creating_packages/toolchains.rst Co-authored-by: Javier G. Sogo --- creating_packages/toolchains.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/creating_packages/toolchains.rst b/creating_packages/toolchains.rst index 1aa2a23f759..ba019e6abee 100644 --- a/creating_packages/toolchains.rst +++ b/creating_packages/toolchains.rst @@ -14,7 +14,7 @@ Toolchains 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 - ``write_toolchain_files()`` and ``generate`` or ``generators = "ToolChainClassName"`` instead of + ``toolchain()`` and ``generators = "ToolChainClassName"`` instead of ``toolchain`` attribute. Toolchains are the new, experimental way to integrate with build systems in Conan. From 3a36b51b4038076fd4bbe1f4028959ea5cd1f856 Mon Sep 17 00:00:00 2001 From: czoido Date: Wed, 2 Dec 2020 13:44:59 +0100 Subject: [PATCH 8/8] revision --- creating_packages/toolchains/cmake.rst | 4 ++-- creating_packages/toolchains/make.rst | 4 ++-- creating_packages/toolchains/msbuild.rst | 4 ++-- 3 files changed, 6 insertions(+), 6 deletions(-) diff --git a/creating_packages/toolchains/cmake.rst b/creating_packages/toolchains/cmake.rst index a07b22a6752..9e5d42bc639 100644 --- a/creating_packages/toolchains/cmake.rst +++ b/creating_packages/toolchains/cmake.rst @@ -11,8 +11,8 @@ CMakeToolchain .. warning: Starting in Conan 1.32 ``write_toolchain_files()`` method and ``toolchain`` attribute have been - deprecated and moved. They will be removed in Conan 1.33, please use ``generate()`` instead of - ``write_toolchain_files()`` and ``generate`` or ``generators = "ToolChainClassName"`` instead of + deprecated. They will be removed in Conan 1.33, please use ``generate()`` instead of + ``write_toolchain_files()`` and ``generate`` or ``generators = "CMakeToolchain"`` instead of the ``toolchain`` attribute. The ``CMakeToolchain`` can be used in the ``generate()`` method: diff --git a/creating_packages/toolchains/make.rst b/creating_packages/toolchains/make.rst index 37428c281ca..2f098b8ed41 100644 --- a/creating_packages/toolchains/make.rst +++ b/creating_packages/toolchains/make.rst @@ -8,8 +8,8 @@ .. warning: Starting in Conan 1.32 ``write_toolchain_files()`` method and ``toolchain`` attribute have been - deprecated and moved. They will be removed in Conan 1.33, please use ``generate()`` instead of - ``write_toolchain_files()`` and ``generate`` or ``generators = "ToolChainClassName"`` instead of + deprecated. They will be removed in Conan 1.33, please use ``generate()`` instead of + ``write_toolchain_files()`` and ``generate`` or ``generators = "MakeToolchain"`` instead of the ``toolchain`` attribute. MakeToolchain diff --git a/creating_packages/toolchains/msbuild.rst b/creating_packages/toolchains/msbuild.rst index eb350e84bdd..bac049429f5 100644 --- a/creating_packages/toolchains/msbuild.rst +++ b/creating_packages/toolchains/msbuild.rst @@ -8,8 +8,8 @@ MSBuildToolchain .. warning: Starting in Conan 1.32 ``write_toolchain_files()`` method and ``toolchain`` attribute have been - deprecated and moved. They will be removed in Conan 1.33, please use ``generate()`` instead of - ``write_toolchain_files()`` and ``generate`` or ``generators = "ToolChainClassName"`` instead of + deprecated. They will be removed in Conan 1.33, please use ``generate()`` instead of + ``write_toolchain_files()`` and ``generate`` or ``generators = "MSBuildToolchain"`` instead of the ``toolchain`` attribute. The ``MSBuildToolchain`` can be used in the ``generate()`` method: