Added documentation for Building GCC and Useful Aliases and Scripts.

aliases-and-scripts.rst

@@ -0,0 +1,255 @@
+Aliases and Scripts
+===================
+
+If you are going to be doing a lot of development on GCC, it can become a huge
+hassle to type, and remember, the same complicated commands over and over again.
+These aliases and scripts are designed to save you a lot of time, and headaches.
+
+Aliases
+-------
+
+Aliases are like custom commands that act as "shortcuts". These "shortcuts" are
+used to represent a command, or set of commands. If you use Ubuntu, chances are
+you are already using some aliases, as Ubuntu defaultly defines a few. If you
+would like to see a list of aliases you might have, type ``alias`` into your 
+terminal.
+
+Aliases live inside the bashrc (typically at ``~/.bashrc``), so will have to 
+edit the file to gain our nice custom shortcuts! 
+I will be going over each alias and describing what it does.
+
+.. note::
+
+   I will assume that your source and build
+   directory paths are as follows: ``~/src/gcc/``, and ``~/bld/trunk/``
+
+
+.. code-block:: bash
+
+   alias gt='cd ~/src/gcc/gcc' # source files
+   alias gtls='cd ~/src/gcc/libstdc++-v3' # C++ standard
+   alias gtt='cd ~/src/gcc/gcc/testsuite/' # testsuite
+   alias gtu='cd ~/svn/trunk/; svn up' # svn directory for commiting
+   alias gb='cd ~/bld/trunk' # build directory
+   alias gbg='cd ~/bld/trunk/gcc' # where the compiler lives
+
+These are all pretty straight forward. They are all shortened "cd" style
+commands.
+
+* ``gt`` will bring you to where most of the source files for GCC's 
+  front end is.
+* ``gtls`` brings you to where the GNU Standard C++ Library V3
+  lives.
+* ``gtt`` brings you to the testsuite.
+* ``gtu`` is a little more interesting. Once you have write access to GCC you 
+  will make a directory for the svn repository. That is where you would commit 
+  your patches. So what this alias does is, it cds into the directory,
+  updates it.
+* ``gb`` brings you to the build directory.
+* ``gbg`` brings you to where all the object files live. More importantly, it
+  brings you to where you where the compiler (``cc1``, and ``cc1plus``) lives.
+
+.. code-block:: bash
+
+   alias mg='make CXXFLAGS=-g3'
+   export MAKEFLAGS='-j4'
+
+This is just to make the building process go faster. It saves a lot of time.
+
+.. code-block:: bash
+
+   alias gdba='gdb -q --args'
+
+``gdba`` is my quick way of running the debugger. You will be debugging the
+compiler a lot, so, it saves a lot of time to not have to write that 
+command every singe time. ``-q`` is so it ruins quietly. GDB would usually
+print annoying messages everytime you run it, having ``q`` enabled, turns that
+off. ``--args`` is what lets you debug inside of the compiler. With that, you
+can now make breakpoints and step through the compiler as you would a normal
+program.
+
+.. code-block:: bash
+
+   dgxx ()
+   {
+       ( cd ~/bld/trunk/gcc;
+       GXX_TESTSUITE_STDS=98,11,14,17,2a make check-c++ ${1:+RUNTESTFLAGS="$*"} )
+   }
+
+   dg ()
+   {
+        ( cd ~/bld/trunk/gcc;
+	make check-c ${1:+RUNTESTFLAGS="$*"} )
+   }
+
+These two are for running tests. ``dgxx`` is used for C++ tests and 
+``dg`` is used for C tests. To run these you can either run them alone to
+run all tests, or you can run it with an extra argument to run one specific
+test. For example:
+
+.. code-block:: console
+
+   dgxx dg.exp="name-of-test"
+
+.. code-block:: bash
+
+   gcc_configure ()
+   {
+     ~/src/gcc/configure
+   }
+
+This last one is used to configure gcc inside of a build directory. This can be
+heavily customized as everyone will have different configuration options. For
+example, mine looks like this:
+
+.. code-block:: bash
+
+   gcc_configure ()
+   {
+     ~/src/gcc/configure --enable-languages=c,c++ 
+     --enable-checking=yes -with-system-zlib --disable-bootstrap 
+     --disable-libvtv --disable-libcilkrts --disable-libitm --disable-libgomp 
+     --disable-libcc1 --disable-libstdcxx-pch --disable-libssp --disable-isl 
+     --disable-libmpx --disable-libsanitizer --disable-libquadmath 
+     --disable-libatomic
+   }
+
+You can find the configuration options `here`_.
+
+.. _here: https://gcc.gnu.org/install/configure.html
+
+.. code-block:: console
+
+   alias 'cc1'='./cc1 -quiet' # lazy C compile
+   alias 'cc1p'='./cc1plus -quiet' # lazy C++ compile
+
+These last two are more for convience than anything. I hated having to type out
+the command everytime I compiled something (which was a lot), so I decided to
+shorten it.
+
+Scripts
+-------
+
+The first thing you are going to want to do is make a bin directory in your
+home directory (``~/bin/``). This is so your $PATH can catch it so you wont have
+to type out each scripts path everytime you run one. The way all of these work
+is by typing the scripts name and a string you want to search.
+
+.. note::
+
+   Once again, I am going to assume your source and build directorys' paths are
+   as follows: ``~/src/gcc/``, and ``~/bld/trunk``
+
+Searching scripts
+^^^^^^^^^^^^^^^^^
+
+**gcf**
+
+.. code-block:: bash
+
+   #!/bin/bash
+   cd ~/src/gcc/gcc
+   grep -nE --color=tty "$@" c/*.{c,h} c-family/*.{c,cc,h,def,opt}
+
+This one searches inside of the C/C++ front end files.
+
+**gcx**
+
+.. code-block:: bash
+
+   #!/bin/bash
+   cd ~/src/gcc/gcc
+   grep -nE --color=tty "$@" cp/*.{c,cc,h,def} c-family/*.{c,cc,h,def,opt}
+
+This one searches inside the gcc/cp/ and gcc/c-family/ directories.
+
+**gf**
+
+.. code-block:: bash
+
+   #!/bin/bash
+   cd ~/src/gcc/gcc
+   grep -nE --color=tty "^""$@" *.{c,h,def,opt,pd} doc/*.texi* c/*.{c,h} c-family/*.{c,h,def,opt} cp/*.{c,h,def} ginclude/*.h config/i386/*.{c,h,def,opt}
+
+This one searches for function declarations.
+
+**gg**
+
+.. code-block:: bash
+
+   #!/bin/bash
+   cd ~/src/gcc/gcc
+   grep -nE --color=tty "$@" *.{c,cc,h,def,opt,pd} doc/*.texi* c/*.{c,h} c-family/*.{c,cc,h,def,opt} cp/*.{c,h,def,cc} ginclude/*.h config/i386/*.{c,h,def,opt}
+   #grep -nE --color=tty $@ *.{c,h,def,opt} doc/*.texi* c/*.{c,h} {c-family,java,fortran}/*.{c,h,def,opt} {cp,objc,objc}/*.{c,h,def} lto/*.{c,h,opt} go/*.{c,cc,h} ada/*.{adb,ads} ada/gcc-interface/*.{c,h,def,opt} config/*.{c,h,def,opt} config/*/*.{c,h,md,def,opt} common/config/*/*.c
+   #grep -nEr --exclude-dir=".svn" --color=tty $@ ../libgcc/*
+   #grep -nEr --exclude-dir=".svn" --color=tty $@ ../libcpp/*
+
+This one searches the entire compiler.
+
+**ggh**
+
+.. code-block:: bash
+
+   #!/bin/bash
+   cd ~/src/gcc/gcc
+   grep -nE --color=tty "$@" *.{h,def,opt} doc/*.texi* c/*.h c-family/*.{h,def,opt} cp/*.{h,def} ginclude/*.h
+
+Compiling scripts
+^^^^^^^^^^^^^^^^^
+
+These are really only useful if you have set up older versions of GCC on your
+system. The paths I use within the scripts assume you have set up the older
+versions in the way of step 4 in "How to Build GCC from Source".
+
+**xg++-7**
+
+.. code-block:: bash
+
+   #!/bin/sh
+   ~/bld/gcc7/gcc/xg++ -B ~/bld/gcc7/gcc/ -B ~/bld/gcc7/x86_64-pc-linux-gnu/libstdc++-v3/bld/.libs/ `~/bld/gcc7/x86_64-pc-linux-gnu/libstdc++-v3/scripts/testsuite_flags --build-includes` -B ~/bld/gcc7/x86_64-pc-linux-gnu/libsanitizer/ubsan/.libs/ -Wl,-rpath=~/bld/gcc7/x86_64-pc-linux-gnu/libsanitizer/ubsan/.libs/ "$@"
+
+**xg++-8**
+
+.. code-block:: bash
+
+   #!/bin/sh
+   ~/bld/gcc8/gcc/xg++ -B ~/bld/gcc8/gcc/ -B ~/bld/gcc8/x86_64-pc-linux-gnu/libstdc++-v3/bld/.libs/ `~/bld/gcc8/x86_64-pc-linux-gnu/libstdc++-v3/scripts/testsuite_flags --build-includes` -B ~/bld/gcc8/x86_64-pc-linux-gnu/libsanitizer/ubsan/.libs/ -Wl,-rpath=/home/mbelivea/bld/gcc8/x86_64-pc-linux-gnu/libsanitizer/ubsan/.libs/ "$@"
+
+**xg++-9**
+
+.. code-block:: bash
+
+   #!/bin/sh
+   ~/bld/gcc9/gcc/xg++ -B ~/bld/gcc9/gcc/ -B ~/bld/gcc9/x86_64-pc-linux-gnu/libstdc++-v3/bld/.libs/ `~/bld/gcc9/x86_64-pc-linux-gnu/libstdc++-v3/scripts/testsuite_flags --build-includes` -B ~/bld/gcc9/x86_64-pc-linux-gnu/libsanitizer/ubsan/.libs/ -Wl,-rpath=/home/mbelivea/bld/gcc9/x86_64-pc-linux-gnu/libsanitizer/ubsan/.libs/ "$@"
+
+Other Scripts
+^^^^^^^^^^^^^
+
+This last script is one of the most used scripts I have used while developing
+for GCC. This patch generates a script by taking the git diff, and checking its
+contents with a style guide that is built into ``~/src/gcc/contrib``.
+
+**do_patch**
+
+.. code-block:: bash
+
+   #!/bin/sh
+   P=$1.patch
+   if test -e $P; then
+   echo "Patch already exists, bailing out."
+   exit 1
+   fi
+   git diff  > $P
+   ~/src/gcc/contrib/mklog /tmp/$P | cat - /tmp/$P > $P
+   pr=`echo $P | sed 's/pr\([0-9]\+\).*/\1/'`
+   if test -n "$pr"; then
+     sed -i "3i\\\tPR c++/$pr" $P
+   fi
+   sed -i "s/\t\*\ gcc\//\t\*\ /" $P
+   sed -i '1i Bootstrapped/regtested on x86_64-linux, ok for trunk?\n' $P
+   echo -e "Wrote $P\nDon't forget to remove c/, cp/, c-family/, testsuite/ prefixes."
+   ~/src/gcc/contrib/check_GNU_style.sh $P
+   $EDITOR $P
+
+The way to run this script is as follows: ``do_patch pr55555555`` then it will
+generate a patch called ``pr55555555.patch``.

