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> 19Like other GNOME libraries, <application>libsoup</application> uses 20<application>pkg-config</application> to provide compiler options. The 21package 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> 26PKG_CHECK_MODULES(LIBSOUP, [libsoup-2.4 >= 2.26]) 27AC_SUBST(LIBSOUP_CFLAGS) 28AC_SUBST(LIBSOUP_LIBS) 29</programlisting></informalexample> 30 31<para> 32The "<literal>2.4</literal>" in the package name is the "API version" 33(indicating "the version of the <application>libsoup</application> API 34that first appeared in version 2.4") and is essentially just part of 35the package name. 36</para> 37 38</refsect2> 39 40<refsect2> 41<title>API Availability and Deprecation Warnings</title> 42 43<para> 44If you want to restrict your program to a particular 45<application>libsoup</application> version or range of versions, you 46can define <link 47linkend="SOUP-VERSION-MIN-REQUIRED:CAPS"><literal>SOUP_VERSION_MIN_REQUIRED</literal></link> 48and/or <link 49linkend="SOUP-VERSION-MAX-ALLOWED:CAPS"><literal>SOUP_VERSION_MAX_ALLOWED</literal></link>. 50Eg: 51</para> 52 53<informalexample><programlisting> 54LIBSOUP_CFLAGS="$LIBSOUP_CFLAGS -DSOUP_VERSION_MIN_REQUIRED=SOUP_VERSION_2_36" 55LIBSOUP_CFLAGS="$LIBSOUP_CFLAGS -DSOUP_VERSION_MAX_ALLOWED=SOUP_VERSION_2_40" 56</programlisting></informalexample> 57 58<para> 59The <literal>SOUP_VERSION_MIN_REQUIRED</literal> declaration states 60that the code is not expected to compile on versions of 61<application>libsoup</application> older than the indicated version 62(here, 2.36), and so the compiler should print warnings if the code 63uses functions that were deprecated as of that release. 64</para> 65 66<para> 67The <literal>SOUP_VERSION_MAX_ALLOWED</literal> declaration states 68that the code <emphasis>is</emphasis> expected to compile on versions 69of <application>libsoup</application> up to the indicated version 70(here, 2.40), and so, when compiling the program against a newer 71version than that, the compiler should print warnings if the code uses 72functions that did not yet exist in the max-allowed release. 73</para> 74 75<para> 76You can use <link 77linkend="SOUP-CHECK-VERSION:CAPS"><literal>SOUP_CHECK_VERSION</literal></link> 78to check the version of libsoup at compile time, to compile different 79code for different <application>libsoup</application> versions. (If 80you are setting <literal>SOUP_VERSION_MIN_REQUIRED</literal> and 81<literal>SOUP_VERSION_MAX_ALLOWED</literal> to different versions, as 82in the example above, then you almost certainly need to be doing 83this.) 84</para> 85 86</refsect2> 87 88<refsect2> 89<title>Headers</title> 90 91<para> 92Code using <application>libsoup</application> should do: 93</para> 94 95<informalexample><programlisting> 96#include <libsoup/soup.h> 97</programlisting></informalexample> 98 99<para> 100Including individual headers rather than <literal>soup.h</literal> is not 101recommended. 102</para> 103 104</refsect2> 105 106</refentry> 107