docs(mac): update CIME machine configuration documentation for Darwin OS-level support

[johnpaulalex]

Description of changes

Updates CIME machine configuration documentation (cime/doc/source/ccs/model-configuration/support-a-new-machine.rst) to document zero-config macOS (Darwin) OS-level support and macro resolution in the CESM repository while preserving the model-independent machine configuration documentation.

Specific notes

Contributors other than yourself, if any:

• @billsacks
• @jasonb5
• @johnpaulalex

Linked issues addressed, if any:

• None

Description of generative AI usage:

• Google Antigravity was used to write the code and tests, followed by human-guided verification.

Answer Changes & Scientific Impact

• Bit-for-Bit (B4B) with baseline master
• Roundoff-level differences only
• Expected Answer Changes (ECA)

User Interface & Namelist Changes

• Namelist / Defaults modified? No
• XML / Build script changes? No (cime/doc/source/ccs/model-configuration/support-a-new-machine.rst)

Testing planned or performed, if any:

• Verified documentation markup rendering.

CTSM / CESM baseline hash-tag: 8961a1142
PR branch hash-tag: f4a0ba9a1

Requirements before merge:

• The code in this PR branch builds with no errors.
• The code in this PR branch runs with no errors.
• In-code documentation and Fortran docstrings updated.
• This PR either (a) does not create a need to update documentation or (b) includes required documentation updates. Which?: (a) Documentation update.

[billsacks]

Thanks a lot for both this documentation and the changes to support it, @johnpaulalex !

[billsacks]

@johnpaulalex - I see that there are conflicts with the latest version of this documentation. Please merge and resolve conflicts. It may be because of some recent work to remove machine-specific things from the documentation.

@jasonb5 - any thoughts on whether this machine-specific documentation is appropriate here or if we want it elsewhere?

[johnpaulalex]

Thanks Bill. I merged and resolved. Note these docs depend on ESMCI/ccs_config_cesm#298 which actually makes the darwin stuff work (I also added this pointer to the PR description). Is there some ordering to worry about here?

[billsacks]

Thanks, @johnpaulalex ! I'm happy with this, but I want to hear @jasonb5 's thoughts before merging. I'm not concerned about order dependency because this is just documentation, so it's not a big deal if it's temporarily out of sync.

[johnpaulalex]

Thanks @jasonb5 and @billsacks! I restored the paragraph, and put the Macos stuff below it. Also I removed the paragraph about homebrew sticking around - I meant to ask if homebrew is a config we should still keep around in general. Is it more generic than just Macs?

[billsacks]

A few comments:

(1)

I meant to ask if homebrew is a config we should still keep around in general. Is it more generic than just Macs?

I think this is a question for the ccs_config changes, not really for this CIME documentation change. Do you agree? That said, I'll try to answer it: I haven't totally gotten my head around what you did for the ccs_config changes, but if you have made homebrew obsolete for Macs, then I think it can be removed. As far as I know, homebrew is only for Macs.

(2) I see that you removed reference to CESM in your latest version. I actually think that CESM should be mentioned specifically there, because what you're describing is not generic CIME functionality, but (I think) depends on the changes you made in CESM's ccs_config.

(3) A general GitHub process issue: I find it a lot easier to iteratively review PRs if they don't include force pushes – instead involving simple commits that build on each other. Maybe there's a solution I'm not aware of, but I don't know a good way to see what changed since my last review in the presence of force pushes, and this makes it harder for me to re-review changes. In a case like this one where the history of the branch isn't very important, I am okay with a final cleanup squash just before merging, but I prefer if the development in the midst of review doesn't include any force pushes that overwrite history. That said, I'm curious how others feel about this.

Thanks a lot for continuing to iterate on this - I appreciate the care you're taking with this documentation!

[johnpaulalex]

Thanks Bill. I thought homebrew also applied to this PR because this seems like the natural place to have mentioned it (but now superseded by the Darwin instructions).

Yeah I think the new changes supersede the old homebrew mechanism, and now require no special var-setting from users. I updated that PR to be clearer about what it's doing.

I added CESM back to the text in this PR.

And TIL about force-pushing being not good for reviews. Makes sense. I had kinda noticed that github wasn't showing diffs and I didn't connect the dots why. That said, it's a process of iterating with AI and even though I had instructed it to not force-push anymore, it just did it anyway for my CESM change above. Sigh. I updated my instructions again and I believe it won't happen again.

[billsacks]

Thanks for your continued iteration on this! Looks good to me.

[billsacks]

I thought homebrew also applied to this PR because this seems like the natural place to have mentioned it (but now superseded by the Darwin instructions).

Ah, gotcha - I hadn't realized that you were referring to the documentation. I realize that it's confusing that we have documentation in CIME despite it documenting something that lives outside of CIME and is CESM-specific... we're still working on how to manage this... thanks for bearing with us.

Yeah I think the new changes supersede the old homebrew mechanism, and now require no special var-setting from users. I updated that PR to be clearer about what it's doing.

Great!

And TIL about force-pushing being not good for reviews. Makes sense. I had kinda noticed that github wasn't showing diffs and I didn't connect the dots why. That said, it's a process of iterating with AI and even though I had instructed it to not force-push anymore, it just did it anyway for my CESM change above. Sigh. I updated my instructions again and I believe it won't happen again.

Not a big deal here, but yes, thanks for trying to change this for the future - it would be more of a problem with larger PRs.