From 763475fa115bced40971d6de8fb7691e1047fc34 Mon Sep 17 00:00:00 2001 From: Willy Tarreau Date: Thu, 11 Apr 2024 17:59:19 +0200 Subject: [PATCH] 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 | 161 ++++++++++++++++++++++++++++++++++++++------------------ 1 file changed, 109 insertions(+), 52 deletions(-) diff --git a/INSTALL b/INSTALL index e09d0d1b93..d0cd4d1ba0 100644 --- a/INSTALL +++ b/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 -check the Makefile to see which ones will be available in your case, and -use/override the USE_* variables from the Makefile. +5.7) Summary of the Makefile's main variables +--------------------------------------------- -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 - -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 +The following variables are commonly used: + - TARGET platform name, empty by default, see help + - CC path to the C compiler, defaults to "cc" + - LD path to the linker, defaults to "$CC" + - CFLAGS CFLAGS to append at the end, empty by default + - LDFLAGS LDFLAGS to append at the end, empty by default + - ARCH_FLAGS flags common to CC and LD (-fsanitize, etc). Defaults to "-g" + - OPT_CFLAGS C compiler optimization level. Defaults to "-O2" + - WARN_CFLAGS list of autodetected C compiler warnings to enable + - NOWARN_CFLAGS list of autodetected C compiler warnings to disable + - ADDINC include directives to append at the end, empty by default + - ADDLIB lib directives to append at the end, empty by default + - DEFINE extra macros definitions for compiler, empty by default + - DEBUG extra DEBUG options for compiler, empty by default + - ERR enables -Werror if non-zero, empty by default + - FAILFAST enables -Wfatal-error if non-zero, empty by default 6) How to install HAProxy