diff options
Diffstat (limited to 'docs/api/chapters/compiling-and-linking.sgml')
| -rw-r--r-- | docs/api/chapters/compiling-and-linking.sgml | 252 |
1 files changed, 252 insertions, 0 deletions
diff --git a/docs/api/chapters/compiling-and-linking.sgml b/docs/api/chapters/compiling-and-linking.sgml new file mode 100644 index 00000000..f184c6a4 --- /dev/null +++ b/docs/api/chapters/compiling-and-linking.sgml @@ -0,0 +1,252 @@ +<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> |