how-to-build-gcc-from-source.rst

@@ -0,0 +1,133 @@
+How to Build GCC from Source
+============================
+
+Step 1: Install Dependancies
+----------------------------
+
+.. code-block:: console
+
+   sudo dnf install gcc-c++ \
+	libmpc-devel \
+	mpfr-devel \
+	gmp-devel \
+	bison \
+	flex \
+	dejagnu \
+	zlib-devel \
+	glibc-devel.i686
+
+Step 2: Set up Directories
+--------------------------
+
+Development for GCC is split into two different directories: A source, and 
+a build. The source directory is where all the source files will go. This is
+where you will clone the git repo, and where you will be changing files for 
+development. The build directory is where you are going to configure and
+build gcc. This directory contains all of the object files. After every
+edit to the source directory, you will have to recompile the object files.
+
+.. code-block:: console
+
+   mkdir -p ~/bld/trunk && mkdir ~/src/
+
+Step 2a: Clone Git Repo into Source Directory
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Make a build and source directory. Here I will make it in my home directory;
+however, you can make the directories where you choose.
+
+.. code-block:: console
+
+   cd ~/src/ && git clone git://gcc.gnu.org/git/gcc.git
+
+Then you will want to checkout branch ``trunk`` or ``master``
+
+.. code-block:: console
+
+   git checkout master
+
+.. note::
+
+   If your git username and email are not the same as the one you use to
+   contribute to GCC (i.e. work email), it's helpful to set it to the correct
+   information inside the git directory.
+
+   .. code-block:: console
+
+      git config user.name "User Name"
+      git config user.email "[email protected]"
+
+   This is useful for when you are generating patches later, because the script
+   grabs your git information. This means you will not have to change it every
+   time you make a new patch.
+
+Step 2b:  Set up Build Directory Configuration
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+GCC has a script called ``configure`` inside the source directory at
+``~/gcc/configure``. Calling by itself will enable every option by default.
+If you want a different configuration you will have to use option flags to
+change the configuration settings. For example, I mostly work on front end C and
+C++ stuff, so my configuration would look like this:
+
+.. code-block:: console
+
+    ~/src/gcc/configure --enable-languages=c,c++ \
+    --enable-checking=yes -with-system-zlib --disable-bootstrap \
+    --disable-libvtv --disable-libcilkrts --disable-libitm --disable-libgomp \
+    --disable-libcc1 --disable-libstdcxx-pch --disable-libssp --disable-isl \
+    --disable-libmpx --disable-libsanitizer --disable-libquadmath \
+    --disable-libatomic
+
+You can find the configuration options `here`_.
+
+.. _here: https://gcc.gnu.org/install/configure.html
+
+Next you will have to make the directory:
+
+.. code-block:: console
+
+   make CXXFLAGS=-g3
+
+The CXXFLAGS option will make the process go much faster.
+
+.. note::
+
+   If you make a change to the source directory, you wont have to build the
+   entirety of GCC again! For example, if you make a change to the front end
+   (``~/src/gcc/gcc``), all you have to do is run the command above in
+   ``~/bld/trunk/gcc``. This will save you a load of time!
+
+Step 3: Compile a test program with the newly built GCC to confirm it works
+---------------------------------------------------------------------------
+
+Take this test code ``hello.c``:
+
+.. literalinclude:: hello.c
+   :language: c
+
+From inside the build directory ``~/bld/trunk/gcc``, we will run the command:
+
+.. code-block:: console
+
+   ./cc1plus -quiet -Iinclude hello.c
+
+The ``-quiet`` option makes it so the compiler doesn't print out annoying
+messages to console when compiling. The ``-Iinclude`` option lets you
+compile code that contains ``#include``'s when using
+either ``cc1`` or ``cc1plus``.
+
+Step 4 (Optional): Set up Older Versions of GCC
+-----------------------------------------------
+
+Many times you will find a bug that worked in one version and doesn't work in
+another, sometimes you will accept a bug report that is in GCC 9 or GCC 8. In
+these cases, it's handy to already have a working source and build directory for
+this version. What I like to do is have working directories for ``trunk``,
+``gcc-9``, ``gcc-8``, and ``gcc-7``.
+
+To set these directories up, all you have to do is copy your working ``trunk``
+source directory into a seperate one and check out ``gcc-7/8/9-branch``
+inside those directories.  Then follow the steps above to configure the build
+directory, but changing the path of the script to fit the correct version. For
+example: ``~/src/gcc9/configure`` instead of ``~/src/gcc/configure``.

index.rst

@@ -38,6 +38,8 @@ Contents:
    :maxdepth: 1
 
    gotchas-and-faq.rst
+   how-to-build-gcc-from-source.rst
+   aliases-and-scripts.rst
    debugging.rst
    working-with-the-testsuite.rst
    how-to-improve-the-location-of-a-diagnostic.rst