Add docu for deployers and a simple example

[AbrilRBS]

Closes #2686

Requires conan-io/examples2#61

[memsharded]

Very good job

[memsharded]

dependencies_sources might be better?

[SSE4]

where is this dependency_sources folder located?

[memsharded]

Better not document a private object yet (nothing in the conans namespace should be in the docs at all), because users might thing they can instantiate or use their methods. Until we document the API of the graph, better treat it as opaque as possible, just saying that it has a root.conanfile would be enough.

[SSE4]

if consumer receives some sort of opaque object, they need to know that are the valid methods/attributes to be safely called.
if object itself cannot be documented, then it should define some sort of an interface.
e.g. how do I know that graph has graph.root, and graph.root has graph.root.conanfile, and graph.root.conanfile has graph.root.conanfile.dependencies that is some sort of dict.
how do I know that are these object and are they stable, if they are never explained?

[memsharded]

At the moment, it is enough to say that graph.root.conanfile is available, and that has the documented dependencies attribute, which is good for most cases. Let's just document that, but not the whole object private interface.

[SSE4]

and documentation on the dependencies interface says explicitly: This information does not exist in some recipe methods, only in those methods that evaluate after the full dependency graph has been computed., At the moment, this information should only be used in generate() and validate() methods. Any other use, please submit a Github issue.. it doesn't seem to say it's available in deploy() method and allowed to be used there. that's a bit contradictory from the documentation to say in one place it's not allowed, and in another it's allowed 🤔

[memsharded]

You are referencing Conan 1.X docs. The docs for 2.0 will be (and already are) very different to those of 1.X. Deployers is a 2.0 feature, and this PR is for 2.0-beta

[SSE4]

it says the same in 2.0 docs: https://docs.conan.io/en/2.0/reference/conanfile/other/dependencies.html?highlight=dependencies

[SSE4]

it says the same in 2.0 docs: https://docs.conan.io/en/2.0/reference/conanfile/other/dependencies.html?highlight=dependencies

[memsharded]

Ok, yes, that would be a bug in the docs, seems it was a copy&paste from 1.X

[SSE4]

I think, as it's for conan 2 and python 3+, it may already use Pathlib

[SSE4]

why do they need to affect on generators behavior? that's super confusing part.
as a consumer, I'd expect deployers just to deploy (copy) things, and otherwise, leave other parts untouched.

[memsharded]

That is one of most requested behaviors for deployers and generators.

[SSE4]

that's kinda surprising behavior that deployers may modify files generated by generators. can it be made more explicit? e.g. --deploy=full_deploy --deploy-modify-generator=CMakeDeps?

[SSE4]

some things that are not covered:

• can I specify multiple deployments at once (--deploy=a --deploy=b), or should I use separated conan install commands for each of the invocations?
• what happens if deploy() raises in the middle of deployment? will it leave some intermediate state or roll back? will it continue to execute other deployers, if any?

[SSE4]

I get:

cd: no such file or directory: examples2/examples/extensions/deployers/sources

is it expected? or typo in path?

[AbrilRBS]

Yes, this is expected as the PR in examples2 has not yet been merged

[SSE4]

as it doesn't include all the settings/options, is there a risk that several deployments will overwrite each other? maybe it's better just to use package id here?

[AbrilRBS]

There is, but if the user is worried about such problems, they are encouraged to write their own deployer, but let's tag @memsharded in case he thinks this could be nice to have

[SSE4]

this is kinda unspecified, what happens in case of multiple deployers, if all of them want to change target directories, what happens?

[AbrilRBS]

In this case, the last one would win