diff --git a/.github.example/workflows/build.yml b/.github.example/workflows/build.yml new file mode 100644 index 0000000..05edd55 --- /dev/null +++ b/.github.example/workflows/build.yml @@ -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 diff --git a/README.md b/README.md index 6967840..0ef4fb2 100644 --- a/README.md +++ b/README.md @@ -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 ----------------- diff --git a/docs/dependencies.md b/docs/dependencies.md index f6d1a30..62206a8 100644 --- a/docs/dependencies.md +++ b/docs/dependencies.md @@ -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). diff --git a/docs/getting_started.md b/docs/getting_started.md index c3c3628..27f9612 100644 --- a/docs/getting_started.md +++ b/docs/getting_started.md @@ -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. diff --git a/docs/github_actions.md b/docs/github_actions.md new file mode 100644 index 0000000..3eb840e --- /dev/null +++ b/docs/github_actions.md @@ -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. diff --git a/docs/images/github_actions_secrets.png b/docs/images/github_actions_secrets.png new file mode 100644 index 0000000..63ae372 Binary files /dev/null and b/docs/images/github_actions_secrets.png differ diff --git a/docs/images/github_build_repo_create.png b/docs/images/github_build_repo_create.png new file mode 100644 index 0000000..07171fc Binary files /dev/null and b/docs/images/github_build_repo_create.png differ diff --git a/docs/images/github_build_repo_packages.png b/docs/images/github_build_repo_packages.png new file mode 100644 index 0000000..e0c943b Binary files /dev/null and b/docs/images/github_build_repo_packages.png differ diff --git a/docs/images/github_package_settings.png b/docs/images/github_package_settings.png new file mode 100644 index 0000000..8b6e6a6 Binary files /dev/null and b/docs/images/github_package_settings.png differ diff --git a/docs/images/github_package_settings_access.png b/docs/images/github_package_settings_access.png new file mode 100644 index 0000000..704be61 Binary files /dev/null and b/docs/images/github_package_settings_access.png differ