<?xml version="1.0" encoding="UTF-8"?>
<?xml-model href="http://docbook.org/xml/5.1/rng/docbook.rng" schematypens="http://relaxng.org/ns/structure/1.0"?>
<?xml-model href="http://docbook.org/xml/5.1/sch/docbook.sch" type="application/xml" schematypens="http://purl.oclc.org/dsdl/schematron"?>
<sect1 xmlns="http://docbook.org/ns/docbook" 
    xmlns:xlink="http://www.w3.org/1999/xlink" version="5.1">
    <title>Building with libsoup</title>
    <sect3>
      <title>Buildsystem Integration</title>
    <para>Like other GNOME libraries, <application>libsoup</application> uses
            <application>pkg-config</application> to provide compiler options. The package name is
            "<literal>libsoup-3.0</literal>". </para>
    <para>For example if you use Autotools:<informalexample>
    <programlisting>PKG_CHECK_MODULES(LIBSOUP, [libsoup-3.0])
AC_SUBST(LIBSOUP_CFLAGS)
AC_SUBST(LIBSOUP_LIBS)</programlisting>
        </informalexample></para>
    <para>If you use Meson: <informalexample>
            <programlisting>libsoup_dep = dependency('libsoup-3.0')</programlisting>
        </informalexample></para>
    </sect3>

    <sect3>
      <title>API Availability and Deprecation Warnings</title>
<para>
If you want to restrict your program to a particular
<application>libsoup</application> version or range of versions, you
can define <link
linkend="SOUP-VERSION-MIN-REQUIRED:CAPS"><literal>SOUP_VERSION_MIN_REQUIRED</literal></link>
and/or <link
linkend="SOUP-VERSION-MAX-ALLOWED:CAPS"><literal>SOUP_VERSION_MAX_ALLOWED</literal></link>.
For example with Autotools:
</para>

<informalexample><programlisting>LIBSOUP_CFLAGS="$LIBSOUP_CFLAGS -DSOUP_VERSION_MIN_REQUIRED=SOUP_VERSION_3_0"
LIBSOUP_CFLAGS="$LIBSOUP_CFLAGS -DSOUP_VERSION_MAX_ALLOWED=SOUP_VERSION_3_2"</programlisting></informalexample>

  <para>Or with Meson:</para>

  <informalexample><programlisting>add_project_arguments(
  '-DSOUP_VERSION_MIN_REQUIRED=SOUP_VERSION_2_99',
  '-DSOUP_VERSION_MAX_ALLOWED=SOUP_VERSION_3_0',
  language: 'c'
)</programlisting></informalexample>
  
<para>The <literal>SOUP_VERSION_MIN_REQUIRED</literal> declaration states that the code is not
        expected to compile on versions of <application>libsoup</application> older than the
        indicated version, and so the compiler should print warnings if the code uses
        functions that were deprecated as of that release.</para>

<para>The <literal>SOUP_VERSION_MAX_ALLOWED</literal> declaration states that the code
            <emphasis>is</emphasis> expected to compile on versions of
            <application>libsoup</application> up to the indicated version, and so, when
        compiling the program against a newer version than that, the compiler should print warnings
        if the code uses functions that did not yet exist in the max-allowed release.</para>

<para>You can use <link linkend="SOUP-CHECK-VERSION:CAPS"><literal>SOUP_CHECK_VERSION</literal></link> to check the version of libsoup at compile
        time, to compile different code for different <application>libsoup</application> versions.
        (If you are setting <literal>SOUP_VERSION_MIN_REQUIRED</literal> and
            <literal>SOUP_VERSION_MAX_ALLOWED</literal> to different versions, as in the example
        above, then you almost certainly need to be doing this.)</para>
  </sect3>
  <sect3>
    <title>Headers</title>

    <para>Code using <application>libsoup</application> should include the header like so:</para>
<informalexample><programlisting>
#include &lt;libsoup/soup.h&gt;
</programlisting></informalexample>
  </sect3>
</sect1>
