# Building ICON :::{hint} _auto-icon_ takes care of building the ICON model for you - but it is configurable. ::: This page is on how to configure this if the default does not suit you. By default, the model is built once (per Autosubmit experiment, but can also be shared between experiments on the same machine) and the latest version of the model code is used for this. ## Building ICON with the configure scripts Building ICON with the configure scripts is the recommended way for all machines for which these scripts exist. ### Main build options There are a few options determining how the model is build, collected in the `ICON` section of the configuration. This section is contained in `conf/common/build.yml` (linked as `/build.yml`). Additionally, the configure file (`ICON.CONFIG_FILE:`) to be used is specified in the platform-specific config file `conf/common/platforms/.yml`. The most important configure options are | Option | Description | |--------------|-------------| | OPTIONS | extra configure options passed on to the configure script | | ENSURE_BUILD | always trigger an (incremental) build, i.e. run `make`
This is most useful for model development. | | BRANCH | branch to be build | | COMMIT | commit to check out
`HEAD`: (default): latest commit of the specified branch
`CURRENT`: uses the current status of the repo; useful for editing the repo in-place | | | SHA of _commit_ or _tag_ | | SUBMODULES | use specific submodule branches or commits. The syntax is `::`, where submodule is the submodules name, e.g. `art`, and `branch` and `commit` are analogous to above | Some notes on further options are explained in more detail in the following. ### Model version By default, the `icon-nwp` repository in the latest version (current `HEAD`) of the default branch `master` is pulled and built. This can be changed with the options `GROUP`, `SLUG`, `BRANCH` and `COMMIT`. The repository `/` will be pulled and the respective branch will be used. If `COMMIT: HEAD` is set, the latest version of the branch is used, if it points to a specific commit hash, this one will be used. If `COMMIT: CURRENT` is set, no pull will be performed but instead the current version in the (existing) repository will be used. If there is none, the behavior is the same as with `HEAD`. :::{note} In the _auto-icon_ branch `public`, the default repository is the public ICON repository `icon/icon-model` in the latest release. ::: ### Installation directory The `%HPCROOTDIR%` is the root directory for the Autosubmit experiment on the cluster and can differ from cluster to cluster. On both HoreKa and Levante this is `~/`. A directory referred to as `%AISHAREDIR%` is used by _auto-icon_ for ICON and the Python venv. By default, it is set to `%HPCROOTDIR%`, but can also be set to a different directory to share the ICON installation and/or Python venv. `%AISHAREDIR%` can be set at the top of the `build.yml` configuration file or directly with the `--share` option of the init script. ICON is cloned in this directory, creating a subdirectory called like the ICON model project (specifically like the option `ICON.SLUG`). All configure and build files are stored in a subdirectory `icon-build` and finally it is installed in a directory `icon`. This directory is also used when searching for [input files](/Userguide/Input-data.md#pool-directories). These directories can be modified with the options `INSTALLDIR`, `BUILDDIR` and `REPODIR`. ### Model development with auto-icon _auto-icon_ is designed to be a useful tool for both production simulations and for model development. To use it for model development, the recommended workflow is as follows: 1. Create an experiment with _auto-icon_ that reflects your experiment for testing. (Obviously this can be repeated for several different experiments.) 1. When running the init script, use the option `-b` to link the file containing the build configuration. 2. Configure the experiment to suit your purposes. Using several members might be interesting to test several similar use cases, e.g. using a new flag and also a reference case. 3. Set the appropriate parameters for building the model, specifically the branch and the [policy to build](#model-version) the model. ### Re-building and incremental builds If the `BUILD_ICON` job is started again, when the model has already been built before, *auto-icon* will check if a binary exists and skip the build if so. This behavior can be changed with the option `ENSURE_BUILD` (rebuild even if a binary exists; no configure will be done in this case, making an incremental build). The option `REBUILD_FROM_SCRATCH` does what it says: all the named icon directories will be cleared in a first step, then a new build is started with `git clone` -> configure -> build. ## Building ICON with spack Configure scripts do not exist for all machines. For these machines, ICON can be built with `spack`. To do so, in the file `conf/common/build.yml` set the option `BUILD_TYPE: spack`. The corresponding section in this file allows detailed configuration on how to build ICON. This has to be adjusted to the respective machine, some details and examples can be found in the [Quick start guide](/Introductory-guides/Quick-start.md).