workspaces templates change to allow out-of-source builds

[memsharded]

Changelog: Fix: Allow using reference object in workspaces in templates for out of source builds
Docs: conan-io/docs#1135

Close #4800

The key is allowing:

[build_folder]
../build/{{reference.name}}/{{settings.build_type}}

@tags: slow

[theodelrieu]

Is it possible to use the project's folder name? I usually have package names prefixed.

Assuming Boost uses workspaces: boost_math is the package name, boost the root folder of the workspace, math a subproject. I'd like to keep the same folder hierarchy in the build folder.

This is especially useful to run Ninja commands, e.g. ninja math/test to only run Boost.Math tests.

[jgsogo]

Two considerations:

• This new context variable available for Jinja2 engine should be documented in the same way as hooks, not like a ConanFileReference, but a namedtuple: "reference: Named tuple with attributes name, version, user, and channel. Its representation will be a reference like: box2d/2.1.0@user/channel"
• Should it be reference or ref? We can keep reference for backwards compatibility and add ref to match our naming conventions.

[memsharded]

Is it possible to use the project's folder name? I usually have package names prefixed.

Assuming Boost uses workspaces: boost_math is the package name, boost the root folder of the workspace, math a subproject. I'd like to keep the same folder hierarchy in the build folder.

@theodelrieu you will have the package name as an input, from there, if you can do it with Jinja (I think it is possible, something like {{ reference.name | replace("_", "/") }}), then you are good

@jgsogo Agree on docs for namedtuple, I'll do it that way. Regarding the name, I think we are calling it reference towards the user (hooks, conan_api), so maybe we could leave it the same way, the feature is experimental if we wanted we could rename it, right? But reference sounds more consistent with other places, what do you think?

[lasote]

Pending docs

[jgsogo]

@jgsogo Regarding the name, I think we are calling it reference towards the user (hooks, conan_api), so maybe we could leave it the same way, the feature is experimental if we wanted we could rename it, right? But reference sounds more consistent with other places, what do you think?

For hooks, we thought it had been an error to name the argument reference when it was actually a ref. I agree that reference is more sound from the user POV, and actually I like it more 👍