Improve docs regarding "host" profile tool-requires

[memsharded]

Simplified Summary for Future Readers

For anyone who finds this issue (#18148) later while trying to enforce Ninja usage for both project and dependency builds, hopefully this simplified summary helps navigate the complexities we encountered.

Our Goal

We aimed for fully reproducible cross-platform builds using Ninja, managed by Conan via tool_requires, as the exclusive CMake generator for all components (our main project and any dependencies built from source via conan install --build=missing). We wanted to avoid relying on system-installed Ninja.

The Problem We Faced

Our initial attempts failed. Dependencies either didn't use Ninja (defaulting to Makefiles) or failed because CMake couldn't find the Ninja executable during the dependency build step, even when Ninja was listed as a tool_requires in our main recipe or configured via profile [conf] settings in various ways.

The Key Insight

The crucial point, clarified by @memsharded, relates to Conan's Host vs. Build contexts.

• Dependencies (like libraries your project uses, e.g., fmt, log4cplus) are part of the Host Context.
• To successfully build a package for the Host Context, the necessary build tools ([tool_requires]) AND the configuration instructing the build system what to do (e.g., [conf] generator=Ninja) must BOTH be provided by the Host Profile.
• Simply putting the tool_requires in the main project's recipe or in the Build Profile was insufficient to make Ninja available and active during the dependency build phase.

Working Solution Steps (Conan 2.15.1)

The configuration that ultimately worked reliably was:

1. Remove Ninja tool_requires from the main project's conanfile.py. Let the profile handle it entirely.
2. Create a project-local Host Profile (e.g., .conan/profiles/host_ninja). This keeps the configuration with the project.
3. Inside this Host Profile file (host_ninja):
   • Include the user's base settings: include(default)
   • Add the configuration to use Ninja:

   [conf]
   tools.cmake.cmaketoolchain:generator=Ninja
   

   • Add the tool itself to be available:

   [tool_requires]
   ninja/1.12.1
   

4. Run conan install specifying this profile for the host context (e.g., conan install ... -pr:h /path/to/.conan/profiles/host_ninja). Let the build profile default or be specified separately if needed.
5. Run CMake configure for the main project directly, passing -G Ninja and the path to the conan_toolchain.cmake generated by conan install. No special environment sourcing was needed in the calling script for this final step because the toolchain file contained the necessary hints.

Disclaimer

This summary reflects our understanding based on resolving this specific issue in our environment with Conan 2.15.1. The concepts might evolve, or there could be nuances not covered here. Please always refer to the official Conan documentation as the definitive and most up-to-date source. We hope this helps others facing similar challenges.

Acknowledgements

We'd like to express our sincere gratitude to @memsharded and the Conan team for their outstanding support in resolving this issue. Their expertise and willingness to guide us through the complexities of Conan's profile system was invaluable.

We're sharing this guide in good faith to pay it forward to the community. If you're struggling with similar Ninja integration challenges, we hope our experience saves you time and frustration. Open source thrives on knowledge sharing, and we're grateful to be part of a community where solutions can benefit everyone.

Originally posted by @evilrix in #18148