branch unity: Merge preview into trunk with 24 custom commits

.gitattributes

@@ -2,3 +2,4 @@
 # These are all bash scripts and should use lf
 *.sh text eol=lf
 tools/ipl3.h linguist-generated=true
+libdragon.version export-subst

.github/actions/path-diff/action.yml

@@ -19,7 +19,7 @@ runs:
   using: "composite"
   steps:
     - name: Checkout
-      uses: actions/checkout@v6
+      uses: actions/checkout@v7
       with:
         fetch-depth: 0
 

.github/workflows/build-documentation.yml

@@ -14,7 +14,7 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Checkout
-        uses: actions/checkout@v6
+        uses: actions/checkout@v7
         with:
           fetch-depth: 1 # Using a shallow checkout. Change to `0` if a full fetch is required.
 
@@ -24,7 +24,7 @@ jobs:
           echo "default_ref=${{ format('refs/heads/{0}', github.event.repository.default_branch) }}" >> $GITHUB_OUTPUT
 
       - name: Run Doxygen
-        uses: mattnotmitt/doxygen-action@v1.9
+        uses: mattnotmitt/doxygen-action@v1.12
         with:
           doxyfile-path: 'doxygen-public.conf'
 

.github/workflows/build-tool-windows.yml

@@ -22,7 +22,7 @@ jobs:
             unzip
           update: true
 
-      - uses: actions/checkout@v6
+      - uses: actions/checkout@v7
         with:
           fetch-depth: 1 # Using a shallow checkout. Change to `0` if a full fetch is required.
 

.github/workflows/build-toolchain-library-and-roms.yml

@@ -14,7 +14,7 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Checkout
-        uses: actions/checkout@v6
+        uses: actions/checkout@v7
         with:
           fetch-depth: 0 # Using a full fetch so that the diff action can run.
 
@@ -101,16 +101,39 @@ jobs:
           cache-from: type=gha
           cache-to: type=gha,mode=max
 
+      # Cache the videoplayer sample movie so CI does not re-download it from
+      # archive.org on every run. The Makefile skips wget/curl if the file exists,
+      # and the Docker build binds the workspace, so restoring here is enough.
+      - name: Cache videoplayer sample movie
+        uses: actions/cache@v6
+        with:
+          path: examples/videoplayer/caminandes.ogv
+          key: videoplayer-caminandes-ogv-v1
+
       # As we have a tagged image now, we can use that to run build.sh if it is
       # built in the previous step. o/w it will be downloaded from the registry.
       # Then verify everything is building properly
-      - name: Build libdragon
+      - name: Run libdragon docker container
         run: |
-          docker run \
+          docker run -d --name libdragon \
           --mount type=bind,source=$(pwd),target=/libdragon \
           --workdir=/libdragon \
           ghcr.io/${{ steps.vars.outputs.repository_name }}:latest \
-          ./build.sh
+          sleep infinity
+
+      - name: Build libdragon
+        run: |
+          docker container exec --env=LIBDRAGON_PREVIEW=0 libdragon ./build.sh --no-examples
+
+      # This also builds the test ROMs, and checks that the preview APIs are
+      # locked for a stable project and unlocked for a preview one.
+      - name: Run tests
+        run: |
+          docker container exec --env=LIBDRAGON_PREVIEW=0 libdragon make test
+
+      - name: Build examples
+        run: |
+          docker container exec --env=LIBDRAGON_PREVIEW=0 libdragon make examples --keep-going
 
       - name: "Upload built ROMs to artifacts"
         uses: actions/upload-artifact@v7
