<chapter id="xmlsec-notes-compiling">
    <title>Building the application with XML Security Library.</title>
    <sect1 id="xmlsec-notes-compiling-overview">
        <title>Overview.</title>
        <para>Compiling and linking application with XML Security
	Library requires specifying correct compilation flags, library files 
        and paths to include and library files. As we discussed before, 
	XML Security Library consist of the core xmlsec library and several 
	xmlsec-crypto libraries. Application has a choice of selecting crypto 
	library at link time or dynamicaly loading it at run time. Please note,
	that loading crypto engines dynamicaly may introduce security problems
	on some platforms. 
	</para>
    </sect1>
    <sect1 id="xmlsec-notes-include-files" >
	<title>Include files.</title>
	<para>In order to use XML Security Library an application should include 
	one or more of the following files:
	<itemizedlist>
	    <listitem>
		<para><link linkend="XMLSEC-XMLSEC">xmlsec/xmlsec.h</link> -
		XML Security Library initialization and shutdown functions;
		</para>
	    </listitem>
	    <listitem>
		<para><link linkend="XMLSEC-XMLDSIG">xmlsec/xmldsig.h</link> - 
		XML Digital Signature functions;</para>
	    </listitem>
	    <listitem>
		<para><link linkend="XMLSEC-XMLENC">xmlsec/xmlenc.h</link> - 
		XML Encryption functions;</para>
	    </listitem>
	    <listitem>
		<para><link linkend="XMLSEC-XMLTREE">xmlsec/xmltree.h</link> -
		helper functions for XML documents manipulation;
		</para>
	    </listitem>
	    <listitem>
		<para><link linkend="XMLSEC-TEMPLATES">xmlsec/templates.h</link> -
		helper functions for dynamic XML Digital Signature and 
		XML Encryption templates creation;
		</para>
	    </listitem>
	    <listitem>
		<para><link linkend="XMLSEC-CRYPTO">xmlsec/crypto.h</link> -
		automatic XML Security Crypto Library selection.
		</para>
	    </listitem>
	</itemizedlist>
	</para>
	<para>If necessary, the application should also include LibXML, 
	LibXSLT and crypto library header files.
	</para>
	<para>
	<example>
	    <title>Example includes file section.</title>
	    <programlisting><![CDATA[
#include <libxml/tree.h>
#include <libxml/xmlmemory.h>
#include <libxml/parser.h>

#ifndef XMLSEC_NO_XSLT
#include <libxslt/xslt.h>
#endif /* XMLSEC_NO_XSLT */

#include <xmlsec/xmlsec.h>
#include <xmlsec/xmltree.h>
#include <xmlsec/xmldsig.h>
#include <xmlsec/xmlenc.h>
#include <xmlsec/templates.h>
#include <xmlsec/crypto.h>
	    ]]></programlisting>
	</example>
	</para>
    </sect1>
    <sect1 id="xmlsec-notes-compiling-unix" >
	<title>Compiling and linking on Unix.</title>
	<para>There are several ways to get necessary compilation
	and linking information on Unix and application can use
	any of these methods to do crypto engine selection either
	at linking or run time.
	
	<itemizedlist>
	    <listitem><para>PKG_CHECK_MODULES() macro
		<example>
		    <title>Using PKG_CHECK_MODULES() macro in a configure.in file
		    to select crypto engine (openssl) at linking time.</title>
		    <programlisting><![CDATA[
dnl 
dnl Check for xmlsec and friends
dnl
PKG_CHECK_MODULES(XMLSEC, xmlsec1-openssl >= 1.0.0 xml2 libxslt,,exit)
CFLAGS="$CFLAGS $XMLSEC_CFLAGS"
CPPFLAGS="$CPPFLAGS $XMLSEC_CFLAGS"
LDFLAGS="$LDFLAGS $XMLSEC_LIBS"
		    ]]></programlisting>
		</example>

		<example>
		    <title>Using PKG_CHECK_MODULES() macro in a configure.in file
		    to enable dynamical loading of xmlsec-crypto library.</title>
		    <programlisting><![CDATA[
dnl 
dnl Check for xmlsec and friends
dnl
PKG_CHECK_MODULES(XMLSEC, xmlsec1 >= 1.0.0 xml2 libxslt,,exit)
CFLAGS="$CFLAGS $XMLSEC_CFLAGS"
CPPFLAGS="$CPPFLAGS $XMLSEC_CFLAGS"
LDFLAGS="$LDFLAGS $XMLSEC_LIBS"
		    ]]></programlisting>
		</example>

	    </para></listitem>


	    <listitem><para>pkg-config script
		<example>
		    <title>Using pkg-config script in a Makefile
		    to select crypto engine (nss) at linking time.</title>
		    <programlisting><![CDATA[
PROGRAM = test
PROGRAM_FILES = test.c

CFLAGS	+= -g $(shell pkg-config --cflags xmlsec1-nss)
LDFLAGS	+= -g
LIBS 	+= $(shell pkg-config --libs xmlsec1-nss) 

all: $(PROGRAM)

%: %.c 
	$(cc) $(PROGRAM_FILES) $(CFLAGS) $(LDFLAGS) -o $(PROGRAM) $(LIBS)

clean:
	@rm -rf $(PROGRAM)
		    ]]></programlisting>
		</example>


		<example>
		    <title>Using pkg-config script in a Makefile
		    to enable dynamical loading of xmlsec-crypto library.</title>
		    <programlisting><![CDATA[
PROGRAM = test
PROGRAM_FILES = test.c

CFLAGS	+= -g $(shell pkg-config --cflags xmlsec1)
LDFLAGS	+= -g
LIBS 	+= $(shell pkg-config --libs xmlsec1) 

all: $(PROGRAM)

%: %.c 
	$(cc) $(PROGRAM_FILES) $(CFLAGS) $(LDFLAGS) -o $(PROGRAM) $(LIBS)

clean:
	@rm -rf $(PROGRAM)
		    ]]></programlisting>
		</example>

	    </para></listitem>
	    <listitem><para>xmlsec1-config script
		<example>
		    <title>Using xmlsec1-config script in a Makefile
		    to select crypto engine (e.g. gnutls) at linking time.</title>
		    <programlisting><![CDATA[
PROGRAM = test
PROGRAM_FILES = test.c

CFLAGS	+= -g $(shell xmlsec1-config --crypto gnutls --cflags)
LDFLAGS	+= -g
LIBS 	+= $(shell xmlsec1-config --crypto gnutls --libs) 

all: $(PROGRAM)

%: %.c 
	$(cc) $(PROGRAM_FILES) $(CFLAGS) $(LDFLAGS) -o $(PROGRAM) $(LIBS)

clean:
	@rm -rf $(PROGRAM)
		    ]]></programlisting>
		</example>

		<example>
		    <title>Using xmlsec1-config script in a Makefile
		    to enable dynamical loading of xmlsec-crypto library.</title>
		    <programlisting><![CDATA[
PROGRAM = test
PROGRAM_FILES = test.c

CFLAGS	+= -g $(shell xmlsec1-config --cflags)
LDFLAGS	+= -g
LIBS 	+= $(shell xmlsec1-config --libs) 

all: $(PROGRAM)

%: %.c 
	$(cc) $(PROGRAM_FILES) $(CFLAGS) $(LDFLAGS) -o $(PROGRAM) $(LIBS)

clean:
	@rm -rf $(PROGRAM)
		    ]]></programlisting>
		</example>
		</para></listitem>
	</itemizedlist>
	</para>
    </sect1>
    <sect1 id="xmlsec-notes-compiling-windows" >
	<title>Compiling and linking on Windows.</title>
	<para>On Windows there is no such simple and elegant solution.
	Please check <filename>README</filename> file in <filename>win32</filename>
	folder of the library package for latest instructions.
	However, there are few general things, that you need to remember:
	<itemizedlist>
	    <listitem><para>	
	     <emphasis>All libraries linked to your application must be compiled
	    with the same Microsoft Runtime Libraries.</emphasis>
	    </para></listitem>
	    <listitem><para>	
	     <emphasis>Static linking with XML Security Library requires 
	     additional global defines:</emphasis>
	      <informalexample><programlisting>
#define LIBXML_STATIC
#define LIBXSLT_STATIC
#define XMLSEC_STATIC	    
	     </programlisting></informalexample>
	    </para></listitem>
	    <listitem><para>
	    If you do not want to dynamicaly load xmlsec-crypto library
	    and prefer to select crypto engine at linking then you should
	    link your application with xmlsec and at least one of 
	    xmlsec-crypto libraries.
	    </para></listitem>
	    <listitem><para>
	    In order to enable dynamic loading for xmlsec-crypto library
	    you should add additional global define:
	      <informalexample><programlisting>
#define XMLSEC_CRYPTO_DYNAMIC_LOADING
	     </programlisting></informalexample>	    
	    </para></listitem>
	</itemizedlist>
	</para>
    </sect1>
    <sect1 id="xmlsec-notes-compiling-others">
	<title>Compiling and linking on other systems.</title>
	<para>Well, nothing is impossible, it's only software (you managed to 
	compile the library itself, do you?). 
	I'll be happy to include in this manual your expirience with
	compiling and linking applications with XML Security Library
	on other platforms (if you would like to share it).
	</para>
    </sect1>
</chapter>
