# mk-ghcup-metadata

This script is used to automatically generate metadata suitable for consumption by
GHCUp.

# Usage

```
nix run -f .gitlab/rel_eng/ -c ghcup-metadata
```

```
options:
  -h, --help            show this help message and exit
  --metadata METADATA   Path to GHCUp metadata
  --pipeline-id PIPELINE_ID
                        Which pipeline to generate metadata for
  --release-mode        Generate metadata which points to downloads folder
  --fragment            Output the generated fragment rather than whole modified file
  --version VERSION     Version of the GHC compiler
  --date DATE           Date of the compiler release
```

The script also requires the `.gitlab/jobs-metadata.yaml` file which can be generated
by running `.gitlab/generate-ci/generate_jobs_metadata` script if you want to run it locally.


## CI Pipelines

The metadata is generated by the nightly and release pipelines.

* Nightly pipelines generate metadata where the bindist URLs point immediatley to
  nightly artifacts.
* Release jobs can pass the `--release-mode` flag which downloads the artifacts from
  the pipeline but the final download URLs for users point into the downloads folder.

The mapping from platform to bindist is not clever, it is just what the GHCUp developers
tell us to use.

## Testing Pipelines

The metadata is tested by the `ghcup-ci` repo which is triggered by the
`ghcup-metadata-testing-nightly` job.

This job sets the following variables which are then used by the downstream job
to collect the metadata from the correct place:

* `UPSTREAM_PIPELINE_ID`  - The pipeline ID which the generated metadata lives in
* `UPSTREAM_PROJECT_ID`   - The project ID for the upstream project (almost always `1` (for ghc/ghc))
* `UPSTREAM_JOB_NAME`     - The job which the metadata belongs to (ie `ghcup-metadata-nightly`)
* `UPSTREAM_PROJECT_PATH` - The path of the upstream project (almost always ghc/ghc)

Nightly pipelines are tested automaticaly but release pipelines are manually triggered
as the testing requires the bindists to be uploaded into the final release folder.



