when working with cmake i often use the following cmake command, cmake -L to print a list of “variables” / “args” i can pass to my cmake based project. so i do a google for CMAKE_OSX_ARCHITECTURES or even better i pop open the official cmake documentation and do a search for CMAKE_OSX_ARCHITECTURESwhich gives me the below page,
so for somebody completely new cmake who god forbid attempts to read the “official” documentation for cmake to troubleshoot working on a cmake based project and they want to find out more information about a cmake var / arg, how does that above page help.
it provides a link to another page that doesn’t provide much if any information that helps with the above said arg / var. i’d figure at the very least in the documentation there would be some values that var / arg could possible be. or even provide a command to show me what those values could be.
the documentation feels rather utterly incomplete.
The OSX_ARCHITECTURES property sets the target binary architecture for targets on macOS (-arch).
It sets the value passed to the -arch flag. That’s it.
Maybe that could be worded a little better, but the confusion I see a lot more often is “OK but what does the -arch flag do” or similar for other CMake options, and this now puts the CMake docs in an awkward position. There’s zero chance our docs can maintain parity with compiler manuals, and hardcoding links to compiler manuals into the CMake docs guarantees the links will rot in older versions of our documentation.
No great answer to this kind of problem. Building system software is hard and requires a very wide knowledge base.
What needs to be documented about the -arch flag? It’s a simple 1-sentence explanation (“specify the architecture to build for“), but I think that’s pretty sufficient explanation
The original poster has a very valid point. Not every developer has the deepest of understanding of CPU architectures let alone what operating system supports which architectures. And to the point about linking to compiler docs and having those links become stale there could be a statement as simple as:
Historically as of macOS (insert some version that is current) the values for -arch are “arm64” and “x86_64”. Please consult the compile documentation for more details.
We are not asking Kitware or the CMake developers to maintain a second compiler manual at all. But sometimes just the most basic of statements can help new users in immense ways.
