"http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd">

<chapter id="devel">

	<title>Building, Packaging, and Contributing to adcli</title>

	<section id="devel-links">

		<title>Helpful Resources</title>

		<para>Use the following to find more information about

		contributing to adcli beyond what's in this manual:</para>

		<itemizedlist>

			<listitem><para><ulink url="http://www.freedesktop.org/software/realmd/adcli/">Website</ulink></para></listitem>

			<listitem><para><ulink url="mail:authentication@lists.freedesktop.org">Mailing list</ulink></para></listitem>

			<listitem><para><ulink url="https://bugs.freedesktop.org/enter_bug.cgi?product=realmd&component=adcli">Bugzilla</ulink></para></listitem>

		</itemizedlist>

	</section>

	<section id="devel-building">

		<title>Compiling adcli from Source</title>

		<para>This describes how to compiling the adcli package from

		source code. This is normally only necessary for those wishing to

		contribute to the project or package adcli.</para>

		<para>You can download

		<ulink url="http://www.freedesktop.org/software/realmd/releases/">tarballs

		of the releases</ulink> of adcli or

		<ulink url="http://cgit.freedesktop.org/realmd/adcli/">check

		out the source code from git</ulink>. This documentation will not

		go into all the details of how to get your development environment

		set up and instead focus on the what's unique to compiling adcli.</para>

		<section id="devel-building-dependencies">

			<title>Dependencies</title>

			<para>Besides the default autotools, binutils and GCC, adcli requires the

			following development dependencies to build:</para>

			<itemizedlist>

				<listitem><para>OpenLDAP client libraries</para></listitem>

				<listitem><para>MIT Kerberos libraries</para></listitem>

			</itemizedlist>

			<para>On <emphasis role="strong">Debian</emphasis> or <emphasis role="strong">Ubuntu</emphasis> you can use the following command to

			install the dependencies:</para>

<programlisting>

$ sudo apt-get install build-essential autoconf automake xmlto xsltproc \

         libkrb5-dev libldap2-dev libsasl2-dev

</programlisting>

			<para>On <emphasis role="strong">Fedora</emphasis> you can use the following command to install the

			dependencies:</para>

<programlisting>

$ sudo yum groupinstall "Development Tools"

$ sudo yum install automake autoconf xmlto xsltproc krb5-devel openldap-devel \

    cyrus-sasl-devel

</programlisting>

		</section>

		<section id="devel-building-unix">

			<title>Building on UNIX</title>

			<para>adcli uses the standard GNU build system, using autoconf for package

			configuration and resolving portability issues, automake for building makefiles

			that comply with the GNU Coding Standards, and libtool for building shared

			libraries on multiple platforms. The normal sequence for compiling and

			installing adcli is thus:</para>

<programlisting>

$ ./configure --prefix=/usr --sysconfdir=/etc...

$ make

$ make install

</programlisting>

			<para>If you've checked out the source code from git, then the

			<command>configure</command> script does not yet exist. So use

			the following instead:</para>

<programlisting>

$ ./autogen.sh --prefix=/usr --sysconfdir=/etc ...

$ make

$ make install

</programlisting>

			<para>The standard options provided by GNU autoconf may be passed to the configure

			script. Please see the autoconf documentation or run <literal>./configure --help</literal>

			for information about the standard options. In particular you probably want to adjust

			the <literal>--prefix=/xxx</literal> argument depending on your system and development

			environment.</para>

			<para>Make sure that the <literal>--sysconfdir=/etc</literal> matches the directory

			where the the MIT kerberos library stores its <literal>krb5.conf</literal>. This is

			usually <literal>/etc</literal></para>

		</section>

		<section id="devel-building-configure">

			<title>Extra Configuration Options</title>

			<para>In addition to the normal options, the configure script in the adcli

			supports these additional arguments:</para>

			<variablelist>

				<varlistentry>

					<term><option>--disable-debug</option>, <option>--enable-debug</option></term>

					<listitem><para>By default adcli is built with debug symbols assertions and

					and precondition checks. Enabling the debug option configures even more

					detailed debug build, including disabling optimization. Disabling the debug

					option is not recommended, as it disables all assertions, preconditions and

					internal consistency checks, although it may result it a slightly faster

					library.</para></listitem>

				</varlistentry>

				<varlistentry>

					<term><option>--disable-doc</option></term>

					<listitem><para>Disables building of the documentation and command line manual.

					The documentation is built in the <literal>doc/html/</literal> directory of

					the build.</para></listitem>

				</varlistentry>

				<varlistentry>

					<term><option>--enable-strict</option></term>

					<listitem><para>Enables strict checks during building of adcli. All

					compiler warnings become errors.</para></listitem>

				</varlistentry>

			</variablelist>

			<para></para>

		</section>

	</section>

	<section id="devel-building-style">

		<title>Coding Style</title>

		<para>We use a code style similar to the linux kernel. Use tabs

		to indent and spaces to align/wrap beyond the indentation level.</para>

		<para>We don't try to guarantee completely robust and problem free

		behavior in cases where the caller or system isn't behaving. We

		consider these to be outside of our control:</para>

		<itemizedlist>

			<listitem><para>Broken input from callers. We use preconditions

			to check input and immediately return. We don't try to provide

			error codes for all the various ways callers can screw

			around.</para></listitem>

			<listitem>

			<para>Out of memory. It is pretty much impossible to handle out

			of memory errors correctly. Handling them alongside other errors

			is naive and broken. We don't try to guarantee library state

			(such as locks or memory leaks) when memory allocation fails.</para>

			<para>We do check the results from all memory allocations, but

			treat them as unexpected conditions. As a nod to the behavior

			of callers of this library, we don't abort on memory allocation

			failures. We use preconditions with somewhat sane results.</para>

			<para>Exception: when reading files or allocating potentially

			unbounded amounts of memory, we should respond robustly to memory

			allocation failures.</para>

			</listitem>

		</itemizedlist>

		<para>These unexpected conditions indicate a bug either in adcli or

		in the system. All bets are off once this occurs.</para>

		<para>Use the <literal>return_val_xxx()</literal> precondition macros to

		check for unexpected conditions.</para>

	</section>

	<section id="devel-testing">

		<title>Testing and Code Coverage</title>

		<para>Low level input parsers and such code should have unit tests

		excercizing it. Use the <literal>make check</literal> command to run all

		the tests. If you run it from a subdirectory only the tests in that

		directory will be run.</para>

		<para>To check for memory errors or memory leaks, run <literal>make memcheck</literal>

		or <literal>make leakcheck</literal> respectively. This requires valgrind

		be installed.</para>

		<para>Build adcli with the <option>--enable-coverage</option> configure

		option to build code coverage support.</para>

		<para>Once you've done that you can either use <literal>make coverage</literal>

		to build code coverage information. Alternatively (and this is usually

		easier) you can use

		<ulink url="http://stef.thewalter.net/2012/12/git-coverage-useful-code-coverage.html">

			<literal>git coverage</literal></ulink> to easily check whether

		you've tested the lines changed by a patch.</para>

	</section>

	<section id="devel-debugging">

		<title>Debugging Tips</title>

		<para>Unexpected conditions will produce critical warnings by adcli.

		These are often failed internal preconditions, and usually indicate a

		bug either in adcli or the software calling it.</para>

		<para>You can use the environment variable <literal>ADCLI_STRICT=yes</literal>

		to make adcli do an <literal>abort()</literal> (and core dump depending on

		your configuration) when a critical warning occurs.</para>

	</section>

</chapter>