133 lines
5.4 KiB
ReStructuredText
133 lines
5.4 KiB
ReStructuredText
Obtaining the full model code and associated scripting infrastructure
|
|
=====================================================================
|
|
|
|
[!CAUTION]
|
|
This is deprecated and will be replaced with git submodules. See
|
|
https://github.com/ESCOMP/CTSM/pull/2443
|
|
|
|
|
|
CTSM is released via GitHub. You will need some familiarity with git in order
|
|
to modify the code and commit these changes. However, to simply checkout and run the
|
|
code, no git knowledge is required other than what is documented in the following steps.
|
|
|
|
To obtain the CTSM code you need to do the following:
|
|
|
|
#. Clone the repository. ::
|
|
|
|
git clone https://github.com/escomp/ctsm.git my_ctsm_sandbox
|
|
|
|
This will create a directory ``my_ctsm_sandbox/`` in your current working directory.
|
|
|
|
#. Run the script **manage_externals/checkout_externals**. ::
|
|
|
|
./manage_externals/checkout_externals
|
|
|
|
The **checkout_externals** script is a package manager that will
|
|
populate the ctsm directory with the relevant versions of each of the
|
|
components along with the CIME infrastructure code.
|
|
|
|
At this point you have a working version of CTSM.
|
|
|
|
To see full details of how to set up a case, compile and run, see the CIME documentation at http://esmci.github.io/cime/ .
|
|
|
|
More details on checkout_externals
|
|
----------------------------------
|
|
|
|
The file **Externals.cfg** in your top-level CTSM directory tells
|
|
**checkout_externals** which tag/branch of each component should be
|
|
brought in to generate your sandbox. **Externals_CLM.cfg** is used similarly to point to the correct version of FATES (and possibly other CTSM-specific externals in the future); the below instructions referring to **Externals.cfg** also apply to modifying **Externals_CLM.cfg**.
|
|
|
|
NOTE: checkout_externals will always attempt
|
|
to make the working copy exactly match the externals description. If
|
|
you manually modify an external without updating Externals.cfg, e.g. switch
|
|
to a different tag, then rerunning checkout_externals will switch you
|
|
back to the external described in Externals.cfg. See below
|
|
documentation `Customizing your CTSM sandbox`_ for more details.
|
|
|
|
**You need to rerun checkout_externals whenever Externals.cfg has
|
|
changed** (unless you have already manually updated the relevant
|
|
external(s) to have the correct branch/tag checked out). Common times
|
|
when this is needed are:
|
|
|
|
* After checking out a new CTSM branch/tag
|
|
|
|
* After merging some other CTSM branch/tag into your currently
|
|
checked-out branch
|
|
|
|
**checkout_externals** must be run from the root of the source
|
|
tree. For example, if you cloned CTSM with::
|
|
|
|
git clone https://github.com/escomp/ctsm.git my_ctsm_sandbox
|
|
|
|
then you must run **checkout_externals** from
|
|
``/path/to/my_ctsm_sandbox``.
|
|
|
|
To see more details of **checkout_externals**, issue ::
|
|
|
|
./manage_externals/checkout_externals --help
|
|
|
|
Customizing your CTSM sandbox
|
|
=============================
|
|
|
|
There are several use cases to consider when you want to customize or modify your CTSM sandbox.
|
|
|
|
Switching to a different CTSM branch or tag
|
|
-------------------------------------------
|
|
|
|
If you have already checked out a branch or tag and **HAVE NOT MADE ANY
|
|
MODIFICATIONS** it is simple to change your sandbox. Say that you
|
|
checked out ctsm1.0.0 but really wanted to have ctsm1.1.0;
|
|
you would simply do the following::
|
|
|
|
git checkout ctsm1.1.0
|
|
./manage_externals/checkout_externals
|
|
|
|
You should **not** use this method if you have made any source code
|
|
changes, or if you have any ongoing CTSM cases that were created from
|
|
this sandbox. In these cases, it is often easiest to do a second **git
|
|
clone**.
|
|
|
|
Pointing to a different version of a component
|
|
----------------------------------------------
|
|
|
|
Each entry in **Externals.cfg** has the following form (we use CIME as an
|
|
example below)::
|
|
|
|
[cime]
|
|
local_path = cime
|
|
protocol = git
|
|
repo_url = https://github.com/CESM-Development/cime
|
|
tag = cime5.4.0-alpha.20
|
|
required = True
|
|
|
|
Each entry specifies either a tag, a hash or a branch. To point to a new tag:
|
|
|
|
#. Modify the relevant entry/entries in **Externals.cfg** (e.g., changing
|
|
``cime5.4.0-alpha.20`` to ``cime5.4.0-alpha.21`` above)
|
|
|
|
#. Checkout the new component(s)::
|
|
|
|
./manage_externals/checkout_externals
|
|
|
|
To point to a hash, the process is the same, except also change ``tag = ...`` to ``hash = ...``.
|
|
|
|
To point to a branch, use ``branch = ...``. Pointing to a branch means that, each time you run ``manage_externals/checkout_externals`` you will get the current latest version of that branch. This can be convenient for in-progress development work, but should not be used when you need a stable version for scientific simulations. There are a number of gotchas with this workflow, so in general you should default to pointing to fixed hashes. (For CTSM master, we require a fixed hash or, usually, a tag.)
|
|
|
|
Keep in mind that changing individual components from a tag may result
|
|
in an invalid model (won't compile, won't run, not scientifically
|
|
meaningful) and is unsupported.
|
|
|
|
Committing your change to Externals.cfg
|
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
After making this change, it's a good idea to commit the change in your
|
|
local CTSM git repository. First create a branch in your local
|
|
repository, then commit it. (Unlike with subversion, branches are stored
|
|
locally unless you explicitly push them up to GitHub. Feel free to
|
|
create whatever local branches you'd like.) For example::
|
|
|
|
git checkout -b my_ctsm_branch
|
|
git add Externals.cfg
|
|
git commit -m "Update CIME to cime5.4.0-alpha.20"
|
|
|