DOC: install: clarify the build process by splitting it into subsections

The doc about the build process has grown to a point where it was painful
to read when searching a specific element. This commit cuts it into a few
sub-categories for ease of searching, and it also adds a summary of the
most commonly used makefile variables, their usage and default settings.

INSTALL

@@ -537,7 +537,11 @@ bindings must be explicitly enabled with a specific QUIC tuning parameter.
 
 This section assumes that you have already read section 2 (basic principles)
 and section 3 (build environment). It often refers to section 4 (dependencies).
+It goes into more details with the main options.
 
+
+5.1) Configuring the TARGET
+---------------------------
 To build haproxy, you have to choose your target OS amongst the following ones
 and assign it to the TARGET variable :
 
@@ -558,6 +562,34 @@ and assign it to the TARGET variable :
   - generic             for any other OS or version.
   - custom              to manually adjust every setting
 
+Example:
+    $ make -j $(nproc) TARGET=linux-glibc
+
+AIX 5.3 is known to work with the generic target. However, for the binary to
+also run on 5.2 or earlier, you need to build with DEFINE="-D_MSGQSUPPORT",
+otherwise __fd_select() will be used while not being present in the libc, but
+this is easily addressed using the "aix52" target. If you get build errors
+because of strange symbols or section mismatches, simply remove -g from
+ARCH_FLAGS.
+
+Building on AIX 7.2 works fine using the "aix72-gcc" TARGET. It adds two
+special CFLAGS to prevent the loading of AIX's xmem.h and var.h. This is done
+by defining the corresponding include-guards _H_XMEM and _H_VAR. Without
+excluding those header-files the build fails because of redefinition errors.
+Furthermore, the atomic library is added to the LDFLAGS to allow for
+multithreading via USE_THREAD.
+
+You can easily define your own target with the GNU Makefile. Unknown targets
+are processed with no default option except USE_POLL=default. So you can very
+well use that property to define your own set of options. USE_POLL and USE_SLZ
+can even be disabled by setting them to an empty string or a zero. For
+example :
+
+  $ gmake TARGET=tiny USE_POLL="" USE_SLZ=0 TARGET_CFLAGS=-fomit-frame-pointer
+
+
+5.2) Adding extra CFLAGS for compiling
+--------------------------------------
 A generic CFLAGS variable may be set to append any option to pass to the C
 compiler. These flags are passed last so the variable may be used to override
 other options such as warnings, optimization levels, include paths etc.
@@ -605,6 +637,29 @@ flags are passed to the compiler nor what compiler is involved. Simply append
 details again. It is recommended to use this option when cross-compiling to
 verify that the paths are correct and that /usr/include is never involved.
 
+If you need to pass some defines to the preprocessor or compiler, you may pass
+them all in the DEFINE variable. Example:
+
+  $ make TARGET=generic DEFINE="-DDEBUG_DONT_SHARE_POOLS"
+
+The ADDINC variable may be used to add some extra include paths; this is
+sometimes needed when cross-compiling. Similarly the ADDLIB variable may be
+used to specify extra paths to library files. Example :
+
+  $ make TARGET=generic ADDINC=-I/opt/cross/include ADDLIB=-L/opt/cross/lib64
+
+
+5.3) Adding extra LDFLAGS for linking
+-------------------------------------
+If a particular target requires specific link-time flags, these can be passed
+via the LDFLAGS variable. This variable is passed to the linker immediately
+after ARCH_FLAGS. One of the common use cases is to add some run time search
+paths for a dynamic library that's not part of the default system search path:
+
+    $ make -j $(nproc) TARGET=generic USE_OPENSSL_AWSLC=1 USE_QUIC=1 \
+      SSL_INC=/opt/aws-lc/include SSL_LIB=/opt/aws-lc/lib \
+      LDFLAGS="-Wl,-rpath,/opt/aws-lc/lib"
+
 Some options require to be consistent between the compilation stage and the
 linking stage. This is the case for options which enable debugging (e.g. "-g"),
 profiling ("-pg"), link-time optimization ("-flto"), endianness ("-EB", "-EL"),
@@ -622,15 +677,9 @@ and building with the address sanitizer (ASAN) simply requires:
 
     $ make TARGET=linux-glibc ARCH_FLAGS="-fsanitize=address -g"
 
-If a particular target requires specific link-time flags, these can be passed
-via the LDFLAGS variable. This variable is passed to the linker immediately
-after ARCH_FLAGS. One of the common use cases is to add some run time search
-paths for a dynamic library that's not part of the default system search path:
-
-    $ make -j $(nproc) TARGET=generic USE_OPENSSL_AWSLC=1 USE_QUIC=1 \
-      SSL_INC=/opt/aws-lc/include SSL_LIB=/opt/aws-lc/lib \
-      LDFLAGS="-Wl,-rpath,/opt/aws-lc/lib"
 
+5.4) Other common OS-specific options
+-------------------------------------
 Recent systems can resolve IPv6 host names using getaddrinfo(). This primitive
 is not present in all libcs and does not work in all of them either. Support in
 glibc was broken before 2.3. Some embedded libs may not properly work either,
@@ -657,6 +706,13 @@ section 4 about dependencies for more information on how to build with OpenSSL.
 HAProxy can compress HTTP responses to save bandwidth. Please see section 4
 about dependencies to see the available libraries and associated options.
 
+If you need to pass other defines, includes, libraries, etc... then please
+check the Makefile to see which ones will be available in your case, and
+use/override the USE_* variables from the Makefile.
+
+
+5.5) Adjusting the build error / warning behavior
+-------------------------------------------------
 If the ERR variable is set to any non-empty value other than "0", then -Werror
 will be added to the compiler so that any build warning will trigger an error.
 This is the recommended way to build when developing, and it is expected that
