Page Comparison

...

At a high-level, the diagram below describes how CIME handles these core components:

Image RemovedImage Added

To make sense of the above diagrams, use this legend:

...

• E3SM/cime_config/machines/config_machines.xml: Contains list of valid compilers (COMPILERS) and environment setup (modules, environment_variables).
• E3SM/cime_config/machines/config_compilers.xml: DEPRECATED. Contains specifications (flags, link flags, exe names) for compilers (gcc, pgi) as well as machine-specific modifications for those compilers.
• E3SM/cime_config/machines/cmake_macros/*: Contains specifications (flags, link flags, exe names) for compilers (gcc, pgi) as well as machine-specific modifications for those compilers. Replaces config_compilers.xml.
• E3SM/cime_config/machines/Depends.$compiler.$machine.cmake: Contains machine/compiler-specific flag changes for specific E3SM component files
• E3SM/cime_config/machines/Depends.$compiler.$machine: Contains machine/compiler-specific flag changes for shared-lib files, this system still uses Makefile syntax
• E3SM/cime/scripts/Tools/e3sm_compile_wrap.py: The default compile/link wrapper. It is used to produce timings of all operations
• E3SM/cime/scripts/machines/scripts/*: Python scripts to assist in managing cmake macro files.
• E3SM/components/CMakeLists.txt: The root CMakeLists.txt file for E3SM, mostly just iterates over components and calls functions
• E3SM/components/cmake/cmake_util.cmake: Contains some generally useful functions for cmake
• E3SM/components/cmake/build_mpas_model.cmake: Implements the handoff between E3SM's CMake system to MPAS's Cmake system

• E3SM/components/cmake/common_setup.cmake: Cmake setup common to all core components, this is only invoked ones (AFTER mpas is configured)

• E3SM/components/cmake/build_model.cmake: Implements how an individual core component gets configures (involves reading the Filepath and CCSM_cppdefs, globbing files, etc)
• E3SM/components/cmake/*/CMakeLists.txt: Very thin CMakeLists.txt files for each component type, this is just to ensure each component get it's own build area
• E3SM/components/*/bld/configure: Perl configure script for component, should produce Filepath and CCSM_cppdefs files
• E3SM/components/*/cime_config/buildnml: The buildnml script for component, controls what flags get passed to $component/bld/configure
• E3SM/components/*/cime_config/buildlib: The legacy buildlib driver for the classic deprecated Makefile-based build system
• E3SM/components/*/cime_config/buildlib_cmake: A insertion point for last-minute, component-specific changes before cmake is called. For example, mosart uses this file, not bld/configure, to generate Filepath and CCSM_cppdefs
• E3SM/components/mpas-source/src/CMakeLists.txt: The root CMakeLists.txt for MPAS
• E3SM/components/mpas-source/src/cmake_utils.cmake: Contains some generally useful functions for configuring MPAS
• E3SM/components/mpas-source/src/build_core.cmake: A generic implementation for building MPAS cores
• E3SM/components/mpas-source/src/core_landice/landice.cmake: The CMake definition of the landice core
• E3SM/components/mpas-source/src/core_ocean/ocean.cmake: The CMake definition of the ocean core
• E3SM/components/mpas-source/src/core_seaice/seaice.cmake: The CMake definition of the seaice core
• $case/Buildconf/*conf: The various build conf dirs for all active components, the Filepath and CCSM_cppdefs files for each component live here
• $case/Macros.cmake: The file that includes the relevant files in cmake_macros. You can modify this locally in your case.
• $case/cmake_macros/*: The files that ultimately sets flags, link flags, etc. You can modify this locally in your case.
• $case/Macros.make: A makefile macro derived from the cmake macros, needed for the sharedlibs that still use Makefile build systems. This is an auto-generated file that you should never edit.
• $EXEROOT/cmake-bld: The root cmake build/binary directory 
• $case/Tools/e3sm_compile_wrap.py: The case-specific compiler wrapper, this will start out as a copy of the e3sm_compile_wrap.py from the repo. Users can customize this one.

...

Be sure not to forget to source $case/.env_mach_specific.sh first so that your environment matches the CIME build environment. 'cd $EXEROOT/cmake-bld && make'. Copy the build line for the broken compilation from the build log file and paste it into your terminal and make tweaks.

...

Temporarily tweaking compiler flags for an entire component

For example, for atmeam:

% edit $case/cmake/atm/CMakeFiles/atm.dir/flags.make
% make

Temporarily tweak CPP defs for a component

Just edit the $case/Buildconf/${component}conf/CIME_cppdefs file and re-run either case.build or the appropriate cmake command

...

_macros/$compiler_$mach.cmake
* Add cmake code to check component name and make the corresponding change, e.g.
if (COMP_NAME STREQUAL eam)
  string(APPEND FFLAGS " -vector0")
endif()
% make

Temporarily tweak CPP defs for a component

Just edit the $case/Buildconf/${component}conf/Filepath CIME_cppdefs file and re-run either case.build or the appropriate cmake command

Temporarily tweak

...

Filepaths for a component

Just edit the $case/Macros.cmake /Buildconf/${component}conf/Filepath file and re-run either case.build . You will need to run case.build --clean if you've already or the appropriate cmake command

Temporarily tweak compilation or link flags for the entire build

Just edit the $case/cmake_macros/$compiler_$mach.cmake file and run case.build before the change.or make

Adding/removing files to be compiled

...

You'll need to edit either E3SM/components/$component/bld/configure OR E3SM/components/$component/cime_config/buildlib_cmake and make a PR to merge your change.

Permanently change compiler flags for a component

...

You can use the COMP_NAME and COMP_CLASS selectors in our config_compilers.xml:

...

or entire build

CMake macros are loaded in this order. If the macro doesn't exist, that level is skipped. Users will usually be working with the $compiler_$mach.cmake macro.

• universal.cmake : applies changes globally
• $compiler.cmake : applies changes for a compiler type (on all machines)
• $os.cmake : applies change for an OS
• $mach.cmake : applies changes for a machine (for all compilers)
• $compiler_$os.cmake : applies changes for a compiler/os combo (for all machines)
• $compiler_$mach.cmake : applies changes to a compiler/mach comb

You can write any cmake you want in these. The macros have access to all the key case settings which can be used for conditionals. The common variables to set/adjust in $compilers_$mach.cmake are:

• CFLAGS: flags for compiling C source files
• FFLAGS: flags for compiler fortran source files
• CXXFLAGS: flags for compiling CXX source files
• LDFLAGS: link flags
• CPPDEFS: c preprocessor definitions

Permanently change Filepaths for a component

...