@@ -120,6 +143,10 @@ jobs:
             ${{ github.workspace }}/examples/**/*.z64
             ${{ github.workspace }}/tests/*.z64
 
+      - name: Stop libdragon docker container
+        if: always()
+        run: docker rm -f libdragon
+
       # Finally push the verified image to the registry with the latest tag if
       # we are on the default branch. At this point, we know that libdragon can
       # build with this freshly built image.

.github/workflows/build-toolchain-matrix.yml

@@ -51,7 +51,6 @@ jobs:
           sudo apt-get install libmpc-dev
           sudo apt-get install squashfs-tools
           # If there are other dependencies, we should add them here and make sure the documentation is updated!
-        continue-on-error: true
 
       - name: Install x-compile system build dependencies
         if: ${{ matrix.target-platform == 'Windows-x86_64' }}
@@ -66,24 +65,22 @@ jobs:
         with:
           bundler-cache: true
           ruby-version: '3.3'
-        continue-on-error: true
 
       - name: Install Package Creator
         if: ${{ matrix.target-platform == 'Linux-x86_64' || matrix.target-platform == 'Linux-aarch64' }}
         run: |
           echo installing jordansissel/fpm ruby package
           gem install fpm
           fpm --version
-        continue-on-error: true
 
       - name: Checkout Code
-        uses: actions/checkout@v6
+        uses: actions/checkout@v7
         with:
           fetch-depth: 1 # we only require the last check-in, unless we want to create a changelog.
 
       # Cache and restore dependencies instead of downloading them to increase build speed.
       # Expires after 7 days.
-      - uses: actions/cache@v5
+      - uses: actions/cache@v6
         id: cache
         with:
           path: |
@@ -120,7 +117,6 @@ jobs:
           ./build-gdb.sh
           echo "Removing un-necessary content"
           rm -rf ${N64_INST}/share/locale/*
-        continue-on-error: true
 
       # https://fpm.readthedocs.io/en/v1.15.0/getting-started.html
       # TODO: add --deb-changelog with versions (like we do in release)
@@ -167,7 +163,6 @@ jobs:
             --maintainer "$Package_Maintainer" \
             $Package_Source_Directory=$Package_Installation_Directory/ \
             $Package_Name-env.sh=/etc/profile.d/$Package_Name-env.sh
-        continue-on-error: true
         env:
           Package_Source_Directory: ${{ runner.temp }}/${{ env.Install_Directory }}/
           Package_Installation_Directory: /opt/${{ env.Install_Directory }}
@@ -188,7 +183,6 @@ jobs:
           name: gcc-toolchain-mips64-${{ matrix.target-platform }}
           path: |
             ${{ runner.temp }}/${{ env.Install_Directory }}
-        continue-on-error: true
 
       - name: Publish Linux-x86_64 Build Artifacts
         if: ${{ matrix.target-platform == 'Linux-x86_64' }}
@@ -198,7 +192,6 @@ jobs:
           path: |
             ./**/*.deb
             ./**/*.rpm
-        continue-on-error: true
 
       - name: Publish Linux-aarch64 Build Artifacts
         if: ${{ matrix.target-platform == 'Linux-aarch64' }}
@@ -208,14 +201,13 @@ jobs:
           path: |
             ./**/*.deb
             ./**/*.rpm
-        continue-on-error: true
 
   Publish-Toolchain:
     runs-on: ubuntu-latest
     needs: Build-Toolchain
 
     steps:
-      - uses: actions/checkout@v6
+      - uses: actions/checkout@v7
 
       - name: Download Windows-x86_64 artifact
         id: download-windows-x86_64-artifact

.gitignore

@@ -9,9 +9,12 @@ tools/dumpdfs/dumpdfs
 tools/mkdfs/mkdfs
 tools/mksprite/convtool
 tools/mksprite/mksprite
-tools/n64sym
+tools/cpaktool/cpaktool
+tools/mkmaterial/mkmaterial
+tools/n64metadata
 tools/n64tool
-tools/n64sym
+tools/n64sym/n64sym
+tools/n64sym/n64symdump
 tools/**/*.exe
 website/ref/
 

.tokeignore

@@ -0,0 +1,48 @@
+# Used by scripts/tokei-git.sh to ignore vendored files/folders
+# Vendored third-party libraries and tools
+
+# FatFS - File system library
+src/fatfs/
+
+# LibCart - Cartridge library (vendored)
+src/libcart/
+
+# Opus audio codec
+src/audio/opus/
+
+# LibXM - XM music format library
+src/audio/libxm/
+
+# libsamplerate - Audio resampling library
+tools/audioconv64/libsamplerate/
+tools/audioconv64/vadpcm/
+tools/audioconv64/dr_wav.h
+tools/audioconv64/dr_mp3.h
+
+# Compression libraries
+tools/common/shrinkler/
+tools/common/lz4/
+tools/common/incbin/
+tools/common/apultra/
+tools/common/json.hpp
+tools/common/mips_elf.h
+
+# STB libraries
+tools/common/stb_ds.h
+tools/common/lodepng.c
+tools/common/lodepng.h
+tools/common/mips_elf.h
+tools/common/subprocess.h
+
+# MKFont - vendored libraries
+tools/mkfont/freetype/
+tools/mkfont/pthash/
+tools/mkfont/plutosvg/
+tools/mkfont/rect_pack/
+
+# Exoquant - Image quantization library
+tools/mksprite/exoquant.*
+
+# PL_MPEG - MPEG decoder
+src/video/pl_mpeg/
+src/video/h264_decoder/