Document generate for toolchains and deprecate toolchain and write_toolchain_files

creating_packages/toolchains.rst

@@ -10,49 +10,62 @@ Toolchains
 
     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.
-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:
 
 
 .. code:: python
 
-    from conans import CMakeToolchain
+    from conan.tools.cmake 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
 
-    from conans import CMakeToolchain
+    from conan.tools.cmake 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")
@@ -81,12 +94,12 @@ 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 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

creating_packages/toolchains/cmake.rst

@@ -8,13 +8,20 @@ CMakeToolchain
 
     This is an **experimental** feature subject to breaking changes in future releases.
 
+.. warning:
 
-The ``CMakeToolchain`` can be used in the ``toolchain()`` method:
+    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 = "CMakeToolchain"`` instead of the
+    ``toolchain`` attribute.
+
+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"
@@ -23,9 +30,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 +77,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:
 

creating_packages/toolchains/make.rst

@@ -5,26 +5,34 @@
 
     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. 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
 ==============
 
-The `MakeToolchain` can be used in the ``toolchain()`` method of
+The `MakeToolchain` can be used in the ``generate()`` method of
 ``conanfile.py``:
 
 
 .. 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"
         requires = "hello/0.1"
         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 +144,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:
 

creating_packages/toolchains/msbuild.rst

@@ -5,13 +5,20 @@ MSBuildToolchain
 
     This is an **experimental** feature subject to breaking changes in future releases.
 
+.. warning:
 
-The ``MSBuildToolchain`` can be used in the ``toolchain()`` method:
+    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 = "MSBuildToolchain"`` instead of the
+    ``toolchain`` attribute.
+
+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"
@@ -20,9 +27,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 +98,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):

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``.
 
@@ -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"
@@ -91,9 +92,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