Added a chapter for sources preparation. Based on the documenation of libksba.

5 files changed, 82 insertions, 4 deletions

diff --git a/doc/tex/Makefile.am b/doc/tex/Makefile.am
index 62fcb6ac38..4cf7322bee 100644
--- a/doc/tex/Makefile.am
+++ b/doc/tex/Makefile.am
@@ -17,7 +17,7 @@ TEX_OBJECTS = gnutls.tex ../../lib/gnutls-api.tex fdl.tex \
 	appendix.tex x509cert.xml.tex pgpcert.xml.tex \
 	programs.tex library.tex certificate.tex record_weaknesses.tex \
 	tlsintro.tex compression.tex $(EXAMPLE_OBJECTS) \
-	tls_extensions.tex srp.tex
+	tls_extensions.tex srp.tex preparation.tex
 
 gnutls.html: $(TEX_OBJECTS)            
 	-latex2html gnutls.tex -no_navigation -split 0 \
diff --git a/doc/tex/ex-pgp-keyserver.tex b/doc/tex/ex-pgp-keyserver.tex
index c5eaca1ef3..2c613fd7e5 100644
--- a/doc/tex/ex-pgp-keyserver.tex
+++ b/doc/tex/ex-pgp-keyserver.tex
@@ -27,7 +27,6 @@ recv_openpgp_key(gnutls_session session, const unsigned char *keyfpr,
 {
    int rc;
    CDK_KBNODE knode = NULL;
-   unsigned char* buf = NULL;
 
    /* The key fingerprint should be 20 bytes
     * in v4 keys.
@@ -59,7 +58,6 @@ recv_openpgp_key(gnutls_session session, const unsigned char *keyfpr,
 
    finish:
 
-   cdk_free( buf );
    cdk_kbnode_release( knode );
    return rc;
 
diff --git a/doc/tex/examples.tex b/doc/tex/examples.tex
index 17f0462aeb..4adbdbe254 100644
--- a/doc/tex/examples.tex
+++ b/doc/tex/examples.tex
@@ -1,6 +1,8 @@
 \chapter{How to use GNUTLS\index{Example programs} in applications}
-\label{examples}
 
+\input{preparation}
+
+\label{examples}
 \section{Client examples}
 This section contains examples of \tls{} and \ssl{} clients, using \gnutls{}. 
 Note that these examples contain little or no error checking.
diff --git a/doc/tex/macros.tex b/doc/tex/macros.tex
index ece5cac1f4..060f4dfe26 100644
--- a/doc/tex/macros.tex
+++ b/doc/tex/macros.tex
@@ -7,6 +7,13 @@
 \newcommand{\ssl}{{\emph{SSL}}} 
 \newcommand{\HRule}{\rule{\linewidth}{0.4mm}}
 
+\newcommand{\option}[1]{%
+	{\tt{#1}}
+}
+
+\newcommand{\command}[1]{%
+	``{\tt{#1}}''
+}
 
 % accepts section name, function name
 \newcommand{\printfunc}[2]{%
diff --git a/doc/tex/preparation.tex b/doc/tex/preparation.tex
new file mode 100644
index 0000000000..6d2a66fc31
--- /dev/null
+++ b/doc/tex/preparation.tex
@@ -0,0 +1,71 @@
+%\section{Preparation\footnote{This section is heavily based on the `libksba' documentation}}
+\section{Preparation}
+
+To use \gnutls{}, you have to perform some changes to your sources and
+your build system. The necessary changes are explained in the following
+subsections.
+
+\subsection{Headers}
+
+All the data types and functions of the \gnutls{} library are defined in
+the header file `gnutls/gnutls.h'. This must be included in all programs that
+make use of the \gnutls{} library.
+\par
+The extra functionality of the \gnutlse{} library is available by
+including the header file `gnutls/extra.h' in your programs.
+
+\subsection{Version check}
+It is often desirable to check that the version of `gnutls' used is indeed
+one which fits all requirements.  Even with binary compatibility new
+features may have been introduced but due to problem with the dynamic
+linker an old version is actually used.  So you may want to check that
+the version is okay right after program startup.
+See the function \printfunc{gnutls_check_version}{gnutls\_check\_version}
+
+
+\subsection{Building the source}
+
+If you want to compile a source file including the `gnutls/gnutls.h' header
+file, you must make sure that the compiler can find it in the
+directory hierarchy.  This is accomplished by adding the path to the
+directory in which the header file is located to the compilers include
+file search path (via the -I option).
+
+However, the path to the include file is determined at the time the
+source is configured.  To solve this problem, \gnutls{} ships with two small
+helper programs \command{libgnutls-config} and \command{libgnutls-extra-config}
+that knows about the path to the
+include file and other configuration options.  The options that need
+to be added to the compiler invocation at compile time are output by
+the \option{--cflags} option to \option{libgnutls-config}.  The following
+example shows how it can be used at the command line:
+
+\begin{verbatim}
+gcc -c foo.c `libgnutls-config --cflags`
+\end{verbatim}
+
+Adding the output of \command{libgnutls-config --cflags} to the compilers
+command line will ensure that the compiler can find the \gnutls{} header
+file.
+
+A similar problem occurs when linking the program with the library.
+Again, the compiler has to find the library files.  For this to work,
+the path to the library files has to be added to the library search
+path (via the -L option).  For this, the option
+\option{--libs} to \command{libgnutls-config} can be used.  For
+convenience, this option also outputs all other options that are
+required to link the program with the \gnutls{} libararies.
+The example shows how to link `foo.o'
+with the \gnutls{} libraries to a program \emph{foo}.
+
+\begin{verbatim}
+gcc -o foo foo.o `libgnutls-config --libs`
+\end{verbatim}
+
+Of course you can also combine both examples to a single command by
+specifying both options to `libgnutls-config':
+
+\begin{verbatim}
+gcc -o foo foo.c `libgnutls-config --cflags --libs`
+\end{verbatim}
+