[workspaces] update documentation

[blockspacer]

My workspaces setup: https://github.com/blockspacer/flextool#for-contibutors-conan-workspace

First of all: workspaces are great! But documentation lacks some important usage instructions.

Some things that i had to change in CmakeLists.txt to make workspaces work in not-trivial setup:

• no relative include(). workspaces use add_subdirectory, so collision in names of .cmake files caused bugs.
• all cmake option names must be unique. Same reason as in include() section. Prefixed each option or CACHE variable name with project name.
• Need to detect somehow if conan package uses workspaces or installed from conan cache (as usual). Added set(packageName_LOCAL_BUILD TRUE CACHE BOOL "packageName_LOCAL_BUILD") in CMakeLists.txt created for workspace. <-- can be automated, just add cmake flag if package is part of workspace
• Not obvious that package to choose as root
• CONAN_PACKAGENAME_ROOT do not work, used get_target_property and hacks similar to:

set(flexlib_LIB CONAN_PKG::flexlib)
# conan package has '/include' dir
set(flexlib_HEADER_DIR
  ${CONAN_FLEXLIB_ROOT}/include
)
if(flexlib_LOCAL_BUILD)
  # name of created target
  set(flexlib_LIB flexlib)
  # no '/include' dir on local build
  set(flexlib_HEADER_DIR
    ${CONAN_FLEXLIB_ROOT}/include
  )
else()
  # uses Config.cmake or a -config.cmake file
  # see https://gitlab.kitware.com/cmake/community/wikis/doc/tutorials/How-to-create-a-ProjectConfig.cmake-file
  # BELOW MUST BE EQUAL TO find_package(... CONFIG REQUIRED)
  # NOTE: find_package(CONFIG) not supported with EMSCRIPTEN, so use include()
  include(${CMAKE_CURRENT_LIST_DIR}/cmake/flexlib-config.cmake)
endif(flexlib_LOCAL_BUILD)
message(STATUS "flexlib_HEADER_DIR=${flexlib_HEADER_DIR}")

<- is invalid CONAN_PACKAGENAME_ROOT expected?

• Had to manually set add_dependencies in CMakeLists.txt created for workspace. <-- can be automated based on dependency graph (build each package in strict order, so deps will not compile before root)
• Prefixed each package option to avoid collisions -o packageName:shared=True
• Added

        # Local build
        # see https://docs.conan.io/en/latest/developing_packages/editable_packages.html
        if not self.in_local_cache:
            self.copy("conanfile.py", dst=".", keep_path=False)

• add_subdirectory changed CMAKE_SOURCE_DIR, CMAKE_BINARY_DIR. Fixed by CMAKE_CURRENT_SOURCE_DIR, CMAKE_CURRENT_BINARY_DIR

[jgsogo]

Hi! Thanks a lot for your detailed feedback and for taking the time to submit all these suggestions that can improve workspaces. For sure this is not just about better docs, but the feature itself needs to be fixed/improved. I'll share with you a draft I did time ago trying to address some issues I found while using workspaces: #5314 (the PR description is more interesting than the changes in sources)

Workspaces are in the roadmap and it will get attention, but there are other things with a higher priority that we need to release before Conan 2.0 so we can get feedback about them. Most of the new things are ready, so we will be able to come back to these features soon 😉

[memsharded]

#15992 is centralizing feedback and effort for Conan 2 workspaces, lets close this one and track progress there.