Add docu for deployers and a simple example

examples.rst

@@ -9,6 +9,7 @@ Examples
 
    examples/conanfile/conanfile
    examples/extensions/commands/custom_commands
+   examples/extensions/deployers/custom_deployers
    examples/tools/cmake/cmake
    examples/tools/files/files
    examples/tools/meson/meson

examples/extensions/deployers/custom_deployers.rst

@@ -0,0 +1,14 @@
+.. _examples_extensions_deployers:
+
+
+
+
+Custom deployers
+================
+
+
+.. toctree::
+   :maxdepth: 2
+
+
+   sources/custom_deployer_sources

examples/extensions/deployers/sources/custom_deployer_sources.rst

@@ -0,0 +1,76 @@
+.. examples_extensions_deployers_sources:
+
+Copy sources from all your dependencies
+=======================================
+
+
+
+Please, first of all, clone the sources to recreate this project. You can find them in the
+`examples2.0 repository <https://github.com/conan-io/examples2>`_ in GitHub:
+
+.. code-block:: bash
+
+    $ git clone https://github.com/conan-io/examples2.git
+    $ cd examples2/examples/extensions/deployers/sources
+
+
+In this example we are going to see how to create and use a custom deployer.
+This deployer copies all the source files from your dependencies and puts them in a specific output folder
+
+.. note::
+
+    To better understand this example, it is highly recommended to have previously read the :ref:`Deployers <reference_extensions_deployer_direct_deploy>` reference.
+
+
+Locate the deployer
+-------------------
+
+In this case, the deployer is located in the same directory than our example conanfile,
+but as show in :ref:`Deployers <reference_extensions_deployer_direct_deploy>` reference,
+Conan will look for the specified deployer in a few extra places besides the current working directory,
+including as an absolute path, and in ``[YOUR_CONAN_HOME]/extensions/deploy/``.
+
+
+Run it
+------
+
+For our example, we have a simple recipe that only lists ``zlib`` as a requirement.
+With the help of the ``tools.build:download_source=True`` conf, we can force the invocation of its ``source()`` method,
+which will ensure that sources are available even if no build needs to be carried out.
+
+Now, you should be able to use the new deployer in both ``conan install`` and ``conan graph`` commands for any given recipe:
+
+.. code-block:: bash
+
+    $ conan graph info . -c tools.build:download_source=True --deploy=sources_deploy
+
+
+
+Inspecting the command output we can see that it copied the sources of all our dependencies (direct and transitive)
+to a ``dependency_sources`` folder. After this, extra preprocessing could be accomplished to more specific needs.
+
+Code tour
+---------
+
+The **source_deploy.py** file has the following code:
+
+
+**sources_deploy.py**
+
+.. code-block:: python
+
+    from conan.tools.files import copy
+    import os
+
+
+    def deploy(graph, output_folder):
+        for name, dep in graph.root.conanfile.dependencies.items():
+            copy(graph.root.conanfile, "*", dep.folders.source_folder, os.path.join(output_folder, "dependency_sources", str(dep)))
+
+
+deploy()
+++++++++
+
+The ``deploy()`` method is called by Conan, and gets both a dependency graph (``conans.client.graph.graph.DepsGraph``)
+and an output folder path as arguments. It iterates all the dependencies of our recipe,
+and copies every source file to their respective folder under ``dependency_sources`` using :ref:`conan.tools.copy<conan_tools_files_copy>`.

reference/extensions/deployers.rst

@@ -1,5 +1,65 @@
 .. _reference_extensions_deployers:
 
 Deployers
----------
+=========
 
+Deployers are a mechanism to facilitate copying files form one folder, usually the Conan cache, to user folders.
+While Conan provides two built-in ones (``full_deploy`` and ``direct_deploy``), users can easily manage their own
+with ``conan config install``.
+
+Deployers run before generators, and they can change the target folders.
+For example, if the ``--deploy=full_deploy`` deployer runs before ``CMakeDeps``,
+the files generated by ``CMakeDeps`` will point to the local copy in the user folder done by the ``full_deploy`` deployer,
+and not to the Conan cache.
+
+Deployers can be multi-configuration. Running ``conan install . --deploy=full_deploy`` repeatedly for different profiles
+can achieve a fully self-contained project, including all the artifacts, binaries, and build files.
+This project would be completely independent of Conan and no longer require it at all to build.
+
+
+Built-in deployers
+------------------
+
+.. _reference_extensions_deployer_full_deploy:
+
+full_deploy()
+^^^^^^^^^^^^^
+
+Deploys to ``output_folder`` + ``host/dep/0.1/Release/x86_64`` subfolder
+
+
+.. _reference_extensions_deployer_direct_deploy:
+
+direct_deploy()
+^^^^^^^^^^^^^^^
+
+Deploys only your direct dependencies to ``output_folder``
+
+
+
+Custom deployers
+----------------
+
+Custom deployers can be managed via ``conan config install``. When looking for a specific deployer,
+Conan will look in these locations for the deployer in the following order:
+
+#. Absolute paths
+#. Relative to cwd
+#. In the ``conancache/extensions/deploy`` folder
+#. Built-in deployers
+
+For each installed file, Conan will look for a ``deploy()`` method which to call.
+The function signature of your custom deployers should be as follows:
+
+**my_custom_deployer.py**
+
+.. code-block:: python
+
+    def deploy(graph: conans.client.graph.graph.DepsGraph, output_folder: str):
+
+(Note that the arguments are passed as named parameters, so both the ``graph`` and ``output_folder`` names are mandatory)
+
+Your custom deployer can then be invoked as if it were a built-in deployer using the filename in which it's found,
+in this case ``conan install . --deploy=my_custom_deployer``.
+
+See the :ref:`custom deployers<examples_extensions_deployers>` section for examples on how to implement your own deployers.