Notes for Steam Runtime maintainers
-----------------------------------

### Useful git remotes

    git remote add salsa https://salsa.debian.org/toolchain-team/gcc.git

Note that unlike most of our packages, this one does not have upstream
source code in the git repository. Debian's gcc packages have an unusual
tarball-in-tarball structure that makes this not a useful thing to do.

### To do a clean/complete/pedantically correct build in a separate directory

* Download the matching `gcc-14_*.orig.tar.*` from Debian
    * Do not get it from Ubuntu - it's different there!
    * It should contain `gcc-*-dfsg.tar.xz` and other tarballs

* Put it in `..` (or in the directory you will pass to
    `deb-build-snapshot --orig-dir` or `gbp buildpackage --git-tarball-dir`
    if different)

* Build with `deb-build-snapshot --overlay` or `gbp buildpackage --git-overlay`

### To do an incremental build for development

* Download `gcc-14_*.orig.tar.*` from Debian, as above

* Unpack it into the current directory, so that you have
    `./gcc-*-dfsg.tar.xz` and other tarballs. To start from a "clean slate"
    you might find these commands useful:

        git clean -fxd
        tar --strip-components=1 -xvf ../gcc-14_14.2.0.orig.tar.gz

* Run a shell in a suitable chroot or container

* `sudo apt-get build-dep .`

* `sudo apt-get install ccache devscripts`
  (recommended; or you can use `dpkg-buildpackage` instead of `debuild`)

* Recommended: add `DEBUILD_PREPEND_PATH=/usr/lib/ccache` and
  `DEBUILD_PRESERVE_ENVVARS=CCACHE_DIR` to `~/.devscripts`

* To do a complete build: `debuild -us -uc -b`
    * You can put `DEBUILD_DPKG_BUILDPACKAGE_OPTS="-us -uc"` in
      `~/.devscripts` to avoid needing to specify them every time

* To do an incremental build, without `make clean`: `debuild -us -uc -b -nc`

* On SteamRT 2 'soldier' or up, the build automatically uses one parallel
  process per CPU. Override with `debuild ... -J4` or similar.
  On SteamRT 1 'scout', the default was a serial build, and the `-J`
  option didn't exist, so use `debuild ... -j4` or similar.

* The actual source code is in `src/`. Patches are applied during
  an early stage of the build. For ad-hoc testing, you can do
  something like:

    * `quilt new try-something.diff`
    * `quilt add src/gcc/main.c`
    * `vi src/gcc/main.c`
    * `quilt refresh` (this writes out `debian/patches/try-something.diff`)

  (Remember all the mistakes you made when you first learned git?
  quilt is like that, all the time. If in doubt, keep a separate copy.)

* quilt edits `debian/patches/series`, but that's actually a generated file
  (yes, this is really weird), so to get your patch actually included in the
  packaging so it will get applied during a clean build, you have to add
  it to `debian_patches` in `debian/rules.patch`. Just above the rules
  for `series_stamp` is a good place.

### To update from upstream git

* Also have a separate gcc git checkout, or a git remote for gcc upstream

* `quilt pop -a`

* Edit the first line of `debian/patches/git-updates.diff` to indicate
  the new date and commit

* Replace the second SHA1 in the long "git diff" command with the new
  commit

* Remove the actual diff

* Replace the diff with the result of running the long "git diff" command
  in your gcc git checkout

* `make -f debian/rules update-patches` and fix any patches that no
  longer apply cleanly

### To regenerate `debian/control` from `debian/control.m4`:

* Download `gcc-14_*.orig.tar.*` from Debian, as above

* Unpack it into the current directory, as above

* Be on a machine where autoconf2.69 is available

* Then run:

        make -f debian/rules steamrt-regenerate-control

Patches applied to the Debian version of GCC
--------------------------------------------

Debian specific patches can be found in the debian/patches directory.
Quilt is used as the patch system.  See /usr/share/doc/quilt/README.source
for details about quilt.

Patches are applied by calling `debian/rules patch'.  The `series'
file is constructed on the fly based on the files found in the to
debian/rules.patch "debian_patches" variable, configure scripts are
regenerated in the `patch' target. The gcc source is unpacked under
src/ this needs to be reflected in the patch header.

Running a single dejagnu test
-----------------------------

 - Find out the test suite containing the test, and the associated
   target (e.g. check-gcc in <build>/gcc, or check in <buildlibdir>/<lib>.

 - Find out the dejagnu test suite, e.g. guality.exp
   - If you have a log of the original testsuite run, search back for the
     .exp file before the fail.
   - Find the directory with the test and then the .exp in the nearest
     enclosing directory.

 - Set RUNTESTFLAGS to the testsuite name and the test name to run, e.g
     RUNTESTFLAGS="guality.exp=pr54519-2.c" make -e check-gcc
   The test name is just the base name, but might be the path relative
   from gcc/testsuite for C++ tests.
