sh-elf-gcc/README.md

# SuperH toolchain: `sh-elf-gcc`

This repository provides scripts to automatically compile and install an SH3/SH4-compatible [GCC cross-compiler](https://gcc.gnu.org/). GCC is a collection of compilers most commonly used for C/C++.

This repo currently builds GCC version 13.1.0 with additional patches from [this fork](https://github.com/antoyo/gcc) by antoyo, who works on the GCC backend for rustc, to allow rustc_codedgen_gcc to work. GCC and any patches are licenced under the GNU General Public License version 3 with a runtime exception; see the [GCC source code](https://ftp.gnu.org/gnu/gcc/gcc-13.1.0/) for more details.

The following three methods can be used to install the compiler with different levels of automation.

Note that this repository should usually be built twice: first to build the compiler, and then after the libc is installed to build the C++ library.

## Method 1: Using GiteaPC

The most common way to install this compiler is for the fxSDK, and it can be automated with [GiteaPC](/Lephenixnoir/GiteaPC):

```bash
% giteapc install Lephenixnoir/sh-elf-gcc
# After you install the libc, do it again
```

This installs GCC (and binutils if missing) in the fxSDK's SuperH system root. Note that at first it will *not* install the C++ standard library libstdc++, because it requires the C standard library which is not available at this stage. After you install [fxlibc](/Vhex-Kernel-Core/fxlibc/) you should run GiteaPC's install command again, and this time the scripts will build libstdc++. The GiteaPC tutorial has more detailed instructions about this two-stage process.

A `:any` configuration is provided in case you already have another version of GCC installed in the fxSDK sysroot and want to keep using it (ie. skip a version upgrade). This will mark this repository as installed, so other repositories depending on it can build, without actually compiling binutils.

```bash
% giteapc install Lephenixnoir/sh-elf-gcc:any
```

A `:clean` configuration is also provided if you want to clean up the source and build files automatically after the second pass. This frees up some disk space.

```bash
% giteapc install Lephenixnoir/sh-elf-gcc:clean
```

## Method 2: Manually running the scripts

Make sure to previously install:

* [fxSDK](https://gitea.planet-casio.com/Lephenixnoir/fxsdk) ≥ 2.8.1 (provides the sysroot)
* [binutils for SuperH](https://gitea.planet-casio.com/Lephenixnoir/sh-elf-binutils)
* Most of the [requirements for GCC](https://gcc.gnu.org/install/prerequisites.html) are checked in the binutils `configure.sh`

Follow the same procedure as for binutils; preferably use the same `PREFIX`.

```bash
% make -f giteapc.make configure build install PREFIX="$HOME/.local"
```

## Method 3: Fully manually

First here is the [guide for installing GCC](https://gcc.gnu.org/install/index.html) and here is [the one for libstdc++](https://gcc.gnu.org/onlinedocs/libstdc++/manual/setup.html).

Get your GCC version of choice from [gcc.gnu.org](https://ftp.gnu.org/gnu/gcc/) and extract the archive.

**Warning:** GCC 12.1 to 12.3 for SuperH have a [critical bug](https://gcc.gnu.org/bugzilla/show_bug.cgi?id=106609) which causes them to compile add-ins incorrectly. If you install GCC manually, use either GCC 11.1 (or earlier) or GCC 13 (or later).

If using GCC 11.1 (or possibly earlier) for the SuperH compiler, we need to patch the libstdc++ configure script because it tries to run tests that are too advanced for our setup and not actually intended to run on cross-compilers. GCC 12 has this patch upstream.

```bash
% patch -u -N -p0 < patches/gcc-11.1.0-libstdc++-v3-skip-dlopen.patch
```

If you want Rust support you will also need to apply some patches to add some needed functionality to libgccjit, taken from the fork mentioned above. This patch has been tested to work when applied to GCC 13.1.0. Note that arguments to this command are slightly different that the last one and it must be applied within the source directory.

```bash
% cd gcc-$VERSION
% patch -t -u -N -p1 < ../patches/gcc-13.1.0-rustc-codegen-gcc.patch
% cd ..
```

Also download prerequisites if you don't have them system-wide.

```bash
% cd gcc-$VERSION
% ./contrib/download_prerequisites
% cd ..
```

Now choose a prefix for install. If you're installing for the fxSDK, you must use `$(fxsdk path sysroot)`, otherwise anything that is isolated from the native OS is fine.

```bash
% SYSROOT="$(fxsdk path sysroot)"
```

Because the binutils is called `sh-elf-` and not `sh3eb-elf-`, GCC won't find it on PATH alone. Symlink them to `$SYSROOT/sh3eb-elf/bin`:

```bash
% mkdir -p "$SYSROOT/sh3eb-elf/bin"
% for TOOL in as ld ar ranlib; do \
    ln -sf $(command -v sh-elf-$TOOL) "$SYSROOT/sh3eb-elf/bin/$TOOL" \
  done
```

You can then configure and build GCC.

```bash
% mkdir build && cd build
% ../gcc-$VERSION/configure                 \
    --prefix="$SYSROOT"                     \
    --target="sh3eb-elf"                    \
    --with-multilib-list="m3,m4-nofpu"      \
    --enable-languages="c,c++,jit"          \
    --enable-host-shared                    \
    --without-headers                       \
    --program-prefix="sh-elf-"              \
    --enable-libssp                         \
    --enable-lto                            \
    --enable-clocale="generic"              \
    --enable-libstdcxx-allocator            \
    --disable-threads                       \
    --disable-libstdcxx-verbose             \
    --enable-cxx-flags="-fno-exceptions"
```

* `--enable-languages="c,c++,jit"`: rustc_codegen_gcc uses libgccjit. If you don't need Rust support you can remove `jit`.
* `--enable-host-shared`: Builds as a shared library for rustc_codegen_gcc. Again, if you don't need Rust support you can remove this.
* `--without-headers`: Also indicates a cross-compiler in many scenarios.
* `--enable-clocale="generic"`: Makes it easier to build the libstdc++.
* `--enable-libstdcxx-allocator`: Same; `=malloc` might be an option too.
* `--disable-threads`: Obvious.
* `--disable-libstdcxx-verbose`: For space; we don't always have stderr anyway.
* `--enable-cxx-flags="-fno-exceptions"`: Unless you have a kernel with exception support I guess.

Then build and install gcc.

```bash
% make -j$(nproc) all-gcc all-target-libgcc
% make install-strip-gcc install-strip-target-libgcc
```

The next step is to install the libc. The standard fxSDK setup is to install [OpenLibm](https://gitea.planet-casio.com/Lephenixnoir/OpenLibm) and [fxlibc](https://gitea.planet-casio.com/Vhex-Kernel-Core/fxlibc/). Feel free to experiment. Make sure the includes and libraries end up in `$SYSROOT/sh3eb-elf/{bin,include}` since this is where GCC looks in hosted-like situations.

Once the libc is available we can come back to GCC's build folder and actually compile libstdc++.

```bash
# Install the libc, then:
% make -j$(nproc) all-target-libstdc++-v3
% make install-strip-target-libstdc++-v3
```

You can then clean up the source archive, source files, and build folder if needed. Link add-ins with `-lm -lstdc++ -lc -lgcc` in this order for the best results.