summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorFrancis Dupont <fdupont@isc.org>2017-12-18 16:05:40 +0100
committerFrancis Dupont <fdupont@isc.org>2017-12-18 16:05:40 +0100
commit1e80a731f0b8755b527b37a3e7e5a96938188273 (patch)
treeb8e6ec5bb8eb9f3425595190157fa3bffedd1151
parent4406f9b05dfc3aa5f232e01be94fb38950e3661f (diff)
downloadisc-dhcp-1e80a731f0b8755b527b37a3e7e5a96938188273.tar.gz
Merged rt43327 (build change doc)
-rw-r--r--Makefile.am6
-rw-r--r--Makefile.in16
-rw-r--r--doc/BIND-libraries170
-rw-r--r--doc/devel/libtool.dox77
-rw-r--r--doc/devel/mainpage.dox3
5 files changed, 261 insertions, 11 deletions
diff --git a/Makefile.am b/Makefile.am
index f66f456c..e78b328f 100644
--- a/Makefile.am
+++ b/Makefile.am
@@ -18,7 +18,7 @@ EXTRA_DIST = RELNOTES LICENSE configure.ac+lt config+lt \
contrib/ms2isc/readme.txt contrib/ldap/dhcpd-conf-to-ldap \
contrib/ldap/dhcp.schema contrib/ldap/README.ldap \
contrib/dhcp-lease-list.pl \
- doc/DHCPv4-over-DHCPv6 \
+ doc/BIND-libraries doc/DHCPv4-over-DHCPv6 \
doc/IANA-arp-parameters doc/Makefile doc/References.html \
doc/References.txt doc/References.xml doc/api+protocol \
doc/ja_JP.eucJP/dhclient-script.8 doc/ja_JP.eucJP/dhclient.8 \
@@ -26,8 +26,8 @@ EXTRA_DIST = RELNOTES LICENSE configure.ac+lt config+lt \
doc/ja_JP.eucJP/dhcp-eval.5 doc/ja_JP.eucJP/dhcp-options.5 \
doc/examples/dhclient-dhcpv6.conf doc/examples/dhcpd-dhcpv6.conf \
doc/devel/arch.dox doc/devel/atf.dox doc/devel/contrib.dox \
- doc/devel/debug.dox doc/devel/isc-logo.jpg doc/devel/mainpage.dox \
- doc/devel/omapi.dox doc/devel/qa.dox \
+ doc/devel/debug.dox doc/devel/isc-logo.jpg doc/devel/libtool.dox \
+ doc/devel/mainpage.dox doc/devel/omapi.dox doc/devel/qa.dox \
common/tests/Atffile server/tests/Atffile
if HAVE_BINDDIR
diff --git a/Makefile.in b/Makefile.in
index 8735e660..db6b0193 100644
--- a/Makefile.in
+++ b/Makefile.in
@@ -370,19 +370,19 @@ EXTRA_DIST = RELNOTES LICENSE configure.ac+lt config+lt \
contrib/ms2isc/Registry.pm contrib/ms2isc/ms2isc.pl \
contrib/ms2isc/readme.txt contrib/ldap/dhcpd-conf-to-ldap \
contrib/ldap/dhcp.schema contrib/ldap/README.ldap \
- contrib/dhcp-lease-list.pl doc/DHCPv4-over-DHCPv6 \
- doc/IANA-arp-parameters doc/Makefile doc/References.html \
- doc/References.txt doc/References.xml doc/api+protocol \
- doc/ja_JP.eucJP/dhclient-script.8 doc/ja_JP.eucJP/dhclient.8 \
- doc/ja_JP.eucJP/dhclient.conf.5 \
+ contrib/dhcp-lease-list.pl doc/BIND-libraries \
+ doc/DHCPv4-over-DHCPv6 doc/IANA-arp-parameters doc/Makefile \
+ doc/References.html doc/References.txt doc/References.xml \
+ doc/api+protocol doc/ja_JP.eucJP/dhclient-script.8 \
+ doc/ja_JP.eucJP/dhclient.8 doc/ja_JP.eucJP/dhclient.conf.5 \
doc/ja_JP.eucJP/dhclient.leases.5 doc/ja_JP.eucJP/dhcp-eval.5 \
doc/ja_JP.eucJP/dhcp-options.5 \
doc/examples/dhclient-dhcpv6.conf \
doc/examples/dhcpd-dhcpv6.conf doc/devel/arch.dox \
doc/devel/atf.dox doc/devel/contrib.dox doc/devel/debug.dox \
- doc/devel/isc-logo.jpg doc/devel/mainpage.dox \
- doc/devel/omapi.dox doc/devel/qa.dox common/tests/Atffile \
- server/tests/Atffile $(am__append_1)
+ doc/devel/isc-logo.jpg doc/devel/libtool.dox \
+ doc/devel/mainpage.dox doc/devel/omapi.dox doc/devel/qa.dox \
+ common/tests/Atffile server/tests/Atffile $(am__append_1)
# Use an autoconf substitution vs an automake conditional here
# to fool automake when the bind directory does not exist.
diff --git a/doc/BIND-libraries b/doc/BIND-libraries
new file mode 100644
index 00000000..371e53c7
--- /dev/null
+++ b/doc/BIND-libraries
@@ -0,0 +1,170 @@
+Current ISC DHCP uses the BIND 9 libraries for some services.
+These libraries can be embedded in the bind directory or external using
+the configuration parameter --with-libbind=PATH with PATh pointing to
+the directory where can be found includes and libraries.
+
+Using standard embedded libraries is safe but you can configure
+them with extra parameters (cf --with-bind-extra-config) or simply
+use external libraries with a different configuration.
+
+Note if you want to share libraries between bind 9 and ISC DHCP
+BIND 9 must be built and installed before ISC DHCP build is configured.
+
+Three cases are possible:
+ - everything builds and works fine
+
+ - building requires extra parameters, for instance --enable-threads
+ can require a link parameter to find POSIX threads.
+ In this case you should look at the config.status file of the bind
+ libraries, take CC, CPPFLAGS, CFLAGS, LIBS or LDFLAGS related
+ parameters, and add them to the call to make.
+
+ - even when the previous step succeeds ISC DHCP still does not work
+ properly. We are trying to collect such cases (cf the list bellow)
+ but unfortunately you have to forget the particular feature.
+
+Below you have 3 kinds of don't use:
+ - please don't use means it should likely break ISC DHCP
+
+ - don't use means unless you don't have a good reason to use it
+
+ - by default don't use it means you should not use it for embedded
+ libraries but it doesn't lead to problems (other than possible
+ new ISC DHCP build flags and bigger binaries) when used for
+ external BIND 9 libraries
+
+Possible bind9 configuration flags (list built from bind 9.11 and bind 9.12
+various branches even ISC DHCP uses only the git v9_11 branch):
+ -h, --help, -V, --version
+ make configure to exit immediately so don't use
+
+ -q, --quiet, --silent, --cache-file, -C, --config-cache,
+ --with-make-clean
+ you have no reason to use them but they should not have bad effect
+
+ -n, --no-create
+ make configure to exit too early so don't use
+
+ --prefix, --exec-prefix
+ not used for embedded libraries but used by BIND 9
+
+ --bindir, --sbindir, --libexecdir, --sysconfdir, --sharedstatedir,
+ --localstatedir, --oldincludedir, --datarootdir, --datadir, --infodir,
+ --localedir, --mandir, --docdir, --htmldir, --dvidir, --pdfdir, --psdir
+ not used for embedded nor BIND 9 for its includes and libraries
+
+ --libdir, --includedir
+ used for embedded libraries for the make install (cf the
+ --enable-bind-install ISC DHCP configuration parameter)
+
+ --build, --host
+ used for cross compiling and handled by ISC DHCP configure
+
+ --disable-option-checking
+ this disables a sanity check so please don't use
+
+ --enable-shared, --enable-static, --enable-fast-install
+ ignored by embedded or BIND 9 libraries configure
+
+ --disable-libtool-lock
+ parallel builds don't work for embedded or BIND 9 libraries build
+ so it should not have any effect
+
+ --enable-libbind
+ this was deprecated so please don't use
+
+ --enable-warn-shadow
+ for developers, should have no effect if compilers don't raise errors
+ (vs warnings) on this (and a shadowing was left)
+
+ --enable-warn-error, --with-sysroot
+ this likely breaks the build so please don't use
+
+ --enable-developer
+ for developers, should have no direct effect but still recommend
+ to not use it
+
+ --enable-afl
+ for developers, useless for ISC DHCP so don't use
+
+ --enable-seccomp
+ this should not have any effect for ISC DHCP?
+
+ --enable-kqueue, --enable-epoll, --enable-devpoll
+ please use them at the ISC DHCP configure level, they should work
+ but not yet fully tested so use at your own risk
+
+ --enable-threads
+ this should work but not yet fully tested so use at your own risk.
+ Note on many systems it requires an extra flag for ISC DHCP building
+ and some experiments showed a large slow down when this is enabled
+
+ --enable-native-pkcs11
+ You should not have a reason to use this and it likely won't work
+ so please don't use
+
+ --enable-openssl-version-check
+ You should never use an antic version of OpenSSL with known
+ security bugs so please don't use
+
+ --enable-openssl-hash
+ Comes with --with-openssl so if OpenSSL raises some problems with
+ hash or HMAC you can try to disable this
+
+ --enable-crypto-rand
+ Comes with --with-openssl so if OpenSSL raises some problems with
+ random number generation you can try to disable this
+
+ --enable-largefile
+ Perhaps there is no systems today where this is required so
+ by default don't use
+
+ --enable-backtrace, --enable-symtable
+ this should have no effect for ISC DHCP?
+
+ --enable-ipv6, --disable-tcp-fastopen, --enable-getifaddrs, --enable-atomic
+ please leave embedded or BIND 9 libraries configure to do its job
+ so please don't use
+
+ --disable-isc-spnego, --with-gssapi
+ this should have no effect for ISC DHCP?
+
+ --enable-full-report
+ this should have no effect for ISC DHCP but is still useful
+ to get more information about bind configuration so use it
+ if you believe it can be useful
+
+ --disable-chroot, --disable-linux-caps, --enable-fixed-rrset,
+ --disable-rpz-nsip, --disable-rpz-nsdname, --enable-filter-aaaa,
+ --enable-querytrace, --with-python, --with-python-install-dir,
+ --with-locktype, --with-pkcs11, --with-ecdsa, --with-gost,
+ --with-eddsa, --with-aes, --with-cc-alg, --with-purify,
+ --with-gperftools-profiler, --with-kame, --with-docbook-xsl,
+ --with-dlopen
+ this should have no effect for ISC DHCP
+
+ --enable-dnsrps-dl, --enable-dnsrps, --enable-dnstap, --with-geoip,
+ --with-lmdb, --with-libxml2, --with-libjson, --with-zlib,
+ --with-readline, --with-dnsrps-libname, --with-dnsrps-dir,
+ --with-protobuf-c, --with-libfstrm, --with-idn, --with-libiconv,
+ --with-iconv, --with-idnlib, --with-dlz-*
+ useless for ISC DHCP so by default don't use
+
+ --with-pic
+ this should have no effect for ISC DHCP?
+
+ --with-gnu-ld
+ this should have no effect for ISC DHCP?
+
+ --with-randomdev, --with-atf
+ please use them at the ISC DHCP configure level
+
+ --with-libtool
+ please leave the ISC DHCP configure manage this
+
+ --with-openssl
+ useless for ISC DHCP by default don't use but remember it is
+ required for DNSSEC
+
+ --with-tuning
+ by default don't use
diff --git a/doc/devel/libtool.dox b/doc/devel/libtool.dox
new file mode 100644
index 00000000..d5cb3747
--- /dev/null
+++ b/doc/devel/libtool.dox
@@ -0,0 +1,77 @@
+/**
+@page libtool Build with libtool
+
+@section libtoolBuild
+
+4.4.0 introduces the dynamic library build option. It uses Gnu autotools
+and in particular libtool but is fully backward compatible.
+
+The Gnu autoreconf which is a driver for other autotools: it runs
+autoconf (building configure from configure.ac), autoheader (creating
+the AC_CONFIG_HEADERS file, includes/config.h for ISC DHC), aclocal
+(building aclocal.m4 script), automake (creating .in files from .am files),
+libtoolize (adding libtool support when enabled in configure.ac) and
+autopoint (for gettext which is not used by ISC DHCP).
+
+Static libraries are built using the same setup as in previous versions.
+This enforces strict backward compatibility and is the default option
+so users who do not want dynamic libraries have nothing different to do.
+(In other words changes for the support of dynamic libraries is invisible
+for legacy users).
+
+Dynamic libraries are handled by libtool, and therefore require a few
+extra steps before invoking configure. For users not reading the
+documentation but still wanting dynamic libraries "--enable-libtool"
+is accepted even without these extra steps (cp configure.ac+lt configure.ac;
+autoreconf -i) in a recovery procedure (invoking config+lt script)
+but not in a very robust way. Note libtool allows you to build static
+libraries: there is nothing to make this impossible but as the
+recommend way to build static libraries does not use libtool it is
+neither recommended nor supported.
+
+The autoreconf input file is configure.ac. There are four versions of this:
+
+ - configure.ac-base which has code for legacy and libtool options
+
+ - configure.ac-lt which has only the legacy option with recovery
+ when --with-libtool is given. Note it is not included in the
+ distribution as its configure.ac copy is
+
+ - configure.ac+lt which has the libool code and defaults to --with-libtool
+
+ - configure.ac which is either configure.ac-lt in the distribution and
+ configure.ac+lt when copied by the user at the first step for dynamic
+ libraries or by the config+lt recovery script
+
+Three scripts manage legacy and libtool options:
+
+ - util/lt.pl which extracts configure.ac-lt and configure.ac+lt from
+ configure.ac-base
+
+ - util/regen.sh which invokes util/lt.pl and copies configure.ac-lt
+ to configure.ac and run autoconf. The correct way for developers to
+ update the configure system is to update configure.ac-base and
+ to call util/regen.sh
+
+ - config+lt which is the recovery script. As it can be called in place
+ of configure it must be executable (i.e. -rwxr-xr-x rights) in
+ the distribution.
+ To perform the reverse recovery, i.e. from libtool to legacy options,
+ the simplest (and most reliable) way is to simply clean the build
+ directory and to restart from the initial step, i.e., to extract
+ the distribution.
+
+Automake uses different names for library related variables if libtool
+is used or not for some Makefile's the procedure is a bit complex.
+
+Usually the source Makefile is Makefile.am. Automake is run before
+the distribution build to generate Makefile.in and at configuration
+time the config.status script is invoked at the end of ./configure
+on AC_CONFIG_FILES to substitute @xxx@ variables into Makefile.
+
+ISC DHCP uses an extra step with a postconfig phase at the end
+of ./configure which invokes automake and reruns config.status
+giving a chain with Makefile.am.in, Makefile.am, Makefile.in and
+Makefile
+
+*/
diff --git a/doc/devel/mainpage.dox b/doc/devel/mainpage.dox
index b6d5c431..2fd551e9 100644
--- a/doc/devel/mainpage.dox
+++ b/doc/devel/mainpage.dox
@@ -8,6 +8,9 @@
http://www.isc.org/software/dhcp website.
@section toc Table Of Contents
+ - Build
+ - @subpage libtool
+ - @subpage libtoolBuild
- Server
- @subpage ipv6structures
- @subpage tests