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.
This commit is contained in:
Willy Tarreau
parent
8e0263323c
commit
763475fa11
161
INSTALL
161
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
|
||||
|
|
|
|||
Loading…
Reference in New Issue