fre.make.create_checkout_script module

Create_checkout_script provides methods to generate a checkout.sh script from a YAML configuration file. Checkout.sh git clones all component source repositories listed under the src key of the compile.yaml.

The method checkout_create is the entry point called by fre make checkout-script and fre make all. Checkout_create calls baremetal_checkout_write for a bare-metal build or container_checkout_write for a container build to write checkout.sh.

fre.make.create_checkout_script.baremetal_checkout_write(model_yaml: freyaml, src_dir: str, jobs: str, parallel_cmd: str, execute: bool)

Baremetal_checkout_write generates the checkout.sh script and optionally executes the script to git clone the component repositories in preparation for model compilation.

Called by checkout_create for each bare-metal platform, this method - reads the compile section of the resolved YAML to determine source repositories for each component, - writes checkout.sh into src_dir, - optionally executes checkout.sh afterwards

Parameters:

  • model_yaml (yamlfre.freyaml) – is the parsed and validated YAML object containing the compile specifications (source repositories, experiment name, etc.).

  • src_dir (str) – is the absolute path of the directory where checkout.sh will be written and where the source repositories will be cloned. Typically, src_dir = [modelRoot]/[experiment]/src where modelRoot is defined in platforms.yaml.

  • jobs (str) – is the number of git submodules to fetch simultaneously, passed to git clone –jobs (relevant only if the component repository contain submodules.)

  • parallel_cmd (str) – is the shell suffix appended to each git clone command to control concurrency. Pass “ &” to background each clone (parallel checkout) or “” to clone sequentially.

  • execute (bool) – is a flag where if True, checkout.sh is executed immediately after creation. Defaults to False.

fre.make.create_checkout_script.checkout_create(yamlfile: str, platform: tuple, target: tuple, no_parallel_checkout: bool | None = None, njobs: int = 4, execute: bool | None = False, force_checkout: bool | None = False)

Checkout_create is the entry point for fre make checkout-script. The method resolves the YAML configuration and calls baremetal_checkout_write or container_checkout_write for each specified platform.

Parameters:

  • yamlfile (str) – is the path to the model YAML configuration file (e.g. am5.yaml).

  • platform (tuple[str]) – is one or more FRE platform strings as defined in platforms.yaml.

  • target (tuple[str]) – is one or more mkmf target strings (e.g. debug-openmp, repro-openmp, prod-openmp).

  • no_parallel_checkout (bool, optional) – is a flag where if True, git clone component repositories sequentially. Defaults to False to enable parallel checkout for bare-metal builds; Option will be removed for container builds in the future.

  • njobs (int) – is the number of git submodules to fetch simultaneously, passed to git clone –jobs. Defaults to 4.

  • execute (bool, optional) – If True, execute checkout.sh immediately after writing it (bare-metal only). Defaults to False.

  • force_checkout (bool, optional) – is a flag to control behavior when checkout.sh already exists. If True for for bare-metal build, renames the existing src directory with a YYYYmmdd.HHMMSS timestamp suffix, then writes a fresh checkout.sh in a new src directory. For container build, deletes the existing tmp/[platform]/checkout.sh and writes a new one in its place. Defaults to False.

Raises:

  • ValueError –

    • If njobs is passed as a boolean while –execute is also set (ambiguous intent — njobs must be an explicit integer).

    • If a specified platform name does not exist in platforms.yaml.

  • OSError – When checkout.sh returns a non-zero exit code during execution. (applicable when execute is True for a bare-metal build).

fre.make.create_checkout_script.container_checkout_write(model_yaml: freyaml, src_dir: str, tmp_dir: str, jobs: str, parallel_cmd: str)

Container_checkout_write generates checkout.sh for a container build.

Called by checkout_create for each container platform, this method writes checkout.sh into a temporary directory on the host (tmp/[platform-name]/) where the script will eventually be COPY-ed to the container image filesystem. The script will be executed during the container build to git clone the component repositories serially.

Parameters:

  • model_yaml (yamlfre.freyaml) – is the parsed and validated YAML object containing the compile specifications (source repositories, experiment name, etc.).

  • src_dir (str) – is the source-code path inside the running container where repositories will be cloned. Set to [modelRoot]/[experiment]/src where modelRoot is defined in platforms.yaml.

  • tmp_dir (str) – is the local temporary directory on the host (outside the container) where checkout.sh is staged before being COPYed into the image. Typically tmp/[platform-name].

  • jobs (str) – is the number of git submodules to fetch simultaneously, passed to git clone –jobs. Unused argument for this method and should be removed.

  • parallel_cmd (str) – is a flag not used in this method and should be removed.