diff --git a/reference/extensions/custom_generators.rst b/reference/extensions/custom_generators.rst index 43b13bdedf1..a1e454b99db 100644 --- a/reference/extensions/custom_generators.rst +++ b/reference/extensions/custom_generators.rst @@ -5,7 +5,7 @@ Custom Conan generators In the case that you need to use a build system or tool that is not supported by Conan off-the-shelf, you could create your own custom integrations using a custom generator. -This can be done in two different ways. +This can be done in three different ways. Custom generators as python_requires ------------------------------------ @@ -98,3 +98,47 @@ argument: .. code-block:: bash conan install --requires=zlib/1.2.13 -g MyGenerator + + +Generators from tool_requires +----------------------------- + +.. include:: ../../common/experimental_warning.inc + +A direct dependency tool requires can also be used to provide custom generators. +The following example shows how to create a custom generator that generates a file with the +dependencies of the package, just like the example above, but using a ``tool_require`` instead of a ``python_require`` +to inject the generator into the recipe, by adding them to the ``self.generators_info`` list inside the ``package_info`` method. + +.. code-block:: python + :caption: mygenerator/conanfile.py + + from conan import ConanFile + from conan.tools.files import save + + class MyGenerator: + def __init__(self, conanfile): + self._conanfile = conanfile + + def generate(self): + deps_info = "" + for dep, _ in self._conanfile.dependencies.items(): + deps_info = f"{dep.ref.name}, {dep.ref.version}" + save(self._conanfile, "deps.txt", deps_info) + + class MyToolReq(ConanFile): + name = "mygenerator-tool" + version = "1.0" + + def package_info(self): + self.generators_info.append(MyGenerator) + +And then having a ``tool_requires`` in your recipe for the ``mygenerator-tool`` package will automatically +inject the generator into the recipe. + +.. note:: + + Note that built-in generators can also be injected using tool_requires, + by adding them by name: ``self.generators_info.append("CMakeDeps")``. + ``tool_require``ing this package will inject the ``CMakeDeps`` generator into the recipe + just as if it was declared in its ``generators`` attribute.