Add some docs about our compilers and patches done to them.

Change-Id: I60e0960499aec789ae6240eec949249adb2e35ad
Reviewed-on: https://review.haiku-os.org/c/haiku/+/5224
Reviewed-by: Fredrik Holmqvist <[email protected]>

docs/develop/build/compilers.rst

@@ -0,0 +1,31 @@
+Haiku compilers
+===============
+
+For legacy reason, Haiku uses gcc2 to build parts of the system. This only applies to the x86 32bit
+version of Haiku, which maintains binary compatibility with BeOS applications. The other ports of
+Haiku are not affected by this, and use a more modern version of GCC (version 10 at the time of the
+writing).
+
+The compilers are available in the separate "buildtools" repository. This repository contains gcc
+as well as the binutils (assembler, linker, etc). These are modified versions of the GNU tools, to
+handle the specifics of Haiku. The gcc2 compiler is still getting some maintenance updates and
+bugfixes. For the modern tools, the goal is to eventually re-integrate these changes into the
+upstream version.
+
+There is also work in progress to be able to build Haiku with llvm/clang as an alternative to gcc.
+
+Summary of changes made to gcc for Haiku support
+------------------------------------------------
+
+This is an incomplete list of the changes.
+
+- The -pthread option does nothing. In Haiku, pthreads are always enabled.
+- The -fPIE option does the same thing as -fPIC. In Haiku, executables are also loadable as shared
+  libraries because they can be loaded using load_add_on for use as replicants. Using the standard
+  gcc implementation of -fPIE would then break, because it generates code that can't be used in a
+  shared library. For this reason, -fPIE in Haiku instead does the same thing as -fPIC.
+- Header search path in Mac OS is case sensitive. Mac OS can handle both case sensitive and case
+  insensitive filesystems. Building Haiku requires a case sensitive filesystem, otherwise it's not
+  possible to tell apart headers like string.h and String.h. When compiling gcc for Mac OS, it
+  normally has code to force case insensitive comparison of header filenames, no matter what the
+  underlying filesystem offers. This is disabled in our version of gcc.

docs/develop/build/index.rst

@@ -0,0 +1,22 @@
+The build system
+================
+
+Building a complete operating system is a somewhat complex task. Simple tools like GNU make would
+result in a lot of problems and hard to maintain scripts if used this way.
+
+Haiku uses a slightly more elaborate tool called Jam. Jam was initially developed by Perforce, but
+they have now abandoned the product. As a result, Haiku currently maintains its own fork of Jam
+with several customizations.
+
+The core idea of Jam is to provide generic rules (for example "how to build an application from a set
+of source files") and then apply these rules several times. The Haiku build system defines a number
+of custom rules, allowing to build code both for Haiku and for the host operating system (to be run
+during the compiling process).
+
+The build system also offers various ways to configure and customize your Haiku disk image.
+
+
+.. toctree::
+
+   /build/compilers
+   /build/repositories/README

docs/develop/index.rst

@@ -38,7 +38,7 @@ Table of contents
    :maxdepth: 2
    :caption: Contents:
 
-   /build/repositories/README
+   /build/index
    /apps/haikudepot/server
    /midi/index
    /net/NetworkStackOverview