====== Building GCC ======

GCC is a large codebase that has developed over a period of several decades, works on many different architectures, has had many contributors, and is itself written in several different languages.

Building GCC is similar to building many other large codebases. Since the people working on this project are themselves experts in compilers and build tools, the software has a high-quality build system.

===== Step 0: Decide Where to Build =====

You can use the [[SPO600 Servers]] or your own systems.

**CRITICAL:** The host aarch64-001.spo600.cdot.systems does __not__ have enough RAM to build GCC. Please use aarch64-002 or another host for this purpose. Attempting to build GCC on aarch64-001 will cause a system crash due to memory exhaustion (and your prof will know who did it!).

===== Step 1: Obtain the Source Code =====

The GCC source is available from four places:
  - As a [[https://gcc.gnu.org/git.html|git repository on gcc.gnu.org]]
  - As a [[https://gcc.gnu.org/snapshots.html|weekly snapshot of the current development version]]
  - As official [[https://gcc.gnu.org/releases.html|releases]]
  - Via a read-only [[https://github.com/gcc-mirror/gcc|mirror of the gcc.gnu.org repository on GitHub]]

Of these sources, I recommend using #1 or possibly #4 for development work. Clone the repository to your local machine as usual using standard ''git'' commands.

===== Step 2: Configure Your Build =====

The GCC source code may be built inside the source directories, but this is **not recommended and strongly discouraged** by the GCC developers.

Instead, you should create a separate build directory. From this build directory, you should invoke the configure script which is in the root directory of the source repository.

You can pass parameters to the configure script. The most important is to configure the "prefix" directory for the installation location, which may be done with the ''--prefix'' option.

For example, if the source is in ''~/git/gcc'', you could do something like this:
<code>
mkdir ~/gcc-build-001
cd ~/gcc-build-001
~/git/gcc/configure --prefix=$HOME/gcc-test-001</code>

If there are any required build dependencies (libraries, headers, or build tools) which are not present on the system, you will be notified by the configure script. Install the required build dependencies and then re-execute the configure script.

===== Step 3: Perform the Build =====

If you are unfamiliar with the ''make'' utility, see the [[Make and Makefiles]] page.

Once you have configured the build, you can use ''make'' to perform the build. By default, make will only start one job (subprocess, such as gcc) at a time. You can use the ''-j'' option to specify the maximum number of jobs which make will execute simultaneously; the value provided to ''-j'' should be in the range of (number of cores + 1) to (number of cores * 2 + 1) -- use the higher end of this range for machines with hardware multi-thread support (aka hyperthreading) or slow disk systems, and the lower end of this range for machines without multi-thread support.

Before building, consider that the build may take anywhere from 20 minutes to several hours depending on the build options, speed of the build computer, and what else is being done on the computer (e.g., multiple builds by several users). It is strongly recommended that you use the [[screen]] utility (or similiar tool) to permit disconnection and reconnection if needed.

It is also recommended that you record the time taken for the build to complete using the shell built-in ''time'' command, and that you redirect the stdin and stdout to a log file as well as the screen using the ''tee'' program.

Putting these recommendations together, you could build on a 16-core system with a command such as this:

<code>time make -j 24 |& tee build.log</code>

The ''|&'' symbol concatenates the stdout and stderr and feeds it to the ''tee'' command, which writes the data to the given file as well as stdout (the terminal).

===== Step 4: Install the Build =====

**Critical!** Never install a test or development build as the __root__ user (using ''sudo'' or ''su''), or it may overwrite the system installation of the same software (in this case, replacing the system's gcc with the experimental one that you've built). Instead, always install into a personal directory using the ''--prefix'' option to configure and the ''make install'' command executed as a regular user.

To install the software into the directory that you configured in step 2, run ''make install''.

===== Step 5: Test the Build =====

You can test the build using ''make check'' in the build directory. You can also use the installed build of the compiler by setting your path to include the ''bin'' directory within the installation directory as the first directory in your PATH:

<code>PATH=$HOME/gcc-test-001:$PATH</code>

===== Cleaning Up =====

To clean up a build directory, you can simply ... delete it! THe source code will be in a separate directory and will remain unchanged.

Likewise, to clean up an installation directory that contains only a single build, you can simply delete that directory.

===== Things to Watch For =====

  * Be aware of who else is using the build computer and what they're doing on it. Use command such as ''w'' or ''who'' as well as  ''top'' or ''btop''.
  * Be aware of available disk space (''df -h .'')
  * Keep an eye on currently-available memory (''free'' -- watch the "Available" memory, not the "Free" memory)