|
Packit Service |
6d40f9 |
|
|
Packit Service |
6d40f9 |
|
|
Packit Service |
6d40f9 |
"http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd">
|
|
Packit Service |
6d40f9 |
|
|
Packit Service |
6d40f9 |
<chapter id="devel">
|
|
Packit Service |
6d40f9 |
<title>Building, Packaging, and Contributing to adcli</title>
|
|
Packit Service |
6d40f9 |
|
|
Packit Service |
6d40f9 |
<section id="devel-links">
|
|
Packit Service |
6d40f9 |
<title>Helpful Resources</title>
|
|
Packit Service |
6d40f9 |
|
|
Packit Service |
6d40f9 |
<para>Use the following to find more information about
|
|
Packit Service |
6d40f9 |
contributing to adcli beyond what's in this manual:</para>
|
|
Packit Service |
6d40f9 |
|
|
Packit Service |
6d40f9 |
<itemizedlist>
|
|
Packit Service |
6d40f9 |
<listitem><para><ulink url="http://www.freedesktop.org/software/realmd/adcli/">Website</ulink></para></listitem>
|
|
Packit Service |
6d40f9 |
<listitem><para><ulink url="mail:authentication@lists.freedesktop.org">Mailing list</ulink></para></listitem>
|
|
Packit Service |
6d40f9 |
<listitem><para><ulink url="https://bugs.freedesktop.org/enter_bug.cgi?product=realmd&component=adcli">Bugzilla</ulink></para></listitem>
|
|
Packit Service |
6d40f9 |
</itemizedlist>
|
|
Packit Service |
6d40f9 |
</section>
|
|
Packit Service |
6d40f9 |
|
|
Packit Service |
6d40f9 |
<section id="devel-building">
|
|
Packit Service |
6d40f9 |
<title>Compiling adcli from Source</title>
|
|
Packit Service |
6d40f9 |
<para>This describes how to compiling the adcli package from
|
|
Packit Service |
6d40f9 |
source code. This is normally only necessary for those wishing to
|
|
Packit Service |
6d40f9 |
contribute to the project or package adcli.</para>
|
|
Packit Service |
6d40f9 |
|
|
Packit Service |
6d40f9 |
<para>You can download
|
|
Packit Service |
6d40f9 |
<ulink url="http://www.freedesktop.org/software/realmd/releases/">tarballs
|
|
Packit Service |
6d40f9 |
of the releases</ulink> of adcli or
|
|
Packit Service |
6d40f9 |
<ulink url="http://cgit.freedesktop.org/realmd/adcli/">check
|
|
Packit Service |
6d40f9 |
out the source code from git</ulink>. This documentation will not
|
|
Packit Service |
6d40f9 |
go into all the details of how to get your development environment
|
|
Packit Service |
6d40f9 |
set up and instead focus on the what's unique to compiling adcli.</para>
|
|
Packit Service |
6d40f9 |
|
|
Packit Service |
6d40f9 |
<section id="devel-building-dependencies">
|
|
Packit Service |
6d40f9 |
<title>Dependencies</title>
|
|
Packit Service |
6d40f9 |
|
|
Packit Service |
6d40f9 |
<para>Besides the default autotools, binutils and GCC, adcli requires the
|
|
Packit Service |
6d40f9 |
following development dependencies to build:</para>
|
|
Packit Service |
6d40f9 |
|
|
Packit Service |
6d40f9 |
<itemizedlist>
|
|
Packit Service |
6d40f9 |
<listitem><para>OpenLDAP client libraries</para></listitem>
|
|
Packit Service |
6d40f9 |
<listitem><para>MIT Kerberos libraries</para></listitem>
|
|
Packit Service |
6d40f9 |
</itemizedlist>
|
|
Packit Service |
6d40f9 |
|
|
Packit Service |
6d40f9 |
<para>On <emphasis role="strong">Debian</emphasis> or <emphasis role="strong">Ubuntu</emphasis> you can use the following command to
|
|
Packit Service |
6d40f9 |
install the dependencies:</para>
|
|
Packit Service |
6d40f9 |
|
|
Packit Service |
6d40f9 |
<programlisting>
|
|
Packit Service |
6d40f9 |
$ sudo apt-get install build-essential autoconf automake xmlto xsltproc \
|
|
Packit Service |
6d40f9 |
libkrb5-dev libldap2-dev libsasl2-dev
|
|
Packit Service |
6d40f9 |
</programlisting>
|
|
Packit Service |
6d40f9 |
|
|
Packit Service |
6d40f9 |
<para>On <emphasis role="strong">Fedora</emphasis> you can use the following command to install the
|
|
Packit Service |
6d40f9 |
dependencies:</para>
|
|
Packit Service |
6d40f9 |
|
|
Packit Service |
6d40f9 |
<programlisting>
|
|
Packit Service |
6d40f9 |
$ sudo yum groupinstall "Development Tools"
|
|
Packit Service |
6d40f9 |
$ sudo yum install automake autoconf xmlto xsltproc krb5-devel openldap-devel \
|
|
Packit Service |
6d40f9 |
cyrus-sasl-devel
|
|
Packit Service |
6d40f9 |
</programlisting>
|
|
Packit Service |
6d40f9 |
|
|
Packit Service |
6d40f9 |
</section>
|
|
Packit Service |
6d40f9 |
|
|
Packit Service |
6d40f9 |
<section id="devel-building-unix">
|
|
Packit Service |
6d40f9 |
<title>Building on UNIX</title>
|
|
Packit Service |
6d40f9 |
<para>adcli uses the standard GNU build system, using autoconf for package
|
|
Packit Service |
6d40f9 |
configuration and resolving portability issues, automake for building makefiles
|
|
Packit Service |
6d40f9 |
that comply with the GNU Coding Standards, and libtool for building shared
|
|
Packit Service |
6d40f9 |
libraries on multiple platforms. The normal sequence for compiling and
|
|
Packit Service |
6d40f9 |
installing adcli is thus:</para>
|
|
Packit Service |
6d40f9 |
|
|
Packit Service |
6d40f9 |
<programlisting>
|
|
Packit Service |
6d40f9 |
$ ./configure --prefix=/usr --sysconfdir=/etc...
|
|
Packit Service |
6d40f9 |
$ make
|
|
Packit Service |
6d40f9 |
$ make install
|
|
Packit Service |
6d40f9 |
</programlisting>
|
|
Packit Service |
6d40f9 |
|
|
Packit Service |
6d40f9 |
<para>If you've checked out the source code from git, then the
|
|
Packit Service |
6d40f9 |
<command>configure</command> script does not yet exist. So use
|
|
Packit Service |
6d40f9 |
the following instead:</para>
|
|
Packit Service |
6d40f9 |
|
|
Packit Service |
6d40f9 |
<programlisting>
|
|
Packit Service |
6d40f9 |
$ ./autogen.sh --prefix=/usr --sysconfdir=/etc ...
|
|
Packit Service |
6d40f9 |
$ make
|
|
Packit Service |
6d40f9 |
$ make install
|
|
Packit Service |
6d40f9 |
</programlisting>
|
|
Packit Service |
6d40f9 |
|
|
Packit Service |
6d40f9 |
<para>The standard options provided by GNU autoconf may be passed to the configure
|
|
Packit Service |
6d40f9 |
script. Please see the autoconf documentation or run <literal>./configure --help</literal>
|
|
Packit Service |
6d40f9 |
for information about the standard options. In particular you probably want to adjust
|
|
Packit Service |
6d40f9 |
the <literal>--prefix=/xxx</literal> argument depending on your system and development
|
|
Packit Service |
6d40f9 |
environment.</para>
|
|
Packit Service |
6d40f9 |
|
|
Packit Service |
6d40f9 |
<para>Make sure that the <literal>--sysconfdir=/etc</literal> matches the directory
|
|
Packit Service |
6d40f9 |
where the the MIT kerberos library stores its <literal>krb5.conf</literal>. This is
|
|
Packit Service |
6d40f9 |
usually <literal>/etc</literal></para>
|
|
Packit Service |
6d40f9 |
</section>
|
|
Packit Service |
6d40f9 |
|
|
Packit Service |
6d40f9 |
<section id="devel-building-configure">
|
|
Packit Service |
6d40f9 |
<title>Extra Configuration Options</title>
|
|
Packit Service |
6d40f9 |
|
|
Packit Service |
6d40f9 |
<para>In addition to the normal options, the configure script in the adcli
|
|
Packit Service |
6d40f9 |
supports these additional arguments:</para>
|
|
Packit Service |
6d40f9 |
|
|
Packit Service |
6d40f9 |
<variablelist>
|
|
Packit Service |
6d40f9 |
<varlistentry>
|
|
Packit Service |
6d40f9 |
<term><option>--disable-debug</option>, <option>--enable-debug</option></term>
|
|
Packit Service |
6d40f9 |
<listitem><para>By default adcli is built with debug symbols assertions and
|
|
Packit Service |
6d40f9 |
and precondition checks. Enabling the debug option configures even more
|
|
Packit Service |
6d40f9 |
detailed debug build, including disabling optimization. Disabling the debug
|
|
Packit Service |
6d40f9 |
option is not recommended, as it disables all assertions, preconditions and
|
|
Packit Service |
6d40f9 |
internal consistency checks, although it may result it a slightly faster
|
|
Packit Service |
6d40f9 |
library.</para></listitem>
|
|
Packit Service |
6d40f9 |
</varlistentry>
|
|
Packit Service |
6d40f9 |
<varlistentry>
|
|
Packit Service |
6d40f9 |
<term><option>--disable-doc</option></term>
|
|
Packit Service |
6d40f9 |
<listitem><para>Disables building of the documentation and command line manual.
|
|
Packit Service |
6d40f9 |
The documentation is built in the <literal>doc/html/</literal> directory of
|
|
Packit Service |
6d40f9 |
the build.</para></listitem>
|
|
Packit Service |
6d40f9 |
</varlistentry>
|
|
Packit Service |
6d40f9 |
<varlistentry>
|
|
Packit Service |
6d40f9 |
<term><option>--enable-strict</option></term>
|
|
Packit Service |
6d40f9 |
<listitem><para>Enables strict checks during building of adcli. All
|
|
Packit Service |
6d40f9 |
compiler warnings become errors.</para></listitem>
|
|
Packit Service |
6d40f9 |
</varlistentry>
|
|
Packit Service |
6d40f9 |
</variablelist>
|
|
Packit Service |
6d40f9 |
<para></para>
|
|
Packit Service |
6d40f9 |
</section>
|
|
Packit Service |
6d40f9 |
</section>
|
|
Packit Service |
6d40f9 |
|
|
Packit Service |
6d40f9 |
<section id="devel-building-style">
|
|
Packit Service |
6d40f9 |
<title>Coding Style</title>
|
|
Packit Service |
6d40f9 |
|
|
Packit Service |
6d40f9 |
<para>We use a code style similar to the linux kernel. Use tabs
|
|
Packit Service |
6d40f9 |
to indent and spaces to align/wrap beyond the indentation level.</para>
|
|
Packit Service |
6d40f9 |
|
|
Packit Service |
6d40f9 |
<para>We don't try to guarantee completely robust and problem free
|
|
Packit Service |
6d40f9 |
behavior in cases where the caller or system isn't behaving. We
|
|
Packit Service |
6d40f9 |
consider these to be outside of our control:</para>
|
|
Packit Service |
6d40f9 |
|
|
Packit Service |
6d40f9 |
<itemizedlist>
|
|
Packit Service |
6d40f9 |
<listitem><para>Broken input from callers. We use preconditions
|
|
Packit Service |
6d40f9 |
to check input and immediately return. We don't try to provide
|
|
Packit Service |
6d40f9 |
error codes for all the various ways callers can screw
|
|
Packit Service |
6d40f9 |
around.</para></listitem>
|
|
Packit Service |
6d40f9 |
|
|
Packit Service |
6d40f9 |
<listitem>
|
|
Packit Service |
6d40f9 |
<para>Out of memory. It is pretty much impossible to handle out
|
|
Packit Service |
6d40f9 |
of memory errors correctly. Handling them alongside other errors
|
|
Packit Service |
6d40f9 |
is naive and broken. We don't try to guarantee library state
|
|
Packit Service |
6d40f9 |
(such as locks or memory leaks) when memory allocation fails.</para>
|
|
Packit Service |
6d40f9 |
<para>We do check the results from all memory allocations, but
|
|
Packit Service |
6d40f9 |
treat them as unexpected conditions. As a nod to the behavior
|
|
Packit Service |
6d40f9 |
of callers of this library, we don't abort on memory allocation
|
|
Packit Service |
6d40f9 |
failures. We use preconditions with somewhat sane results.</para>
|
|
Packit Service |
6d40f9 |
<para>Exception: when reading files or allocating potentially
|
|
Packit Service |
6d40f9 |
unbounded amounts of memory, we should respond robustly to memory
|
|
Packit Service |
6d40f9 |
allocation failures.</para>
|
|
Packit Service |
6d40f9 |
</listitem>
|
|
Packit Service |
6d40f9 |
</itemizedlist>
|
|
Packit Service |
6d40f9 |
|
|
Packit Service |
6d40f9 |
<para>These unexpected conditions indicate a bug either in adcli or
|
|
Packit Service |
6d40f9 |
in the system. All bets are off once this occurs.</para>
|
|
Packit Service |
6d40f9 |
|
|
Packit Service |
6d40f9 |
<para>Use the <literal>return_val_xxx()</literal> precondition macros to
|
|
Packit Service |
6d40f9 |
check for unexpected conditions.</para>
|
|
Packit Service |
6d40f9 |
</section>
|
|
Packit Service |
6d40f9 |
|
|
Packit Service |
6d40f9 |
<section id="devel-testing">
|
|
Packit Service |
6d40f9 |
<title>Testing and Code Coverage</title>
|
|
Packit Service |
6d40f9 |
|
|
Packit Service |
6d40f9 |
<para>Low level input parsers and such code should have unit tests
|
|
Packit Service |
6d40f9 |
excercizing it. Use the <literal>make check</literal> command to run all
|
|
Packit Service |
6d40f9 |
the tests. If you run it from a subdirectory only the tests in that
|
|
Packit Service |
6d40f9 |
directory will be run.</para>
|
|
Packit Service |
6d40f9 |
|
|
Packit Service |
6d40f9 |
<para>To check for memory errors or memory leaks, run <literal>make memcheck</literal>
|
|
Packit Service |
6d40f9 |
or <literal>make leakcheck</literal> respectively. This requires valgrind
|
|
Packit Service |
6d40f9 |
be installed.</para>
|
|
Packit Service |
6d40f9 |
|
|
Packit Service |
6d40f9 |
<para>Build adcli with the <option>--enable-coverage</option> configure
|
|
Packit Service |
6d40f9 |
option to build code coverage support.</para>
|
|
Packit Service |
6d40f9 |
|
|
Packit Service |
6d40f9 |
<para>Once you've done that you can either use <literal>make coverage</literal>
|
|
Packit Service |
6d40f9 |
to build code coverage information. Alternatively (and this is usually
|
|
Packit Service |
6d40f9 |
easier) you can use
|
|
Packit Service |
6d40f9 |
<ulink url="http://stef.thewalter.net/2012/12/git-coverage-useful-code-coverage.html">
|
|
Packit Service |
6d40f9 |
<literal>git coverage</literal></ulink> to easily check whether
|
|
Packit Service |
6d40f9 |
you've tested the lines changed by a patch.</para>
|
|
Packit Service |
6d40f9 |
</section>
|
|
Packit Service |
6d40f9 |
|
|
Packit Service |
6d40f9 |
<section id="devel-debugging">
|
|
Packit Service |
6d40f9 |
<title>Debugging Tips</title>
|
|
Packit Service |
6d40f9 |
|
|
Packit Service |
6d40f9 |
<para>Unexpected conditions will produce critical warnings by adcli.
|
|
Packit Service |
6d40f9 |
These are often failed internal preconditions, and usually indicate a
|
|
Packit Service |
6d40f9 |
bug either in adcli or the software calling it.</para>
|
|
Packit Service |
6d40f9 |
|
|
Packit Service |
6d40f9 |
<para>You can use the environment variable <literal>ADCLI_STRICT=yes</literal>
|
|
Packit Service |
6d40f9 |
to make adcli do an <literal>abort()</literal> (and core dump depending on
|
|
Packit Service |
6d40f9 |
your configuration) when a critical warning occurs.</para>
|
|
Packit Service |
6d40f9 |
</section>
|
|
Packit Service |
6d40f9 |
</chapter>
|