Metadata-Version: 2.4
Name: ial_build
Version: 1.4.8
Summary: IAL-build: Tools for Source Code Management and build of IAL code.
Author-email: Alexandre Mary <alexandre.mary@meteo.fr>
License: CECILL-C
Project-URL: source, https://github.com/ACCORD-NWP/IAL-build.git
Project-URL: tracker, https://github.com/ACCORD-NWP/IAL-build/issues
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: ecbundle>=2.4.0
Dynamic: license-file

IAL-build
=========

*Tools for Source Code Management and build of IAL code.*

This package wraps around IAL git repo management, bundling (ecbundle package) and build systems
(for now gmkpack only) to help transitioning from source code to IAL binary executables.
It provides a python package to do so, as well as a set of command-line tools.

Dependencies
------------

* `ecbundle` : https://github.com/ecmwf/ecbundle (available on PyPI)
* Some (deprecated from CY50T2 onwards) functionalities may also clone and use [IAL-bundle](https://github.com/ACCORD-NWP/IAL-bundle), especially for the research of "official" bundles for main cycles.
  If you don't have internet connection at time of use, you may have to specify a local, pre-cloned, origin repository for IAL-bundle, using env variable `DEFAULT_IALBUNDLE_REPO`, e.g. `DEFAULT_IALBUNDLE_REPO=~/repositories/IAL-bundle`, or specifying it using command-line options, cf. help with option `-h`.

Installation
------------

`pip install ial_build`

Documentation
-------------

**Cache directory**:

  When using a bundle (and `ecbundle`), the repositories are cloned/downloaded in a sort of cache directory, so as to speed-up the next use: only a fetch of the requested branch or git reference will be done.
  The requested git reference is then checkedout in this cache repository, before being copied/cloned into the pack (in the case of gmkpack).

Tools
-----

When installed with `pip`, a bunch of `ial-*` commands are available in order to :
* help finding bundles (`ial-find_bundle`, `ial-get_bundle`)
* make packs (gmkpack) from bundles or IAL branches (`ial-to_pack`, `ial-git2pack`, `ial-bundle2pack`).
They are auto-documented, see their argument `-h`.

Some examples:

### From CY50T2 onwards, create a pack from IAL

From CY50T2 onwards, the bundle is included in IAL repo, making obsolete the bundle-specific tools.
They are left for use with cycles < CY50T2 only.
The only relevant tool therefore is `ial-to_pack`.

```
ial-to_pack [<IAL_git_ref>] [-t main|incr]
```

Notes:
* If `<IAL_git_ref>` is not provided, the currently checkedout reference is taken.
* The hub sub-packages are taken from `bundle/bundle.yml` in IAL, or specified otherwise by command-line argument.

### PRIOR to CY50T2

#### Prepare a bundle for a personal branch

* Find a bundle appropriate for my IAL branch <my_branch>, based on CY50:
  ```
  % ial-find_bundle my_branch
  BDL50-default
  ```

* Get this bundle:
  ```
  % ial-get_bundle BDL50-default [-t my_bundle.yml]
  ```

* Edit and replace `CY50` in `my_bundle.yml`

* Create a root pack from my bundle:
  ```
  % ial-bundle2pack my_bundle.yml [...pack creation arguments, cf. -h]
  ```

#### Install a root pack of `BDL50-default`

```
ial-bundle2pack BDL50-default
```
will:
* look for a bundle tagged `BDL50-default` in the [IAL-bundle](https://github.com/ACCORD-NWP/IAL-bundle) repository,
* download it
* clone/fetch/checkout each package referenced in the bundle in the requested version, in a cache local directory (cf. option `-d`)
* create a pack (by default: main)
* populate the pack with the source codes checkedout for each package

#### Install a root(=main) pack for the recommended (default) bundle for CY50

```
ial-git2pack -t main CY50 [...]
```
will:
* find a bundle appropriate for CY50 in IAL-bundle repository
* then do the same as `ial-bundle2pack`

#### Install an incremental pack with the content of my IAL branch on top of its most recent official ancestor pack
```
ial-git2pack my_branch
```

#### Install a pack with a modified branch in `oops` only

1. get a local copy of a bundle file that fits the basis of your development, e.g.
  ```
  ial-find_bundle --get_copy CY50
  ```
2. rename and edit your bundle file, setting your (potentially local) oops repository and branch
3. in the bundle file still, set attribute `incremental_pack` of the `oops_src` project to `True`
4. create your pack using
   ```
   ial-bundle2pack <my_bundle.yml> -t incr
   ```
