blob: b54697f4eb54604ef9057d32d7446a1db85b0371 (
plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
|
<?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 <libsoup/soup.h>
</programlisting></informalexample>
</sect3>
</sect1>
|
