Add GitHub Actions workflow template & documentation

This commit is contained in:
Luke Street 2024-03-05 17:24:27 -07:00
parent 2b626fb53e
commit afb82c88dc
10 changed files with 130 additions and 14 deletions

View File

@ -0,0 +1,63 @@
name: Build
on:
push:
pull_request:
jobs:
build:
# This is a *private* build container.
# See docs/github_actions.md for more information.
container: ghcr.io/my/game-build:main
runs-on: ubuntu-latest
strategy:
fail-fast: false
matrix:
# Add game versions here
version: [GAMEID]
steps:
# Checkout the repository (shallow clone)
- name: Checkout
uses: actions/checkout@v3
with:
fetch-depth: 0
submodules: recursive
# Set Git config
- name: Git config
run: git config --global --add safe.directory "$GITHUB_WORKSPACE"
# Copy the original files to the workspace
- name: Prepare
run: cp -R /orig .
# Build the project
- name: Build
run: |
python configure.py --map --version ${{ matrix.version }} \
--binutils /binutils --compilers /compilers
ninja all_source build/${{ matrix.version }}/progress.json
# Upload progress if we're on the main branch
- name: Upload progress
# If you're using a different branch, change this to match
if: github.ref == 'refs/heads/main'
continue-on-error: true
env:
# Replace with your project slug
PROGRESS_SLUG: prime
# Set the API key in your repository secrets
PROGRESS_API_KEY: ${{ secrets.PROGRESS_API_KEY }}
run: |
python tools/upload_progress.py -b https://progress.decomp.club/ \
-p $PROGRESS_SLUG -v ${{ matrix.version }} \
build/${{ matrix.version }}/progress.json
# Upload map files
- name: Upload map
uses: actions/upload-artifact@v3
with:
name: ${{ matrix.version }}_maps
path: build/${{ matrix.version }}/**/*.MAP

View File

