docs/reference/build-howto.xml

   1 <?xml version="1.0"?>
   2 <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
   3                "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd">
   4 <refentry id="libsoup-build-howto">
   5 <refmeta>
   6 <refentrytitle>Compiling with libsoup</refentrytitle>
   7 <manvolnum>3</manvolnum>
   8 <refmiscinfo>LIBSOUP Library</refmiscinfo>
   9 </refmeta>
  10
  11 <refnamediv>
  12 <refname>Compiling with libsoup</refname><refpurpose>Notes on compiling</refpurpose>
  13 </refnamediv>
  14
  15 <refsect2>
  16 <title>Using pkg-config</title>
  17
  18 <para>
  19 Like other GNOME libraries, <application>libsoup</application> uses
  20 <application>pkg-config</application> to provide compiler options. The
  21 package name is "<literal>libsoup-2.4</literal>". So in your
  22 <literal>configure</literal> script, you might specify something like:
  23 </para>
  24
  25 <informalexample><programlisting>
  26 PKG_CHECK_MODULES(LIBSOUP, [libsoup-2.4 >= 2.26])
  27 AC_SUBST(LIBSOUP_CFLAGS)
  28 AC_SUBST(LIBSOUP_LIBS)
  29 </programlisting></informalexample>
  30
  31 <para>
  32 The "<literal>2.4</literal>" in the package name is the "API version"
  33 (indicating "the version of the <application>libsoup</application> API
  34 that first appeared in version 2.4") and is essentially just part of
  35 the package name.
  36 </para>
  37
  38 <para>
  39 If you are using any of the GNOME-specific features of
  40 <application>libsoup</application> (such as automatic proxy
  41 configuration), you must require
  42 "<literal>libsoup-gnome-2.4</literal>" instead:
  43 </para>
  44
  45 <informalexample><programlisting>
  46 PKG_CHECK_MODULES(LIBSOUP, [libsoup-gnome-2.4 >= 2.26])
  47 AC_SUBST(LIBSOUP_CFLAGS)
  48 AC_SUBST(LIBSOUP_LIBS)
  49 </programlisting></informalexample>
  50
  51 <para>
  52 You can also make <application>libsoup-gnome</application> an optional
  53 dependency:
  54 </para>
  55
  56 <informalexample><programlisting>
  57 PKG_CHECK_MODULES(LIBSOUP_GNOME,
  58                   [libsoup-gnome-2.4 >= 2.26],
  59                   [LIBSOUP_CFLAGS="$LIBSOUP_GNOME_CFLAGS"
  60                    LIBSOUP_LIBS="$LIBSOUP_GNOME_LIBS"
  61                    AC_DEFINE(HAVE_LIBSOUP_GNOME, 1, [Have libsoup-gnome])],
  62                   [PKG_CHECK_MODULES(LIBSOUP, [libsoup-2.4 >= 2.26])])
  63 AC_SUBST(LIBSOUP_CFLAGS)
  64 AC_SUBST(LIBSOUP_LIBS)
  65 </programlisting></informalexample>
  66
  67 <para>
  68 This will allow the application to be built with either plain
  69 <application>libsoup</application> or with
  70 <application>libsoup-gnome</application>, and it will define the C
  71 preprocessor symbol <literal>HAVE_LIBSOUP_GNOME</literal> if
  72 <application>libsoup-gnome</application> features are available.
  73 </para>
  74
  75 </refsect2>
  76
  77 <refsect2>
  78 <title>Headers</title>
  79
  80 <para>
  81 Code using <application>libsoup</application> should do:
  82 </para>
  83
  84 <informalexample><programlisting>
  85 #include &lt;libsoup/soup.h&gt;
  86 </programlisting></informalexample>
  87
  88 <para>
  89 or, for <application>libsoup-gnome</application>:
  90 </para>
  91
  92 <informalexample><programlisting>
  93 #include &lt;libsoup/soup-gnome.h&gt;
  94 </programlisting></informalexample>
  95
  96 <para>
  97 Including individual headers besides the two main header files is not
  98 recommended. You may include both <literal>soup.h</literal> and
  99 <literal>soup-gnome.h</literal> (though this is not required; the
 100 latter automatically includes the former).
 101 </para>
 102
 103 </refsect2>
 104
 105 </refentry>