Skip to content

Update adding new software instructions after splitting software-layer and software-layer-scripts #501

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 5 commits into
base: main
Choose a base branch
from
Open

Update adding new software instructions after splitting software-layer and software-layer-scripts #501

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
227576e
Merge pull request #1 from Neves-P/update/dev.eessi.io-docs
Neves-P Jun 25, 2025
83b4dd6
Merge branch 'main' of github.com:EESSI/docs
Neves-P Jul 1, 2025
45ddda0
Update adding software pages with new structure
Neves-P Jul 1, 2025
260cf6e
Rephrase software-layer-scripts
Neves-P Jul 1, 2025
fae8c8d
Merge branch 'EESSI:main' into update/open-pr
Neves-P Jul 1, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 2 additions & 2 deletions docs/adding_software/building_software.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -61,8 +61,8 @@ Once the ingestion has been done, simply re-triggering the CI workflow should be

!!! note
This assumes that the easystack file being modified is considered by the CI workflow file
(`.github/workflows/test_eessi.yml`) that checks for missing installations, in the correct branch (for example
`2023.06`) of the [software-layer](https://github.com/EESSI/software-layer).
(`.github/workflows/test_eessi.yml`) that checks for missing installations, in the `main` branch of the
[software-layer](https://github.com/EESSI/software-layer).

If that's not the case yet, update this workflow in your pull request as well to add the missing easystack file!

Expand Down
29 changes: 19 additions & 10 deletions docs/adding_software/opening_pr.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -41,24 +41,34 @@ git remote add koala git@github.com:koala/software-layer.git
```

3) Check out the branch that corresponds to the version of EESSI repository you want to add software to,
for example `2023.06-software.eessi.io`:
for example `main`:

```
git checkout 2023.06-software.eessi.io
git checkout main
```

!!! note
The commands above only need to be run once, to prepare your setup for making pull requests.

!!! info "Changes to [EESSI/software-layer](https://github.com/EESSI/software-layer)"

On 2025-06-11 the [EESSI/software-layer](https://github.com/EESSI/software-layer) repository was split to primarily include
easystack files necessary for triggering builds. Most scripts needed to build the software have been moved to the new
repository [EESSI/software-layer-scripts](https://github.com/EESSI/software-layer-scripts). In addition,
installations to particular EESSI versions are no longer tracked by branches in
[EESSI/software-layer](https://github.com/EESSI/software-layer) (e.g., the old `2023.06-software.eessi.io` branch), but
by editing or creating the easystack file in the corresponding directory (e.g., `easystacks/software.eessi.io/2023.06/` to
target version `2023.06`).

### Creating a pull request {: #software_layer_pull_request }

1) Make sure that your `2023.06-software.eessi.io` branch in the checkout of the
1) Make sure that your `main` branch in the checkout of the
[`EESSI/software-layer`](https://github.com/EESSI/software-layer) repository is up-to-date

```
cd EESSI/software-layer
git checkout 2023.06-software.eessi.io
git pull origin 2023.06-software.eessi.io
git checkout main
git pull origin main
```

2) Create a new branch (use a sensible name, not `example_branch` as below), and check it out
Expand Down Expand Up @@ -91,20 +101,19 @@ git push koala example_branch
6) Go to the [GitHub web interface](https://github.com/EESSI/software-layer) to open your pull request,
or use the helpful link that should show up in the output of the `git push` command.

**Make sure you target the correct branch**: the one that corresponds to the version of EESSI you want to add
software to (like `2023.06-software.eessi.io`).
**Make sure you target the `main` branch.**

If all goes well, one or more bots :robot: should almost instantly create a comment in your pull request
with an overview of how it is configured - you will need this information when providing build instructions.

### Rebuilding software {: #rebuilding_software }
We typically do not rebuild software, since (strictly speaking) this breaks reproducibility for anyone using the software. However, there are certain situations in which it is difficult or impossible to avoid.
We typically do not rebuild software, since (strictly speaking) this breaks reproducibility for anyone using it. However, there are certain situations in which it is difficult or impossible to avoid.

To do a rebuild, you add the software you want to rebuild to a dedicated easystack file in the `rebuilds` directory. Use the following naming convention: `YYYYMMDD-eb-<EB_VERSION>-<APPLICATION_NAME>-<APPLICATION_VERSION>-<SHORT_DESCRIPTION>.yml`, where `YYYYMMDD` is the opening date of your PR. E.g. `2024.05.06-eb-4.9.1-CUDA-12.1.1-ship-full-runtime.yml` was added in a PR on the 6th of May 2024 and used to rebuild CUDA-12.1.1 using EasyBuild 4.9.1 to resolve an issue with some runtime libraries missing from the initial CUDA 12.1.1 installation.
To do a rebuild, you add the software you want to rebuild to a dedicated easystack file in the `rebuilds` subdirectory inside each version's directory. Use the following naming convention: `YYYYMMDD-eb-<EB_VERSION>-<APPLICATION_NAME>-<APPLICATION_VERSION>-<SHORT_DESCRIPTION>.yml`, where `YYYYMMDD` is the opening date of your PR. E.g. `20240506-eb-4.9.1-CUDA-12.1.1-ship-full-runtime.yml` was added in a PR on the 6th of May 2024 and used to rebuild CUDA-12.1.1 using EasyBuild 4.9.1 to resolve an issue with some runtime libraries missing from the initial CUDA 12.1.1 installation.

At the top of your easystack file, please use comments to include a short description, and make sure to include any relevant links to related issues (e.g. from the GitHub repositories of EESSI, EasyBuild, or the software you are rebuilding).

As an example, consider the full easystack file (`2024.05.06-eb-4.9.1-CUDA-12.1.1-ship-full-runtime.yml`) used for the aforementioned CUDA rebuild:
As an example, consider the full easystack file (`20240506-eb-4.9.1-CUDA-12.1.1-ship-full-runtime.yml`) used for the aforementioned CUDA rebuild:

```yaml
# 2024.05.06
Expand Down