[Doc] Explain how a user profile should be written in order to be robust to conan v1 & v2 recipes

[SpaceIm]

conan-center documentation doesn't explain how user profiles should be written so that they can consume both conan recipes still reyling on legacy helpers & recipes migrated to conan v2 build helpers. Indeed, conan client doesn't provide backward & forward compatibility of all profile parameters (due to design choices, risk of breakage, maintenance cost, or whatever), so users must be aware of these limitations and how avoid breakage.

I think documentation should show:

• a compatibility matrix: legacy conan env vars <=> conan v2 conf, for example:

  User configuration	conan v1	conan v2
  CMake generator	CONAN_CMAKE_GENERATOR in [env]	tools.cmake.cmaketoolchain:generator in [conf]
  Inject User CMake toolchain	CONAN_CMAKE_TOOLCHAIN_FILE in [env]	tools.cmake.cmaketoolchain:user_toolchain in [conf]
  Inject CMAKE_SYSTEM_NAME	CONAN_CMAKE_SYSTEM_NAME in [env]	tools.cmake.cmaketoolchain:system_name in [conf]
  Inject CMAKE_SYSTEM_VERSION	CONAN_CMAKE_SYSTEM_VERSION in [env]	tools.cmake.cmaketoolchain:system_version in [conf]
  Inject CMAKE_SYSTEM_PROCESSOR	CONAN_CMAKE_SYSTEM_PROCESSOR in [env]	tools.cmake.cmaketoolchain:system_processor in [conf]
  Inject CMAKE_SYSROOT	CONAN_CMAKE_SYSROOT in [env]	tools.build:sysroot in [conf]
  Inject -sysroot in autotools build	Not supported ?	tools.build:sysroot in [conf]
  Inject ANDROID_NDK	CONAN_CMAKE_ANDROID_NDK in [env]	tools.android:ndk_path in [conf]
  MSBuild verbosity	CONAN_MSBUILD_VERBOSITY in [env]	tools.microsoft.msbuild:verbosity in [conf]
  Make program	CONAN_MAKE_PROGRAM in [env]	tools.gnu:make_program in [conf]
  Bash path	CONAN_BASH_PATH in [env]	tools.microsoft.bash:path & tools.microsoft.bash:subsystem in [conf]
  Constrain number of jobs during build	CONAN_CPU_COUNT in [env]	tools.build:jobs in [conf]
  C compiler	CC in [env]	c key of tools.build:compiler_executables in [conf] or CC in [buildenv]
  C++ compiler	CXX in [env]	cpp key of tools.build:compiler_executables in [conf] or CXX in [buildenv]

• explanation of difference between [env] & [buildenv] in profile, and that both can coexist together to achieve backward & forward compatibility.

• clear explanation that cross-build must be done with 2 profiles

• some examples of profiles robust to conan v1 & v2 recipes (native build & cross-build):

  • gcc or clang on Linux
  • gcc or apple-clang on macOS
  • msvc or clang-cl or gcc MinGW or clang MinGW on Windows
  • cross-build from Linux to Windows with gcc MinGW
  • cross-build from Linux/Windows/macOS to Android, using android-ndk recipe or a system installed Android NDK.
  • cross-build from Linux/Windows/macOS to Emscripten, using emsdk recipe or a system installed Emscripten SDK.
  • cross-build from macOS to iOS

[prince-chrismc]

This would a great addition

Should this be in the regular docs? https://docs.conan.io/en/latest/conan_v2.html maybe?

[SpaceIm]

Maybe in regular docs of conan v1 client. Maybe conan v1 docs should even completely change its Getting Started to rely on new generators to avoid confusion and already point new comers to modern conan.

[SpaceIm]

@memsharded what do you think? Should it be documented in conan v1 doc? I'm really wondering what is user experience of conan beginner currently with all this mixture of conan v1 & v2 recipes in conan-center, assuming they follow the Getting Started of conan v1 doc.

[memsharded]

I think this is great, and should be definitely part of the Conan 1.X docs, at least in the migration guide.