You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
I couldn't find a lot of documentation on how the CIME build works in the CIME User's Guide nor in README's or comments in the code.
From what I see the options for customization are:
Modify: Macros.cmake, Macros.make, or env_mach_specific.xml for your case (use --keep on case.setup to preserve your changes if you have to rerun case.setup)
Explicitly set any of these environment variables for the build:
USER_SLIBS
USER_CPPDEFS
USER_INCLDIR
USER_CMAKE_MODULE_PATH
USER_CMAKE_OPTS
USER_MKDEPENDS_OPTS
Customize the files in your ccs_config in your checkout for the given machine
Customize specfic file compilation by adding files to the Depends.$COMPILER file in ccs_config
I suggest documenting this in the wiki at first -- let me know if that's the right place (could be a discussion or in the CIME User's Guide)?
I also think there should be some documentation on this in your case in the Makefile and/or maybe the Macros files or in the README.case -- how does that sound?
Any other thoughts on the CIME build that people have?
Oh, another customization that's archived in the ccs_config is the Depends file for each compiler. Which allows you to add specific files to lists like these, which then have specific rules on compilation:
Thanks a lot for starting this discussion, @ekluzek , and for your comprehensive list of ways to customize the build. I hadn't been aware of some of these options myself, like the various USER_* env vars.
It feels like this belongs in the CIME User's Guide, but as @jgfouca points out, it's tricky that CESM and E3SM work differently.
What do people think about having some sections of the CIME User's Guide that only apply to certain models – either E3SM or CESM/NorESM? (Also including @mvertens in this discussion as we start to plan towards updating the CIME documentation for the upcoming CESM and NorESM releases.) In addition to this issue, this would also apply to other things like #1964. Based on discussion in #1964 , we were thinking at one point of having appendices for different models, but then later stopped considering that. Personally I feel like it could be better to put documentation like this in the main body rather than relegating it to an appendix, since it seems likely to get lost in an appendix, but would need a way to differentiate documentation that only applies to certain models. What do others think? We can also discuss on an upcoming CIME call.
Discussion from today's CIME call: People are generally happy with having some model-specific documentation in the CIME documentation. We can have a note on a page saying if it just applies to certain models. Feeling is that it's better to put it within the main organizational structure of CIME documentation rather than as an appendix.
Activity
ekluzek commentedon Apr 26, 2026
I'd like to hear from people:
Pinging a few folks: @billsacks @fischer-ncar @jgfouca @rljacob
ekluzek commentedon Apr 26, 2026
Oh, another customization that's archived in the ccs_config is the Depends file for each compiler. Which allows you to add specific files to lists like these, which then have specific rules on compilation:
PERFOJBS
REDUCED_OPT_OBJS
REDUCED_ERRORCHKS_IN_DEBUG
REDUCED_PRECISION_OBJS
SHR_RANDNUM_FORT_OBJS
SHR_RANDNUM_C_OBJS
PUMAS_OBJS
RRTMGP_OBJS
CLUBB_OBJS
jgfouca commentedon Apr 27, 2026
@ekluzek , when E3SM transitioned to a cmake build system, the behavior significantly diverged from what was there before and what CESM is using now. I've tried to keep this page up to date for us:
https://e3sm.atlassian.net/wiki/spaces/DOC/pages/1011942171/E3SM+Build+System+and+CMake
... but I don't know if any of that is useful to you.
billsacks commentedon Apr 27, 2026
Thanks a lot for starting this discussion, @ekluzek , and for your comprehensive list of ways to customize the build. I hadn't been aware of some of these options myself, like the various
USER_*env vars.It feels like this belongs in the CIME User's Guide, but as @jgfouca points out, it's tricky that CESM and E3SM work differently.
What do people think about having some sections of the CIME User's Guide that only apply to certain models – either E3SM or CESM/NorESM? (Also including @mvertens in this discussion as we start to plan towards updating the CIME documentation for the upcoming CESM and NorESM releases.) In addition to this issue, this would also apply to other things like #1964. Based on discussion in #1964 , we were thinking at one point of having appendices for different models, but then later stopped considering that. Personally I feel like it could be better to put documentation like this in the main body rather than relegating it to an appendix, since it seems likely to get lost in an appendix, but would need a way to differentiate documentation that only applies to certain models. What do others think? We can also discuss on an upcoming CIME call.
billsacks commentedon May 13, 2026
Discussion from today's CIME call: People are generally happy with having some model-specific documentation in the CIME documentation. We can have a note on a page saying if it just applies to certain models. Feeling is that it's better to put it within the main organizational structure of CIME documentation rather than as an appendix.
rljacob commentedon May 13, 2026
Its useful to compare how these dirs appear in CESM vs. E3SM.
CESM
CESM/ccs_config
CESM/cime_config
E3SM
E3SM/cime_config
github-actions commentedon Aug 12, 2026
This issue is stale because it has been open 90 days with no activity. Remove stale label or comment or this will be closed in 5 days.