diff --git a/creating_packages/toolchains.rst b/creating_packages/toolchains.rst index bbeecc23ea1..ba019e6abee 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 ``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 = "" -.. 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: @@ -36,23 +49,23 @@ 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 diff --git a/creating_packages/toolchains/cmake.rst b/creating_packages/toolchains/cmake.rst index 2741776577c..9e5d42bc639 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: -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: diff --git a/creating_packages/toolchains/make.rst b/creating_packages/toolchains/make.rst index 27846b06cc5..2f098b8ed41 100644 --- a/creating_packages/toolchains/make.rst +++ b/creating_packages/toolchains/make.rst @@ -5,16 +5,24 @@ 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" @@ -22,9 +30,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 +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: diff --git a/creating_packages/toolchains/msbuild.rst b/creating_packages/toolchains/msbuild.rst index 57dad7911f5..bac049429f5 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: -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): diff --git a/integrations/build_system/make.rst b/integrations/build_system/make.rst index a56212e9c0b..a185c503e4b 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``. @@ -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