Merged rt43327 (build change doc)

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