Skip to content

Commit

Permalink
modified: README.md
Browse files Browse the repository at this point in the history
- Adding instructions to fetch hash and use the wrofklow with multiple
  dep options now available
  • Loading branch information
F-WRunTime committed Jan 23, 2025
1 parent 8a0b2ab commit a859c9f
Showing 1 changed file with 29 additions and 10 deletions.
39 changes: 29 additions & 10 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -72,6 +72,7 @@ make cov-integration TEST_ARGS="--numprocesses=8 --update-expected-output"
```

### Build Development Kontrol Image with Fixed Upstream Dependencies
--------------------------------
Relevant to this workflow [kontrol-push-fixed-deps.yml](.github/workflows/kontrol-push-fixed-deps.yml)
>This is relevant for internal development to publish development images of kontrol with modified kontrol chagnes and retains fixed upstream dependencies.
The usecase for this workflow is intended to make testing changes of kontrol needed for use in testing CI or in other downstream workflows without needing to publish changes or PRs first.
Expand All @@ -80,13 +81,15 @@ Intent is to reduce friction of needing custom builds and avoiding lengthy upstr



### Build Kontrol with Kup and Specific Dependency Override
### Build Kontrol with Kup and Specific Dependency Overrides
--------------------------------
Relevant to this workflow [kup-build-kontrol.yml](.github/workflows/kontrol-push-unfixed-deps.yml)
> This is relevant for internal development to publish development images of kontrol for use in kaas or a dockerized test environment.
Use the workflow [Kup Build Kontrol](.github/workflows/kup-build-kontrol.yml) to publish a custom version of Kontrol for use in CI and [KaaS](https://kaas.runtimeverification.com/).
[See KUP docs for more information](https://github.com/runtimeverification/kup/blob/master/src/kup/install-help.md#kup-install----override)

#### Using Kup
-------------
Relevant dependency options are shown below and can be listed using `kup list kontrol --inputs`
For example:
```
Expand All @@ -113,23 +116,39 @@ Inputs:
│ └── rv-utils - follows kevm/k-framework/rv-utils
└── rv-utils - follows kevm/rv-utils
```
> **Notice**: the 'follows' in the 'kup list' output. This shows the links to the important dependencies and which are affected when you set the overrides.
Now run a build using kup and specific dependency overrides:

`kup install kontrol --override kevm/haskell-backend "hash/branch_name" --override kevm/k-framework/haskell-backend "hash/branch_name"`
`kup install kontrol --override kevm/k-framework/haskell-backend "hash/branch_name" --override kevm/k-framework/haskell-backend "hash"`

> **Note**: It's important that you use the short-rev hash or the long for specific revisions of the dependencies to modify.
#### Using the workflow and publish to ghcr.io/runtimeverification
The workflow takes a single input and ONLY a single override to fill in the paramater '--override' which is a string following the path from the above dep tree to be passed to kup install. Explained in more detail above.
#### Using the workflow to publish to ghcr.io/runtimeverification
--------------------------------

Running the workflow by providing the override desired for the build.
#### Running the workflow
- Go to repo [Kontrol Actions Page](https://github.com/runtimeverification/kontrol/actions)
- Click on "Push Kontrol w/ Dependencies" from the left hand list
- Click on "Run Workflow" on the top right corner of the list of workflow runs is an option "Run Workflow".
- Use the 'master' branch unless you're doing something special.
- Input the override hash strings for specific dependencies to override in kontrol. See below on how to find the hash for the dependency.
- Then click "Run Workflow" and a job will start.
- The workflow summary shows the name of the image that was built and pushed e.g. ghcr.io/runtimeverification/kontrol-custom:tag

Example using the workflow to publish a ghcr.io/runtimeverification/kontrol-custom:tag image using kup `override` with a custom version of haskell-backend
> **Note**: The tag will be a randomly generated string.
The string to input to the workflow input job Under Actions > "Push Kontrol w/ Dependencies" on the top right corner of the list of workflow runs is an option "Run Workflow".
Select this option and input the override string as `kevm/k-framework/haskell-backend "hash/branch name"`
Then click "Run Workflow" and a job will start. The image when finished will be published to ghcr.io/runtimeverification/kontrol-custom:tag
[The workflow](.github/workflows/kontrol-push-unfixed-deps.yml) takes multiple inputs to override the various components of kontrol. Those overrides are listed above in the example output of 'kup list kontrol --inputs'

The tag will be a randomly generated string. See the workflow summary for the full name of the image to use in KaaS or pull down locally with `docker pull ghcr.io/runtimeverification/kontrol-custom:tag`
To set the desired revisions of the dependencies. Find the associated hash on the branch and commit made to be used for the dependnecy override.
If an input is left blank, the workflow will workout the default hash to use based on kontrols latest release.

Example to fetch the desired hash to insert a different dependency version into the kontrol build.
Substitude the k-framework revision used to build kontrol.
```
K_TAG=$(curl -s https://raw.githubusercontent.com/runtimeverification/kontrol/master/deps/k_release)
git ls-remote https://github.com/runtimeverification/k.git refs/tags/v${K_TAG} | awk '{print $1}'
```

## Resources

Expand Down

0 comments on commit a859c9f

Please sign in to comment.