@ -12,6 +12,7 @@ Documentation
- [Getting Started](docs/getting_started.md)
- [`symbols.txt`](docs/symbols.md)
- [`splits.txt`](docs/splits.md)
- [GitHub Actions](docs/github_actions.md) (new!)
General:
@ -54,7 +55,7 @@ Features
- No manual assembly: decomp-toolkit handles splitting the DOL into relocatable objects based on the configuration. No game assets are committed to the repository.
- Progress calculation and upload script for [frogress](https://github.com/decompals/frogress).
- Integration with [objdiff](https://github.com/encounter/objdiff) for a diffing workflow.
- (TODO) CI workflow template for GitHub Actions.
- CI workflow template for GitHub Actions.
Project structure
-----------------

View File

@ -5,7 +5,7 @@ Windows
--------
On Windows, it's **highly recommended** to use native tooling. WSL or msys2 are **not** required.
When running under WSL, [objdiff](#diffing) is unable to get filesystem notifications for automatic rebuilds.
When running under WSL, [objdiff](https://github.com/encounter/objdiff) is unable to get filesystem notifications for automatic rebuilds.
- Install [Python](https://www.python.org/downloads/) and add it to `%PATH%`.
- Also available from the [Windows Store](https://apps.microsoft.com/store/detail/python-311/9NRWMJP3717K).

View File

@ -2,27 +2,27 @@
See [Dependencies](dependencies.md) first.
Clone this template repository.
1. [Create a new repository from this template](https://github.com/new?template_name=dtk-template&template_owner=encounter), then clone it.
Rename `orig/GAMEID` to the game's ID. (For example, `GLZE01` for _The Legend of Zelda: The Wind Waker_.)
2. Rename `orig/GAMEID` to the game's ID. (For example, `GLZE01` for _The Legend of Zelda: The Wind Waker_.)
Extract your game to `orig/[GAMEID]`. In Dolphin, use "Extract Entire Disc" for GameCube games, or use "Data Partition" -> "Extract Entire Partition" for Wii games.
3. Extract your game to `orig/[GAMEID]`. In Dolphin, use "Extract Entire Disc" for GameCube games, or use "Data Partition" -> "Extract Entire Partition" for Wii games.
Rename `config/GAMEID` to the game's ID and modify `config/[GAMEID]/config.yml` appropriately, using [`config.example.yml`](/config/GAMEID/config.example.yml) as a reference. If the game doesn't use RELs, the `modules` list in `config.yml` can be removed.
4. Rename `config/GAMEID` to the game's ID and modify `config/[GAMEID]/config.yml` appropriately, using [`config.example.yml`](/config/GAMEID/config.example.yml) as a reference. If the game doesn't use RELs, the `modules` list in `config.yml` can be removed.
Generate a `config/[GAMEID]/build.sha1` file for verification. This file is a list of SHA-1 hashes for each build artifact. One possible way:
5. Generate a `config/[GAMEID]/build.sha1` file for verification. This file is a list of SHA-1 hashes for each build artifact. One possible way:
```sh
dtk shasum orig/[GAMEID]/sys/main.dol orig/[GAMEID]/files/*.rel > config/[GAMEID]/build.sha1
```
```sh
dtk shasum orig/[GAMEID]/sys/main.dol orig/[GAMEID]/files/*.rel -o config/[GAMEID]/build.sha1
```
Then, modify the paths in `config/[GAMEID]/build.sha1` to point to the `build` directory instead of `orig`. The DOL will be built at `build/[GAMEID]/main.dol`, and modules will be built at `build/[GAMEID]/[module_name]/[module_name].rel`.
6. Modify the paths in `config/[GAMEID]/build.sha1` to point to the `build` directory instead of `orig`. The DOL will be built at `build/[GAMEID]/main.dol`, and modules will be built at `build/[GAMEID]/[module_name]/[module_name].rel`.
Update `VERSIONS` in [`configure.py`](/configure.py) with the game ID.
7. Update `VERSIONS` in [`configure.py`](/configure.py) with the game ID.
Run `python configure.py` to generate the initial `build.ninja`.
8. Run `python configure.py` to generate the initial `build.ninja`.
Run `ninja` to perform initial analysis.
9. Run `ninja` to perform initial analysis.
If all goes well, the initial `symbols.txt` and `splits.txt` should be automatically generated. Though it's likely it won't build yet. See [Post-analysis](#post-analysis) for next steps.

52
docs/github_actions.md Normal file
View File

@ -0,0 +1,52 @@
# GitHub Actions
This repository includes [.github.example/workflows/build.yml](/.github.example/workflows/build.yml) as an example CI workflow. To use it for your project, follow the setup instructions below.
- [Build Repository](#build-repository)
- [Progress](#progress)
- [Workflow](#workflow)
## Build Repository
This repository will be used to build and store the CI build container.
> [!CAUTION]
> This repository should be **private** to avoid exposing the game's assets.
1. [Create a **private** repository from `encounter/dtk-template-build`](https://github.com/new?template_name=dtk-template-build&template_owner=encounter). A common name is your project's repository name with `-build` appended. For example, `tww-build`.
2. Once the repository is created, add your game's assets to the `orig/GAMEID` directory. (Replace `GAMEID` with your game's ID, matching the `orig` layout in your main repository.)
**Only include game files necessary for the build**, such as `sys/main.dol` and any `.rel` or `.sel` files.
3. Once the build container action completes, visit the package settings:
![GitHub repository packages](images/github_build_repo_packages.png)
![GitHub package settings](images/github_package_settings.png)
4. Under "Manage Actions access", add your project's main repository with the "Read" role:
![GitHub package Actions access](images/github_package_settings_access.png)
## Progress
1. In the [GC/Wii Decompilation Discord](https://discord.gg/hKx3FJJgrV), visit `#frogress` and request an API key for your project.
Please provide the following:
- Project name
- Repository URL
- Game ID(s)
- Whether the game has RELs
2. On GitHub, visit your repo's `/settings/secrets/actions/new` and add a new secret with the name `PROGRESS_API_KEY`:
![GitHub Actions secrets](images/github_actions_secrets.png)
## Workflow
1. Rename `.github.example` to `.github`.
2. In `build.yml`, update the `container:` to point to the new [build image](#build-repository).
3. In `build.yml`, replace `GAMEID` with your game's ID. (Or list of IDs, for multi-version support.)
4. In `build.yml`, update `PROGRESS_SLUG` to match the project name on [frogress](#progress).
5. Commit and push the changes to your repository.
If everything is set up correctly, the workflow will build all versions on every push or pull request, and upload progress on pushes the `main` branch.

Binary file not shown.

After

Width:  |  Height:  |  Size: 44 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 56 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 12 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 11 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 20 KiB