@@ -680,6 +736,33 @@ WARN_CFLAGS (i.e. it can undo some of the WARN_CFLAGS settings). Be careful
 with it, as clearing this list can yield many warnings depending on the
 compiler and options.
 
+The DEP variable is automatically set to the list of include files and also
+designates a file that contains the last build options used. It is used during
+the build process to compute dependencies and decide whether or not to rebuild
+everything (we do rebuild everything when .h files are touched or when build
+options change). Sometimes when performing fast build iterations on inline
+functions it may be desirable to avoid a full rebuild. Forcing this variable
+to be empty will be sufficient to achieve this. This variable must never be
+forced to produce final binaries, and must not be used during bisect sessions,
+as it will often lead to the wrong commit.
+
+Examples:
+  # silence strict-aliasing warnings with old gcc-4.4:
+  $ make -j$(nproc) TARGET=linux-glibc CC=gcc-44 CFLAGS=-fno-strict-aliasing
+
+  # disable all warning options:
+  $ make -j$(nproc) TARGET=linux-glibc CC=mycc WARN_CFLAGS= NOWARN_CFLAGS=
+
+  # enable -Werror and -Wfatal-errors to immediately stop on error
+  $ make -j$(nproc) TARGET=linux-glibc ERR=1 FAILFAST=1
+
+  # try to restart the build where it was after hacking an include file, to
+  # check if that was sufficient or not:
+  $ make -j$(nproc) TARGET=linux-glibc ERR=1 DEP=
+
+
+5.6) Enabling a DEBUG build
+---------------------------
 The DEBUG variable is used to extend the CFLAGS and is preset to a list of
 build-time options that are known for providing significant reliability
 improvements and a barely perceptible performance cost. Unless instructed to do
@@ -751,52 +834,26 @@ or trying to nail a bug down, use "-DDEBUG_STRICT=2 -DDEBUG_STRICT_ACTION=2 \
 memory usage by disabling these integrity features, it is also possible to use
 "-DDEBUG_STRICT=0 -DDEBUG_MEMORY_POOLS=0".
 
-The DEP variable is automatically set to the list of include files and also
-designates a file that contains the last build options used. It is used during
-the build process to compute dependencies and decide whether or not to rebuild
-everything (we do rebuild everything when .h files are touched or when build
-options change). Sometimes when performing fast build iterations on inline
-functions it may be desirable to avoid a full rebuild. Forcing this variable
-to be empty will be sufficient to achieve this. This variable must never be
-forced to produce final binaries, and must not be used during bisect sessions,
-as it will often lead to the wrong commit.
 
-If you need to pass other defines, includes, libraries, etc... then please
+5.7) Summary of the Makefile's main variables
-check the Makefile to see which ones will be available in your case, and
+---------------------------------------------
-use/override the USE_* variables from the Makefile.
 
-AIX 5.3 is known to work with the generic target. However, for the binary to
+The following variables are commonly used:
-also run on 5.2 or earlier, you need to build with DEFINE="-D_MSGQSUPPORT",
+  - TARGET        platform name, empty by default, see help
-otherwise __fd_select() will be used while not being present in the libc, but
+  - CC            path to the C compiler, defaults to "cc"
-this is easily addressed using the "aix52" target. If you get build errors
+  - LD            path to the linker, defaults to "$CC"
-because of strange symbols or section mismatches, simply remove -g from
+  - CFLAGS        CFLAGS to append at the end, empty by default
-ARCH_FLAGS.
+  - LDFLAGS       LDFLAGS to append at the end, empty by default
-
+  - ARCH_FLAGS    flags common to CC and LD (-fsanitize, etc). Defaults to "-g"
-Building on AIX 7.2 works fine using the "aix72-gcc" TARGET. It adds two
+  - OPT_CFLAGS    C compiler optimization level. Defaults to "-O2"
-special CFLAGS to prevent the loading of AIX's xmem.h and var.h. This is done
+  - WARN_CFLAGS   list of autodetected C compiler warnings to enable
-by defining the corresponding include-guards _H_XMEM and _H_VAR. Without
+  - NOWARN_CFLAGS list of autodetected C compiler warnings to disable
-excluding those header-files the build fails because of redefinition errors.
+  - ADDINC        include directives to append at the end, empty by default
-Furthermore, the atomic library is added to the LDFLAGS to allow for
+  - ADDLIB        lib directives to append at the end, empty by default
-multithreading via USE_THREAD.
+  - DEFINE        extra macros definitions for compiler, empty by default
-
+  - DEBUG         extra DEBUG options for compiler, empty by default
-You can easily define your own target with the GNU Makefile. Unknown targets
+  - ERR           enables -Werror if non-zero, empty by default
-are processed with no default option except USE_POLL=default. So you can very
+  - FAILFAST      enables -Wfatal-error if non-zero, empty by default
-well use that property to define your own set of options. USE_POLL and USE_SLZ
-can even be disabled by setting them to an empty string or a zero. For
-example :
-
-  $ gmake TARGET=tiny USE_POLL="" USE_SLZ=0 TARGET_CFLAGS=-fomit-frame-pointer
-
-If you need to pass some defines to the preprocessor or compiler, you may pass
-them all in the DEFINE variable. Example:
-
-  $ make TARGET=generic DEFINE="-DDEBUG_DONT_SHARE_POOLS"
-
-The ADDINC variable may be used to add some extra include paths; this is
-sometimes needed when cross-compiling. Similarly the ADDLIB variable may be
-used to specify extra paths to library files. Example :
-
-  $ make TARGET=generic ADDINC=-I/opt/cross/include ADDLIB=-L/opt/cross/lib64
 
 
 6) How to install HAProxy