more doc additions
This commit is contained in:
parent
20a239149f
commit
5d8ba8b28f
|
@ -2,549 +2,23 @@
|
||||||
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
|
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
|
||||||
"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
|
"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
|
||||||
]>
|
]>
|
||||||
<refentry id="glib-building">
|
<refentry id="binding">
|
||||||
<refmeta>
|
<refmeta>
|
||||||
<refentrytitle>Compiling the GLib package</refentrytitle>
|
<refentrytitle>Writing bindings for libvips</refentrytitle>
|
||||||
<manvolnum>3</manvolnum>
|
<manvolnum>3</manvolnum>
|
||||||
<refmiscinfo>GLib Library</refmiscinfo>
|
<refmiscinfo>VIPS Library</refmiscinfo>
|
||||||
</refmeta>
|
</refmeta>
|
||||||
|
|
||||||
<refnamediv>
|
<refnamediv>
|
||||||
<refname>Compiling the GLib Package</refname>
|
<refname>Binding</refname>
|
||||||
<refpurpose>How to compile GLib itself</refpurpose>
|
<refpurpose>How to write bindings for libvips</refpurpose>
|
||||||
</refnamediv>
|
</refnamediv>
|
||||||
|
|
||||||
<refsect1 id="building">
|
<refsect1 id="binding-goi">
|
||||||
<title>Building the Library on UNIX</title>
|
<title>Binding and gobject-introspection</title>
|
||||||
<para>
|
<para>
|
||||||
On UNIX, GLib uses the standard GNU build system,
|
Stuff about goi.
|
||||||
using <application>autoconf</application> for package
|
|
||||||
configuration and resolving portability issues,
|
|
||||||
<application>automake</application> for building makefiles
|
|
||||||
that comply with the GNU Coding Standards, and
|
|
||||||
<application>libtool</application> for building shared
|
|
||||||
libraries on multiple platforms. The normal sequence for
|
|
||||||
compiling and installing the GLib library is thus:
|
|
||||||
|
|
||||||
<literallayout>
|
|
||||||
<userinput>./configure</userinput>
|
|
||||||
<userinput>make</userinput>
|
|
||||||
<userinput>make install</userinput>
|
|
||||||
</literallayout>
|
|
||||||
</para>
|
</para>
|
||||||
|
|
||||||
<para>
|
|
||||||
The standard options provided by <application>GNU
|
|
||||||
autoconf</application> may be passed to the
|
|
||||||
<command>configure</command> script. Please see the
|
|
||||||
<application>autoconf</application> documentation or run
|
|
||||||
<command>./configure --help</command> for information about
|
|
||||||
the standard options.
|
|
||||||
</para>
|
|
||||||
<para>
|
|
||||||
The GTK+ documentation contains
|
|
||||||
<ulink url="../gtk/gtk-building.html">further details</ulink>
|
|
||||||
about the build process and ways to influence it.
|
|
||||||
</para>
|
|
||||||
</refsect1>
|
|
||||||
<refsect1 id="dependencies">
|
|
||||||
<title>Dependencies</title>
|
|
||||||
<para>
|
|
||||||
Before you can compile the GLib library, you need to have
|
|
||||||
various other tools and libraries installed on your system.
|
|
||||||
Beyond a C compiler (which must implement C90, but does not need
|
|
||||||
to implement C99), the two tools needed during the build process
|
|
||||||
(as differentiated from the tools used in when creating GLib
|
|
||||||
mentioned above such as <application>autoconf</application>) are
|
|
||||||
<command>pkg-config</command> and GNU make.
|
|
||||||
</para>
|
|
||||||
<itemizedlist>
|
|
||||||
<listitem>
|
|
||||||
<para>
|
|
||||||
<ulink url="http://www.freedesktop.org/software/pkgconfig/">pkg-config</ulink>
|
|
||||||
is a tool for tracking the compilation flags needed for
|
|
||||||
libraries that are used by the GLib library. (For each
|
|
||||||
library, a small <literal>.pc</literal> text file is
|
|
||||||
installed in a standard location that contains the compilation
|
|
||||||
flags needed for that library along with version number
|
|
||||||
information.) The version of <command>pkg-config</command>
|
|
||||||
needed to build GLib is mirrored in the
|
|
||||||
<filename>dependencies</filename> directory
|
|
||||||
on the <ulink url="ftp://ftp.gtk.org/pub/gtk/v2.2/">GTK+ FTP
|
|
||||||
site.</ulink>
|
|
||||||
</para>
|
|
||||||
</listitem>
|
|
||||||
<listitem>
|
|
||||||
<para>
|
|
||||||
The GLib Makefiles make use of several features specific to
|
|
||||||
<ulink url="http://www.gnu.org/software/make">GNU
|
|
||||||
make</ulink>, and will not build correctly with other
|
|
||||||
versions of <command>make</command>. You will need to
|
|
||||||
install it if you don't already have it on your system. (It
|
|
||||||
may be called <command>gmake</command> rather than
|
|
||||||
<command>make</command>.)
|
|
||||||
</para>
|
|
||||||
</listitem>
|
|
||||||
</itemizedlist>
|
|
||||||
<para>
|
|
||||||
A UNIX build of GLib requires that the system implements at
|
|
||||||
least the original 1990 version of POSIX. Beyond this, it
|
|
||||||
depends on a number of other libraries.
|
|
||||||
</para>
|
|
||||||
<itemizedlist>
|
|
||||||
<listitem>
|
|
||||||
<para>
|
|
||||||
The <ulink url="http://www.gnu.org/software/libiconv/">GNU
|
|
||||||
libiconv library</ulink> is needed to build GLib if your
|
|
||||||
system doesn't have the <function>iconv()</function>
|
|
||||||
function for doing conversion between character
|
|
||||||
encodings. Most modern systems should have
|
|
||||||
<function>iconv()</function>, however many older systems lack
|
|
||||||
an <function>iconv()</function> implementation. On such systems,
|
|
||||||
you must install the libiconv library. This can be found at:
|
|
||||||
<ulink url="http://www.gnu.org/software/libiconv">http://www.gnu.org/software/libiconv</ulink>.
|
|
||||||
</para>
|
|
||||||
<para>
|
|
||||||
If your system has an <function>iconv()</function> implementation but
|
|
||||||
you want to use libiconv instead, you can pass the
|
|
||||||
--with-libiconv option to configure. This forces
|
|
||||||
libiconv to be used.
|
|
||||||
</para>
|
|
||||||
<para>
|
|
||||||
Note that if you have libiconv installed in your default include
|
|
||||||
search path (for instance, in <filename>/usr/local/</filename>), but
|
|
||||||
don't enable it, you will get an error while compiling GLib because
|
|
||||||
the <filename>iconv.h</filename> that libiconv installs hides the
|
|
||||||
system iconv.
|
|
||||||
</para>
|
|
||||||
<para>
|
|
||||||
If you are using the native iconv implementation on Solaris
|
|
||||||
instead of libiconv, you'll need to make sure that you have
|
|
||||||
the converters between locale encodings and UTF-8 installed.
|
|
||||||
At a minimum you'll need the SUNWuiu8 package. You probably
|
|
||||||
should also install the SUNWciu8, SUNWhiu8, SUNWjiu8, and
|
|
||||||
SUNWkiu8 packages.
|
|
||||||
</para>
|
|
||||||
<para>
|
|
||||||
The native iconv on Compaq Tru64 doesn't contain support for
|
|
||||||
UTF-8, so you'll need to use GNU libiconv instead. (When
|
|
||||||
using GNU libiconv for GLib, you'll need to use GNU libiconv
|
|
||||||
for GNU gettext as well.) This probably applies to related
|
|
||||||
operating systems as well.
|
|
||||||
</para>
|
|
||||||
</listitem>
|
|
||||||
<listitem>
|
|
||||||
<para>
|
|
||||||
The libintl library from the <ulink
|
|
||||||
url="http://www.gnu.org/software/gettext">GNU gettext
|
|
||||||
package</ulink> is needed if your system doesn't have the
|
|
||||||
<function>gettext()</function> functionality for handling
|
|
||||||
message translation databases.
|
|
||||||
</para>
|
|
||||||
</listitem>
|
|
||||||
<listitem>
|
|
||||||
<para>
|
|
||||||
A thread implementation is needed. The thread support in GLib
|
|
||||||
can be based upon POSIX threads or win32 threads.
|
|
||||||
</para>
|
|
||||||
</listitem>
|
|
||||||
<listitem>
|
|
||||||
<para>
|
|
||||||
GRegex uses the <ulink url="http://www.pcre.org/">PCRE library</ulink>
|
|
||||||
for regular expression matching. The default is to use the internal
|
|
||||||
version of PCRE that is patched to use GLib for memory management
|
|
||||||
and Unicode handling. If you prefer to use the system-supplied PCRE
|
|
||||||
library you can pass the <option>--with-pcre=system</option> option
|
|
||||||
to, but it is not recommended.
|
|
||||||
</para>
|
|
||||||
</listitem>
|
|
||||||
<listitem>
|
|
||||||
<para>
|
|
||||||
The optional extended attribute support in GIO requires the
|
|
||||||
getxattr() family of functions that may be provided by glibc or
|
|
||||||
by the standalone libattr library. To build GLib without extended
|
|
||||||
attribute support, use the <option>--disable-xattr</option>
|
|
||||||
option.
|
|
||||||
</para>
|
|
||||||
</listitem>
|
|
||||||
<listitem>
|
|
||||||
<para>
|
|
||||||
The optional SELinux support in GIO requires libselinux.
|
|
||||||
To build GLib without SELinux support, use the
|
|
||||||
<option>--disable-selinux</option> option.
|
|
||||||
</para>
|
|
||||||
</listitem>
|
|
||||||
<listitem>
|
|
||||||
<para>
|
|
||||||
The optional support for DTrace requires the
|
|
||||||
<filename>sys/sdt.h</filename> header, which is provided
|
|
||||||
by SystemTap on Linux. To build GLib without DTrace, use
|
|
||||||
the <option>--disable-dtrace</option> configure option.
|
|
||||||
</para>
|
|
||||||
</listitem>
|
|
||||||
<listitem>
|
|
||||||
<para>
|
|
||||||
The optional support for
|
|
||||||
<ulink url="http://sourceware.org/systemtap/">SystemTap</ulink>
|
|
||||||
can be disabled with the <option>--disable-systemtap</option>
|
|
||||||
configure option.
|
|
||||||
</para>
|
|
||||||
</listitem>
|
|
||||||
</itemizedlist>
|
|
||||||
|
|
||||||
</refsect1>
|
|
||||||
<refsect1 id="extra-configuration-options">
|
|
||||||
<title>Extra Configuration Options</title>
|
|
||||||
|
|
||||||
<para>
|
|
||||||
In addition to the normal options, the
|
|
||||||
<command>configure</command> script in the GLib
|
|
||||||
library supports these additional arguments:
|
|
||||||
</para>
|
|
||||||
|
|
||||||
<formalpara>
|
|
||||||
<title><systemitem>--enable-debug</systemitem></title>
|
|
||||||
|
|
||||||
<para>
|
|
||||||
Turns on various amounts of debugging support. Setting this to 'no'
|
|
||||||
disables g_assert(), g_return_if_fail(), g_return_val_if_fail() and
|
|
||||||
all cast checks between different object types. Setting it to 'minimum' disables only cast checks. Setting it to 'yes' enables
|
|
||||||
<link linkend="G-DEBUG:CAPS">runtime debugging</link>.
|
|
||||||
The default is 'minimum'.
|
|
||||||
Note that 'no' is fast, but dangerous as it tends to destabilize
|
|
||||||
even mostly bug-free software by changing the effect of many bugs
|
|
||||||
from simple warnings into fatal crashes. Thus
|
|
||||||
<option>--enable-debug=no</option> should <emphasis>not</emphasis>
|
|
||||||
be used for stable releases of GLib.
|
|
||||||
</para>
|
|
||||||
</formalpara>
|
|
||||||
|
|
||||||
<formalpara>
|
|
||||||
<title><systemitem>--disable-gc-friendly</systemitem> and
|
|
||||||
<systemitem>--enable-gc-friendly</systemitem></title>
|
|
||||||
|
|
||||||
<para>
|
|
||||||
By default, and with <systemitem>--disable-gc-friendly</systemitem>
|
|
||||||
as well, Glib does not clear the memory for certain objects before
|
|
||||||
they are freed. For example, Glib may decide to recycle GList nodes
|
|
||||||
by putting them in a free list. However, memory profiling and debugging
|
|
||||||
tools like <ulink url="http://www.valgrind.org">Valgrind</ulink> work
|
|
||||||
better if an application does not keep dangling pointers to freed
|
|
||||||
memory (even though these pointers are no longer dereferenced), or
|
|
||||||
invalid pointers inside uninitialized memory.
|
|
||||||
The <systemitem>--enable-gc-friendly</systemitem> option makes Glib
|
|
||||||
clear memory in these situations:
|
|
||||||
</para>
|
|
||||||
|
|
||||||
<itemizedlist>
|
|
||||||
<listitem>
|
|
||||||
<para>
|
|
||||||
When shrinking a GArray, Glib will clear the memory no longer
|
|
||||||
available in the array: shrink an array from 10 bytes to 7, and
|
|
||||||
the last 3 bytes will be cleared. This includes removals of single
|
|
||||||
and multiple elements.
|
|
||||||
</para>
|
|
||||||
</listitem>
|
|
||||||
<listitem>
|
|
||||||
<para>
|
|
||||||
When growing a GArray, Glib will clear the new chunk of memory.
|
|
||||||
Grow an array from 7 bytes to 10 bytes, and the last 3 bytes will
|
|
||||||
be cleared.
|
|
||||||
</para>
|
|
||||||
</listitem>
|
|
||||||
<listitem>
|
|
||||||
<para>
|
|
||||||
The above applies to GPtrArray as well.
|
|
||||||
</para>
|
|
||||||
</listitem>
|
|
||||||
<listitem>
|
|
||||||
<para>
|
|
||||||
When freeing a node from a GHashTable, Glib will first clear
|
|
||||||
the node, which used to have pointers to the key and the value
|
|
||||||
stored at that node.
|
|
||||||
</para>
|
|
||||||
</listitem>
|
|
||||||
<listitem>
|
|
||||||
<para>
|
|
||||||
When destroying or removing a GTree node, Glib will clear the node,
|
|
||||||
which used to have pointers to the node's value, and the left and
|
|
||||||
right subnodes.
|
|
||||||
</para>
|
|
||||||
</listitem>
|
|
||||||
</itemizedlist>
|
|
||||||
|
|
||||||
<para>
|
|
||||||
Since clearing the memory has a cost,
|
|
||||||
<systemitem>--disable-gc-friendly</systemitem> is the default.
|
|
||||||
</para>
|
|
||||||
</formalpara>
|
|
||||||
|
|
||||||
<formalpara>
|
|
||||||
<title><systemitem>--disable-mem-pools</systemitem> and
|
|
||||||
<systemitem>--enable-mem-pools</systemitem></title>
|
|
||||||
|
|
||||||
<para>
|
|
||||||
Many small chunks of memory are often allocated via collective pools
|
|
||||||
in GLib and are cached after release to speed up reallocations.
|
|
||||||
For sparse memory systems this behaviour is often inferior, so
|
|
||||||
memory pools can be disabled to avoid excessive caching and force
|
|
||||||
atomic maintenance of chunks through the <function>g_malloc()</function>
|
|
||||||
and <function>g_free()</function> functions. Code currently affected by
|
|
||||||
this:
|
|
||||||
<itemizedlist>
|
|
||||||
<listitem>
|
|
||||||
<para>
|
|
||||||
<structname>GMemChunk</structname>s become basically non-effective
|
|
||||||
</para>
|
|
||||||
</listitem>
|
|
||||||
<listitem>
|
|
||||||
<para>
|
|
||||||
<structname>GSignal</structname> disables all caching
|
|
||||||
(potentially very slow)
|
|
||||||
</para>
|
|
||||||
</listitem>
|
|
||||||
<listitem>
|
|
||||||
<para>
|
|
||||||
<structname>GType</structname> doesn't honour the
|
|
||||||
<structname>GTypeInfo</structname>
|
|
||||||
<structfield>n_preallocs</structfield> field anymore
|
|
||||||
</para>
|
|
||||||
</listitem>
|
|
||||||
<listitem>
|
|
||||||
<para>
|
|
||||||
the <structname>GBSearchArray</structname> flag
|
|
||||||
<literal>G_BSEARCH_ALIGN_POWER2</literal> becomes non-functional
|
|
||||||
</para>
|
|
||||||
</listitem>
|
|
||||||
</itemizedlist>
|
|
||||||
</para>
|
|
||||||
</formalpara>
|
|
||||||
|
|
||||||
<formalpara>
|
|
||||||
<title><systemitem>--with-threads</systemitem></title>
|
|
||||||
|
|
||||||
<para>
|
|
||||||
Specify a thread implementation to use. Available options are
|
|
||||||
'posix' or 'win32'. Normally, <command>configure</command>
|
|
||||||
should be able to work out the system threads API on its own.
|
|
||||||
</para>
|
|
||||||
</formalpara>
|
|
||||||
|
|
||||||
<formalpara>
|
|
||||||
<title><systemitem>--disable-regex</systemitem> and
|
|
||||||
<systemitem>--enable-regex</systemitem></title>
|
|
||||||
|
|
||||||
<para>
|
|
||||||
Do not compile GLib with regular expression support.
|
|
||||||
GLib will be smaller because it will not need the
|
|
||||||
PCRE library. This is however not recommended, as
|
|
||||||
programs may need GRegex.
|
|
||||||
</para>
|
|
||||||
</formalpara>
|
|
||||||
|
|
||||||
<formalpara>
|
|
||||||
<title><systemitem>--with-pcre</systemitem></title>
|
|
||||||
|
|
||||||
<para>
|
|
||||||
Specify whether to use the internal or the system-supplied
|
|
||||||
PCRE library.
|
|
||||||
<itemizedlist>
|
|
||||||
<listitem>
|
|
||||||
<para>
|
|
||||||
'internal' means that GRegex will be compiled to use
|
|
||||||
the internal PCRE library.
|
|
||||||
</para>
|
|
||||||
</listitem>
|
|
||||||
<listitem>
|
|
||||||
<para>
|
|
||||||
'system' means that GRegex will be compiled to use
|
|
||||||
the system-supplied PCRE library.
|
|
||||||
</para>
|
|
||||||
</listitem>
|
|
||||||
</itemizedlist>
|
|
||||||
Using the internal PCRE is the preferred solution:
|
|
||||||
<itemizedlist>
|
|
||||||
<listitem>
|
|
||||||
<para>
|
|
||||||
System-supplied PCRE has a separated copy of the big tables
|
|
||||||
used for Unicode handling.
|
|
||||||
</para>
|
|
||||||
</listitem>
|
|
||||||
<listitem>
|
|
||||||
<para>
|
|
||||||
Some systems have PCRE libraries compiled without some needed
|
|
||||||
features, such as UTF-8 and Unicode support.
|
|
||||||
</para>
|
|
||||||
</listitem>
|
|
||||||
<listitem>
|
|
||||||
<para>
|
|
||||||
PCRE uses some global variables for memory management and
|
|
||||||
other features. In the rare case of a program using both
|
|
||||||
GRegex and PCRE (maybe indirectly through a library),
|
|
||||||
this variables could lead to problems when they are modified.
|
|
||||||
</para>
|
|
||||||
</listitem>
|
|
||||||
</itemizedlist>
|
|
||||||
</para>
|
|
||||||
</formalpara>
|
|
||||||
|
|
||||||
<formalpara>
|
|
||||||
<title><systemitem>--disable-included-printf</systemitem> and
|
|
||||||
<systemitem>--enable-included-printf</systemitem></title>
|
|
||||||
|
|
||||||
<para>
|
|
||||||
By default the <command>configure</command> script will try
|
|
||||||
to auto-detect whether the C library provides a suitable set
|
|
||||||
of printf() functions. In detail, <command>configure</command>
|
|
||||||
checks that the semantics of snprintf() are as specified by C99
|
|
||||||
and that positional parameters as specified in the Single Unix
|
|
||||||
Specification are supported. If this not the case, GLib will
|
|
||||||
include an implementation of the printf() family.
|
|
||||||
</para>
|
|
||||||
<para>
|
|
||||||
These options can be used to explicitly control whether
|
|
||||||
an implementation of the printf() family should be included or not.
|
|
||||||
</para>
|
|
||||||
</formalpara>
|
|
||||||
|
|
||||||
<formalpara>
|
|
||||||
<title><systemitem>--disable-Bsymbolic</systemitem> and
|
|
||||||
<systemitem>--enable-Bsymbolic</systemitem></title>
|
|
||||||
|
|
||||||
<para>
|
|
||||||
By default, GLib uses the -Bsymbolic-functions linker
|
|
||||||
flag to avoid intra-library PLT jumps. A side-effect
|
|
||||||
of this is that it is no longer possible to override
|
|
||||||
internal uses of GLib functions with
|
|
||||||
<envar>LD_PRELOAD</envar>. Therefore, it may make
|
|
||||||
sense to turn this feature off in some situations.
|
|
||||||
The <option>--disable-Bsymbolic</option> option allows
|
|
||||||
to do that.
|
|
||||||
</para>
|
|
||||||
</formalpara>
|
|
||||||
|
|
||||||
<formalpara>
|
|
||||||
<title><systemitem>--disable-gtk-doc</systemitem> and
|
|
||||||
<systemitem>--enable-gtk-doc</systemitem></title>
|
|
||||||
|
|
||||||
<para>
|
|
||||||
By default the <command>configure</command> script will try
|
|
||||||
to auto-detect whether the
|
|
||||||
<application>gtk-doc</application> package is installed.
|
|
||||||
If it is, then it will use it to extract and build the
|
|
||||||
documentation for the GLib library. These options
|
|
||||||
can be used to explicitly control whether
|
|
||||||
<application>gtk-doc</application> should be
|
|
||||||
used or not. If it is not used, the distributed,
|
|
||||||
pre-generated HTML files will be installed instead of
|
|
||||||
building them on your machine.
|
|
||||||
</para>
|
|
||||||
</formalpara>
|
|
||||||
|
|
||||||
<formalpara>
|
|
||||||
<title><systemitem>--disable-man</systemitem> and
|
|
||||||
<systemitem>--enable-man</systemitem></title>
|
|
||||||
|
|
||||||
<para>
|
|
||||||
By default the <command>configure</command> script will try
|
|
||||||
to auto-detect whether <application>xsltproc</application>
|
|
||||||
and the necessary Docbook stylesheets are installed.
|
|
||||||
If they are, then it will use them to rebuild the included
|
|
||||||
man pages from the XML sources. These options can be used
|
|
||||||
to explicitly control whether man pages should be rebuilt
|
|
||||||
used or not. The distribution includes pre-generated man
|
|
||||||
pages.
|
|
||||||
</para>
|
|
||||||
</formalpara>
|
|
||||||
|
|
||||||
<formalpara>
|
|
||||||
<title><systemitem>--disable-xattr</systemitem> and
|
|
||||||
<systemitem>--enable-xattr</systemitem></title>
|
|
||||||
|
|
||||||
<para>
|
|
||||||
By default the <command>configure</command> script will try
|
|
||||||
to auto-detect whether the getxattr() family of functions
|
|
||||||
is available. If it is, then extended attribute support
|
|
||||||
will be included in GIO. These options can be used to
|
|
||||||
explicitly control whether extended attribute support
|
|
||||||
should be included or not. getxattr() and friends can
|
|
||||||
be provided by glibc or by the standalone libattr library.
|
|
||||||
</para>
|
|
||||||
</formalpara>
|
|
||||||
|
|
||||||
<formalpara>
|
|
||||||
<title><systemitem>--disable-selinux</systemitem> and
|
|
||||||
<systemitem>--enable-selinux</systemitem></title>
|
|
||||||
|
|
||||||
<para>
|
|
||||||
By default the <command>configure</command> script will
|
|
||||||
auto-detect if libselinux is available and include
|
|
||||||
SELinux support in GIO if it is. These options can be
|
|
||||||
used to explicitly control whether SELinux support should
|
|
||||||
be included.
|
|
||||||
</para>
|
|
||||||
</formalpara>
|
|
||||||
|
|
||||||
<formalpara>
|
|
||||||
<title><systemitem>--disable-dtrace</systemitem> and
|
|
||||||
<systemitem>--enable-dtrace</systemitem></title>
|
|
||||||
|
|
||||||
<para>
|
|
||||||
By default the <command>configure</command> script will
|
|
||||||
detect if DTrace support is available, and use it.
|
|
||||||
</para>
|
|
||||||
</formalpara>
|
|
||||||
|
|
||||||
<formalpara>
|
|
||||||
<title><systemitem>--disable-systemtap</systemitem> and
|
|
||||||
<systemitem>--enable-systemtap</systemitem></title>
|
|
||||||
|
|
||||||
<para>
|
|
||||||
This option requires DTrace support. If it is available, then
|
|
||||||
the <command>configure</command> script will also check for
|
|
||||||
the presence of SystemTap.
|
|
||||||
</para>
|
|
||||||
</formalpara>
|
|
||||||
|
|
||||||
<formalpara>
|
|
||||||
<title><systemitem>--enable-gcov</systemitem> and
|
|
||||||
<systemitem>--disable-gcov</systemitem></title>
|
|
||||||
|
|
||||||
<para>
|
|
||||||
Enable the generation of coverage reports for the GLib tests.
|
|
||||||
This requires the lcov frontend to gcov from the
|
|
||||||
<ulink url="http://ltp.sourceforge.net">Linux Test Project</ulink>.
|
|
||||||
To generate a coverage report, use the lcov make target. The
|
|
||||||
report is placed in the <filename>glib-lcov</filename> directory.
|
|
||||||
</para>
|
|
||||||
</formalpara>
|
|
||||||
|
|
||||||
<formalpara>
|
|
||||||
<title><systemitem>--with-runtime-libdir=RELPATH</systemitem></title>
|
|
||||||
|
|
||||||
<para>
|
|
||||||
Allows specifying a relative path to where to install the runtime
|
|
||||||
libraries (meaning library files used for running, not developing,
|
|
||||||
GLib applications). This can be used in operating system setups where
|
|
||||||
programs using GLib needs to run before e.g. <filename>/usr</filename>
|
|
||||||
is mounted.
|
|
||||||
For example, if LIBDIR is <filename>/usr/lib</filename> and
|
|
||||||
<filename>../../lib</filename> is passed to
|
|
||||||
<systemitem>--with-runtime-libdir</systemitem> then the
|
|
||||||
runtime libraries are installed into <filename>/lib</filename> rather
|
|
||||||
than <filename>/usr/lib</filename>.
|
|
||||||
</para>
|
|
||||||
</formalpara>
|
|
||||||
|
|
||||||
<formalpara>
|
|
||||||
<title><systemitem>--with-python</systemitem></title>
|
|
||||||
|
|
||||||
<para>
|
|
||||||
Allows specifying the Python interpreter to use, either as an absolute path,
|
|
||||||
or as a program name. GLib can be built with Python 2 (at least version 2.5)
|
|
||||||
or Python 3.
|
|
||||||
</para>
|
|
||||||
</formalpara>
|
|
||||||
</refsect1>
|
</refsect1>
|
||||||
|
|
||||||
</refentry>
|
</refentry>
|
||||||
|
|
|
@ -2,549 +2,23 @@
|
||||||
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
|
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
|
||||||
"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
|
"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
|
||||||
]>
|
]>
|
||||||
<refentry id="glib-building">
|
<refentry id="extending">
|
||||||
<refmeta>
|
<refmeta>
|
||||||
<refentrytitle>Compiling the GLib package</refentrytitle>
|
<refentrytitle>Extending VIPS</refentrytitle>
|
||||||
<manvolnum>3</manvolnum>
|
<manvolnum>3</manvolnum>
|
||||||
<refmiscinfo>GLib Library</refmiscinfo>
|
<refmiscinfo>VIPS Library</refmiscinfo>
|
||||||
</refmeta>
|
</refmeta>
|
||||||
|
|
||||||
<refnamediv>
|
<refnamediv>
|
||||||
<refname>Compiling the GLib Package</refname>
|
<refname>Extending</refname>
|
||||||
<refpurpose>How to compile GLib itself</refpurpose>
|
<refpurpose>How to add operations to VIPS</refpurpose>
|
||||||
</refnamediv>
|
</refnamediv>
|
||||||
|
|
||||||
<refsect1 id="building">
|
<refsect1 id="extending-subclassing">
|
||||||
<title>Building the Library on UNIX</title>
|
<title>Adding operations to VIPS</title>
|
||||||
<para>
|
<para>
|
||||||
On UNIX, GLib uses the standard GNU build system,
|
all about subclassing.
|
||||||
using <application>autoconf</application> for package
|
|
||||||
configuration and resolving portability issues,
|
|
||||||
<application>automake</application> for building makefiles
|
|
||||||
that comply with the GNU Coding Standards, and
|
|
||||||
<application>libtool</application> for building shared
|
|
||||||
libraries on multiple platforms. The normal sequence for
|
|
||||||
compiling and installing the GLib library is thus:
|
|
||||||
|
|
||||||
<literallayout>
|
|
||||||
<userinput>./configure</userinput>
|
|
||||||
<userinput>make</userinput>
|
|
||||||
<userinput>make install</userinput>
|
|
||||||
</literallayout>
|
|
||||||
</para>
|
</para>
|
||||||
|
|
||||||
<para>
|
|
||||||
The standard options provided by <application>GNU
|
|
||||||
autoconf</application> may be passed to the
|
|
||||||
<command>configure</command> script. Please see the
|
|
||||||
<application>autoconf</application> documentation or run
|
|
||||||
<command>./configure --help</command> for information about
|
|
||||||
the standard options.
|
|
||||||
</para>
|
|
||||||
<para>
|
|
||||||
The GTK+ documentation contains
|
|
||||||
<ulink url="../gtk/gtk-building.html">further details</ulink>
|
|
||||||
about the build process and ways to influence it.
|
|
||||||
</para>
|
|
||||||
</refsect1>
|
|
||||||
<refsect1 id="dependencies">
|
|
||||||
<title>Dependencies</title>
|
|
||||||
<para>
|
|
||||||
Before you can compile the GLib library, you need to have
|
|
||||||
various other tools and libraries installed on your system.
|
|
||||||
Beyond a C compiler (which must implement C90, but does not need
|
|
||||||
to implement C99), the two tools needed during the build process
|
|
||||||
(as differentiated from the tools used in when creating GLib
|
|
||||||
mentioned above such as <application>autoconf</application>) are
|
|
||||||
<command>pkg-config</command> and GNU make.
|
|
||||||
</para>
|
|
||||||
<itemizedlist>
|
|
||||||
<listitem>
|
|
||||||
<para>
|
|
||||||
<ulink url="http://www.freedesktop.org/software/pkgconfig/">pkg-config</ulink>
|
|
||||||
is a tool for tracking the compilation flags needed for
|
|
||||||
libraries that are used by the GLib library. (For each
|
|
||||||
library, a small <literal>.pc</literal> text file is
|
|
||||||
installed in a standard location that contains the compilation
|
|
||||||
flags needed for that library along with version number
|
|
||||||
information.) The version of <command>pkg-config</command>
|
|
||||||
needed to build GLib is mirrored in the
|
|
||||||
<filename>dependencies</filename> directory
|
|
||||||
on the <ulink url="ftp://ftp.gtk.org/pub/gtk/v2.2/">GTK+ FTP
|
|
||||||
site.</ulink>
|
|
||||||
</para>
|
|
||||||
</listitem>
|
|
||||||
<listitem>
|
|
||||||
<para>
|
|
||||||
The GLib Makefiles make use of several features specific to
|
|
||||||
<ulink url="http://www.gnu.org/software/make">GNU
|
|
||||||
make</ulink>, and will not build correctly with other
|
|
||||||
versions of <command>make</command>. You will need to
|
|
||||||
install it if you don't already have it on your system. (It
|
|
||||||
may be called <command>gmake</command> rather than
|
|
||||||
<command>make</command>.)
|
|
||||||
</para>
|
|
||||||
</listitem>
|
|
||||||
</itemizedlist>
|
|
||||||
<para>
|
|
||||||
A UNIX build of GLib requires that the system implements at
|
|
||||||
least the original 1990 version of POSIX. Beyond this, it
|
|
||||||
depends on a number of other libraries.
|
|
||||||
</para>
|
|
||||||
<itemizedlist>
|
|
||||||
<listitem>
|
|
||||||
<para>
|
|
||||||
The <ulink url="http://www.gnu.org/software/libiconv/">GNU
|
|
||||||
libiconv library</ulink> is needed to build GLib if your
|
|
||||||
system doesn't have the <function>iconv()</function>
|
|
||||||
function for doing conversion between character
|
|
||||||
encodings. Most modern systems should have
|
|
||||||
<function>iconv()</function>, however many older systems lack
|
|
||||||
an <function>iconv()</function> implementation. On such systems,
|
|
||||||
you must install the libiconv library. This can be found at:
|
|
||||||
<ulink url="http://www.gnu.org/software/libiconv">http://www.gnu.org/software/libiconv</ulink>.
|
|
||||||
</para>
|
|
||||||
<para>
|
|
||||||
If your system has an <function>iconv()</function> implementation but
|
|
||||||
you want to use libiconv instead, you can pass the
|
|
||||||
--with-libiconv option to configure. This forces
|
|
||||||
libiconv to be used.
|
|
||||||
</para>
|
|
||||||
<para>
|
|
||||||
Note that if you have libiconv installed in your default include
|
|
||||||
search path (for instance, in <filename>/usr/local/</filename>), but
|
|
||||||
don't enable it, you will get an error while compiling GLib because
|
|
||||||
the <filename>iconv.h</filename> that libiconv installs hides the
|
|
||||||
system iconv.
|
|
||||||
</para>
|
|
||||||
<para>
|
|
||||||
If you are using the native iconv implementation on Solaris
|
|
||||||
instead of libiconv, you'll need to make sure that you have
|
|
||||||
the converters between locale encodings and UTF-8 installed.
|
|
||||||
At a minimum you'll need the SUNWuiu8 package. You probably
|
|
||||||
should also install the SUNWciu8, SUNWhiu8, SUNWjiu8, and
|
|
||||||
SUNWkiu8 packages.
|
|
||||||
</para>
|
|
||||||
<para>
|
|
||||||
The native iconv on Compaq Tru64 doesn't contain support for
|
|
||||||
UTF-8, so you'll need to use GNU libiconv instead. (When
|
|
||||||
using GNU libiconv for GLib, you'll need to use GNU libiconv
|
|
||||||
for GNU gettext as well.) This probably applies to related
|
|
||||||
operating systems as well.
|
|
||||||
</para>
|
|
||||||
</listitem>
|
|
||||||
<listitem>
|
|
||||||
<para>
|
|
||||||
The libintl library from the <ulink
|
|
||||||
url="http://www.gnu.org/software/gettext">GNU gettext
|
|
||||||
package</ulink> is needed if your system doesn't have the
|
|
||||||
<function>gettext()</function> functionality for handling
|
|
||||||
message translation databases.
|
|
||||||
</para>
|
|
||||||
</listitem>
|
|
||||||
<listitem>
|
|
||||||
<para>
|
|
||||||
A thread implementation is needed. The thread support in GLib
|
|
||||||
can be based upon POSIX threads or win32 threads.
|
|
||||||
</para>
|
|
||||||
</listitem>
|
|
||||||
<listitem>
|
|
||||||
<para>
|
|
||||||
GRegex uses the <ulink url="http://www.pcre.org/">PCRE library</ulink>
|
|
||||||
for regular expression matching. The default is to use the internal
|
|
||||||
version of PCRE that is patched to use GLib for memory management
|
|
||||||
and Unicode handling. If you prefer to use the system-supplied PCRE
|
|
||||||
library you can pass the <option>--with-pcre=system</option> option
|
|
||||||
to, but it is not recommended.
|
|
||||||
</para>
|
|
||||||
</listitem>
|
|
||||||
<listitem>
|
|
||||||
<para>
|
|
||||||
The optional extended attribute support in GIO requires the
|
|
||||||
getxattr() family of functions that may be provided by glibc or
|
|
||||||
by the standalone libattr library. To build GLib without extended
|
|
||||||
attribute support, use the <option>--disable-xattr</option>
|
|
||||||
option.
|
|
||||||
</para>
|
|
||||||
</listitem>
|
|
||||||
<listitem>
|
|
||||||
<para>
|
|
||||||
The optional SELinux support in GIO requires libselinux.
|
|
||||||
To build GLib without SELinux support, use the
|
|
||||||
<option>--disable-selinux</option> option.
|
|
||||||
</para>
|
|
||||||
</listitem>
|
|
||||||
<listitem>
|
|
||||||
<para>
|
|
||||||
The optional support for DTrace requires the
|
|
||||||
<filename>sys/sdt.h</filename> header, which is provided
|
|
||||||
by SystemTap on Linux. To build GLib without DTrace, use
|
|
||||||
the <option>--disable-dtrace</option> configure option.
|
|
||||||
</para>
|
|
||||||
</listitem>
|
|
||||||
<listitem>
|
|
||||||
<para>
|
|
||||||
The optional support for
|
|
||||||
<ulink url="http://sourceware.org/systemtap/">SystemTap</ulink>
|
|
||||||
can be disabled with the <option>--disable-systemtap</option>
|
|
||||||
configure option.
|
|
||||||
</para>
|
|
||||||
</listitem>
|
|
||||||
</itemizedlist>
|
|
||||||
|
|
||||||
</refsect1>
|
|
||||||
<refsect1 id="extra-configuration-options">
|
|
||||||
<title>Extra Configuration Options</title>
|
|
||||||
|
|
||||||
<para>
|
|
||||||
In addition to the normal options, the
|
|
||||||
<command>configure</command> script in the GLib
|
|
||||||
library supports these additional arguments:
|
|
||||||
</para>
|
|
||||||
|
|
||||||
<formalpara>
|
|
||||||
<title><systemitem>--enable-debug</systemitem></title>
|
|
||||||
|
|
||||||
<para>
|
|
||||||
Turns on various amounts of debugging support. Setting this to 'no'
|
|
||||||
disables g_assert(), g_return_if_fail(), g_return_val_if_fail() and
|
|
||||||
all cast checks between different object types. Setting it to 'minimum' disables only cast checks. Setting it to 'yes' enables
|
|
||||||
<link linkend="G-DEBUG:CAPS">runtime debugging</link>.
|
|
||||||
The default is 'minimum'.
|
|
||||||
Note that 'no' is fast, but dangerous as it tends to destabilize
|
|
||||||
even mostly bug-free software by changing the effect of many bugs
|
|
||||||
from simple warnings into fatal crashes. Thus
|
|
||||||
<option>--enable-debug=no</option> should <emphasis>not</emphasis>
|
|
||||||
be used for stable releases of GLib.
|
|
||||||
</para>
|
|
||||||
</formalpara>
|
|
||||||
|
|
||||||
<formalpara>
|
|
||||||
<title><systemitem>--disable-gc-friendly</systemitem> and
|
|
||||||
<systemitem>--enable-gc-friendly</systemitem></title>
|
|
||||||
|
|
||||||
<para>
|
|
||||||
By default, and with <systemitem>--disable-gc-friendly</systemitem>
|
|
||||||
as well, Glib does not clear the memory for certain objects before
|
|
||||||
they are freed. For example, Glib may decide to recycle GList nodes
|
|
||||||
by putting them in a free list. However, memory profiling and debugging
|
|
||||||
tools like <ulink url="http://www.valgrind.org">Valgrind</ulink> work
|
|
||||||
better if an application does not keep dangling pointers to freed
|
|
||||||
memory (even though these pointers are no longer dereferenced), or
|
|
||||||
invalid pointers inside uninitialized memory.
|
|
||||||
The <systemitem>--enable-gc-friendly</systemitem> option makes Glib
|
|
||||||
clear memory in these situations:
|
|
||||||
</para>
|
|
||||||
|
|
||||||
<itemizedlist>
|
|
||||||
<listitem>
|
|
||||||
<para>
|
|
||||||
When shrinking a GArray, Glib will clear the memory no longer
|
|
||||||
available in the array: shrink an array from 10 bytes to 7, and
|
|
||||||
the last 3 bytes will be cleared. This includes removals of single
|
|
||||||
and multiple elements.
|
|
||||||
</para>
|
|
||||||
</listitem>
|
|
||||||
<listitem>
|
|
||||||
<para>
|
|
||||||
When growing a GArray, Glib will clear the new chunk of memory.
|
|
||||||
Grow an array from 7 bytes to 10 bytes, and the last 3 bytes will
|
|
||||||
be cleared.
|
|
||||||
</para>
|
|
||||||
</listitem>
|
|
||||||
<listitem>
|
|
||||||
<para>
|
|
||||||
The above applies to GPtrArray as well.
|
|
||||||
</para>
|
|
||||||
</listitem>
|
|
||||||
<listitem>
|
|
||||||
<para>
|
|
||||||
When freeing a node from a GHashTable, Glib will first clear
|
|
||||||
the node, which used to have pointers to the key and the value
|
|
||||||
stored at that node.
|
|
||||||
</para>
|
|
||||||
</listitem>
|
|
||||||
<listitem>
|
|
||||||
<para>
|
|
||||||
When destroying or removing a GTree node, Glib will clear the node,
|
|
||||||
which used to have pointers to the node's value, and the left and
|
|
||||||
right subnodes.
|
|
||||||
</para>
|
|
||||||
</listitem>
|
|
||||||
</itemizedlist>
|
|
||||||
|
|
||||||
<para>
|
|
||||||
Since clearing the memory has a cost,
|
|
||||||
<systemitem>--disable-gc-friendly</systemitem> is the default.
|
|
||||||
</para>
|
|
||||||
</formalpara>
|
|
||||||
|
|
||||||
<formalpara>
|
|
||||||
<title><systemitem>--disable-mem-pools</systemitem> and
|
|
||||||
<systemitem>--enable-mem-pools</systemitem></title>
|
|
||||||
|
|
||||||
<para>
|
|
||||||
Many small chunks of memory are often allocated via collective pools
|
|
||||||
in GLib and are cached after release to speed up reallocations.
|
|
||||||
For sparse memory systems this behaviour is often inferior, so
|
|
||||||
memory pools can be disabled to avoid excessive caching and force
|
|
||||||
atomic maintenance of chunks through the <function>g_malloc()</function>
|
|
||||||
and <function>g_free()</function> functions. Code currently affected by
|
|
||||||
this:
|
|
||||||
<itemizedlist>
|
|
||||||
<listitem>
|
|
||||||
<para>
|
|
||||||
<structname>GMemChunk</structname>s become basically non-effective
|
|
||||||
</para>
|
|
||||||
</listitem>
|
|
||||||
<listitem>
|
|
||||||
<para>
|
|
||||||
<structname>GSignal</structname> disables all caching
|
|
||||||
(potentially very slow)
|
|
||||||
</para>
|
|
||||||
</listitem>
|
|
||||||
<listitem>
|
|
||||||
<para>
|
|
||||||
<structname>GType</structname> doesn't honour the
|
|
||||||
<structname>GTypeInfo</structname>
|
|
||||||
<structfield>n_preallocs</structfield> field anymore
|
|
||||||
</para>
|
|
||||||
</listitem>
|
|
||||||
<listitem>
|
|
||||||
<para>
|
|
||||||
the <structname>GBSearchArray</structname> flag
|
|
||||||
<literal>G_BSEARCH_ALIGN_POWER2</literal> becomes non-functional
|
|
||||||
</para>
|
|
||||||
</listitem>
|
|
||||||
</itemizedlist>
|
|
||||||
</para>
|
|
||||||
</formalpara>
|
|
||||||
|
|
||||||
<formalpara>
|
|
||||||
<title><systemitem>--with-threads</systemitem></title>
|
|
||||||
|
|
||||||
<para>
|
|
||||||
Specify a thread implementation to use. Available options are
|
|
||||||
'posix' or 'win32'. Normally, <command>configure</command>
|
|
||||||
should be able to work out the system threads API on its own.
|
|
||||||
</para>
|
|
||||||
</formalpara>
|
|
||||||
|
|
||||||
<formalpara>
|
|
||||||
<title><systemitem>--disable-regex</systemitem> and
|
|
||||||
<systemitem>--enable-regex</systemitem></title>
|
|
||||||
|
|
||||||
<para>
|
|
||||||
Do not compile GLib with regular expression support.
|
|
||||||
GLib will be smaller because it will not need the
|
|
||||||
PCRE library. This is however not recommended, as
|
|
||||||
programs may need GRegex.
|
|
||||||
</para>
|
|
||||||
</formalpara>
|
|
||||||
|
|
||||||
<formalpara>
|
|
||||||
<title><systemitem>--with-pcre</systemitem></title>
|
|
||||||
|
|
||||||
<para>
|
|
||||||
Specify whether to use the internal or the system-supplied
|
|
||||||
PCRE library.
|
|
||||||
<itemizedlist>
|
|
||||||
<listitem>
|
|
||||||
<para>
|
|
||||||
'internal' means that GRegex will be compiled to use
|
|
||||||
the internal PCRE library.
|
|
||||||
</para>
|
|
||||||
</listitem>
|
|
||||||
<listitem>
|
|
||||||
<para>
|
|
||||||
'system' means that GRegex will be compiled to use
|
|
||||||
the system-supplied PCRE library.
|
|
||||||
</para>
|
|
||||||
</listitem>
|
|
||||||
</itemizedlist>
|
|
||||||
Using the internal PCRE is the preferred solution:
|
|
||||||
<itemizedlist>
|
|
||||||
<listitem>
|
|
||||||
<para>
|
|
||||||
System-supplied PCRE has a separated copy of the big tables
|
|
||||||
used for Unicode handling.
|
|
||||||
</para>
|
|
||||||
</listitem>
|
|
||||||
<listitem>
|
|
||||||
<para>
|
|
||||||
Some systems have PCRE libraries compiled without some needed
|
|
||||||
features, such as UTF-8 and Unicode support.
|
|
||||||
</para>
|
|
||||||
</listitem>
|
|
||||||
<listitem>
|
|
||||||
<para>
|
|
||||||
PCRE uses some global variables for memory management and
|
|
||||||
other features. In the rare case of a program using both
|
|
||||||
GRegex and PCRE (maybe indirectly through a library),
|
|
||||||
this variables could lead to problems when they are modified.
|
|
||||||
</para>
|
|
||||||
</listitem>
|
|
||||||
</itemizedlist>
|
|
||||||
</para>
|
|
||||||
</formalpara>
|
|
||||||
|
|
||||||
<formalpara>
|
|
||||||
<title><systemitem>--disable-included-printf</systemitem> and
|
|
||||||
<systemitem>--enable-included-printf</systemitem></title>
|
|
||||||
|
|
||||||
<para>
|
|
||||||
By default the <command>configure</command> script will try
|
|
||||||
to auto-detect whether the C library provides a suitable set
|
|
||||||
of printf() functions. In detail, <command>configure</command>
|
|
||||||
checks that the semantics of snprintf() are as specified by C99
|
|
||||||
and that positional parameters as specified in the Single Unix
|
|
||||||
Specification are supported. If this not the case, GLib will
|
|
||||||
include an implementation of the printf() family.
|
|
||||||
</para>
|
|
||||||
<para>
|
|
||||||
These options can be used to explicitly control whether
|
|
||||||
an implementation of the printf() family should be included or not.
|
|
||||||
</para>
|
|
||||||
</formalpara>
|
|
||||||
|
|
||||||
<formalpara>
|
|
||||||
<title><systemitem>--disable-Bsymbolic</systemitem> and
|
|
||||||
<systemitem>--enable-Bsymbolic</systemitem></title>
|
|
||||||
|
|
||||||
<para>
|
|
||||||
By default, GLib uses the -Bsymbolic-functions linker
|
|
||||||
flag to avoid intra-library PLT jumps. A side-effect
|
|
||||||
of this is that it is no longer possible to override
|
|
||||||
internal uses of GLib functions with
|
|
||||||
<envar>LD_PRELOAD</envar>. Therefore, it may make
|
|
||||||
sense to turn this feature off in some situations.
|
|
||||||
The <option>--disable-Bsymbolic</option> option allows
|
|
||||||
to do that.
|
|
||||||
</para>
|
|
||||||
</formalpara>
|
|
||||||
|
|
||||||
<formalpara>
|
|
||||||
<title><systemitem>--disable-gtk-doc</systemitem> and
|
|
||||||
<systemitem>--enable-gtk-doc</systemitem></title>
|
|
||||||
|
|
||||||
<para>
|
|
||||||
By default the <command>configure</command> script will try
|
|
||||||
to auto-detect whether the
|
|
||||||
<application>gtk-doc</application> package is installed.
|
|
||||||
If it is, then it will use it to extract and build the
|
|
||||||
documentation for the GLib library. These options
|
|
||||||
can be used to explicitly control whether
|
|
||||||
<application>gtk-doc</application> should be
|
|
||||||
used or not. If it is not used, the distributed,
|
|
||||||
pre-generated HTML files will be installed instead of
|
|
||||||
building them on your machine.
|
|
||||||
</para>
|
|
||||||
</formalpara>
|
|
||||||
|
|
||||||
<formalpara>
|
|
||||||
<title><systemitem>--disable-man</systemitem> and
|
|
||||||
<systemitem>--enable-man</systemitem></title>
|
|
||||||
|
|
||||||
<para>
|
|
||||||
By default the <command>configure</command> script will try
|
|
||||||
to auto-detect whether <application>xsltproc</application>
|
|
||||||
and the necessary Docbook stylesheets are installed.
|
|
||||||
If they are, then it will use them to rebuild the included
|
|
||||||
man pages from the XML sources. These options can be used
|
|
||||||
to explicitly control whether man pages should be rebuilt
|
|
||||||
used or not. The distribution includes pre-generated man
|
|
||||||
pages.
|
|
||||||
</para>
|
|
||||||
</formalpara>
|
|
||||||
|
|
||||||
<formalpara>
|
|
||||||
<title><systemitem>--disable-xattr</systemitem> and
|
|
||||||
<systemitem>--enable-xattr</systemitem></title>
|
|
||||||
|
|
||||||
<para>
|
|
||||||
By default the <command>configure</command> script will try
|
|
||||||
to auto-detect whether the getxattr() family of functions
|
|
||||||
is available. If it is, then extended attribute support
|
|
||||||
will be included in GIO. These options can be used to
|
|
||||||
explicitly control whether extended attribute support
|
|
||||||
should be included or not. getxattr() and friends can
|
|
||||||
be provided by glibc or by the standalone libattr library.
|
|
||||||
</para>
|
|
||||||
</formalpara>
|
|
||||||
|
|
||||||
<formalpara>
|
|
||||||
<title><systemitem>--disable-selinux</systemitem> and
|
|
||||||
<systemitem>--enable-selinux</systemitem></title>
|
|
||||||
|
|
||||||
<para>
|
|
||||||
By default the <command>configure</command> script will
|
|
||||||
auto-detect if libselinux is available and include
|
|
||||||
SELinux support in GIO if it is. These options can be
|
|
||||||
used to explicitly control whether SELinux support should
|
|
||||||
be included.
|
|
||||||
</para>
|
|
||||||
</formalpara>
|
|
||||||
|
|
||||||
<formalpara>
|
|
||||||
<title><systemitem>--disable-dtrace</systemitem> and
|
|
||||||
<systemitem>--enable-dtrace</systemitem></title>
|
|
||||||
|
|
||||||
<para>
|
|
||||||
By default the <command>configure</command> script will
|
|
||||||
detect if DTrace support is available, and use it.
|
|
||||||
</para>
|
|
||||||
</formalpara>
|
|
||||||
|
|
||||||
<formalpara>
|
|
||||||
<title><systemitem>--disable-systemtap</systemitem> and
|
|
||||||
<systemitem>--enable-systemtap</systemitem></title>
|
|
||||||
|
|
||||||
<para>
|
|
||||||
This option requires DTrace support. If it is available, then
|
|
||||||
the <command>configure</command> script will also check for
|
|
||||||
the presence of SystemTap.
|
|
||||||
</para>
|
|
||||||
</formalpara>
|
|
||||||
|
|
||||||
<formalpara>
|
|
||||||
<title><systemitem>--enable-gcov</systemitem> and
|
|
||||||
<systemitem>--disable-gcov</systemitem></title>
|
|
||||||
|
|
||||||
<para>
|
|
||||||
Enable the generation of coverage reports for the GLib tests.
|
|
||||||
This requires the lcov frontend to gcov from the
|
|
||||||
<ulink url="http://ltp.sourceforge.net">Linux Test Project</ulink>.
|
|
||||||
To generate a coverage report, use the lcov make target. The
|
|
||||||
report is placed in the <filename>glib-lcov</filename> directory.
|
|
||||||
</para>
|
|
||||||
</formalpara>
|
|
||||||
|
|
||||||
<formalpara>
|
|
||||||
<title><systemitem>--with-runtime-libdir=RELPATH</systemitem></title>
|
|
||||||
|
|
||||||
<para>
|
|
||||||
Allows specifying a relative path to where to install the runtime
|
|
||||||
libraries (meaning library files used for running, not developing,
|
|
||||||
GLib applications). This can be used in operating system setups where
|
|
||||||
programs using GLib needs to run before e.g. <filename>/usr</filename>
|
|
||||||
is mounted.
|
|
||||||
For example, if LIBDIR is <filename>/usr/lib</filename> and
|
|
||||||
<filename>../../lib</filename> is passed to
|
|
||||||
<systemitem>--with-runtime-libdir</systemitem> then the
|
|
||||||
runtime libraries are installed into <filename>/lib</filename> rather
|
|
||||||
than <filename>/usr/lib</filename>.
|
|
||||||
</para>
|
|
||||||
</formalpara>
|
|
||||||
|
|
||||||
<formalpara>
|
|
||||||
<title><systemitem>--with-python</systemitem></title>
|
|
||||||
|
|
||||||
<para>
|
|
||||||
Allows specifying the Python interpreter to use, either as an absolute path,
|
|
||||||
or as a program name. GLib can be built with Python 2 (at least version 2.5)
|
|
||||||
or Python 3.
|
|
||||||
</para>
|
|
||||||
</formalpara>
|
|
||||||
</refsect1>
|
</refsect1>
|
||||||
|
|
||||||
</refentry>
|
</refentry>
|
||||||
|
|
|
@ -21,27 +21,41 @@
|
||||||
docs for full details, but this section will try to give a brief
|
docs for full details, but this section will try to give a brief
|
||||||
overview. The <command>vips</command> program is handy for getting a
|
overview. The <command>vips</command> program is handy for getting a
|
||||||
summary of an operation's parameters.
|
summary of an operation's parameters.
|
||||||
|
</para>
|
||||||
|
|
||||||
|
<para>
|
||||||
When your program starts, use <function>vips_init()</function> to set up
|
When your program starts, use <function>vips_init()</function> to set up
|
||||||
the VIPS library. You should pass it the name of your program, usually
|
the VIPS library. You should pass it the name of your program, usually
|
||||||
<literal>argv[0]</literal>. Use <function>vips_shutdown()</function>
|
<literal>argv[0]</literal>. Use <function>vips_shutdown()</function>
|
||||||
when you exit.
|
when you exit.
|
||||||
|
</para>
|
||||||
|
|
||||||
|
<para>
|
||||||
You can add the VIPS flags to your GObject command-line processing
|
You can add the VIPS flags to your GObject command-line processing
|
||||||
with vips_get_option_group(), see below.
|
with vips_get_option_group(), see below.
|
||||||
|
</para>
|
||||||
|
|
||||||
The basic data object is #VipsImage. You can create an image from a
|
<para>
|
||||||
file on disc or from an area of memory, either as a C-style array,
|
The basic data object is the #VipsImage, see <link
|
||||||
or as a formatted object, like JPEG. See vips_image_new_from_file() and
|
linkend="VipsImage">VIPS Image</link> for details on the
|
||||||
friends.
|
image class. You can create an image from a file on disc or from an
|
||||||
Loading an image is fast. VIPS read just enough of the image to be able
|
area of memory, either as a C-style array, or as a formatted object,
|
||||||
to get the various properties, such as width in pixels. It delays
|
like JPEG. See vips_image_new_from_file() and friends. Loading an
|
||||||
reading any pixels until they are really needed.
|
image is fast. VIPS read just enough of the image to be able to get
|
||||||
|
the various properties, such as width in pixels. It delays reading
|
||||||
|
any pixels until they are really needed.
|
||||||
|
</para>
|
||||||
|
|
||||||
|
<para>
|
||||||
Once you have an image, you can get properties from it in the usual way.
|
Once you have an image, you can get properties from it in the usual way.
|
||||||
You can use projection functions like vips_image_get_width(), or
|
You can use projection functions, like vips_image_get_width() or
|
||||||
g_object_get() to get GObject properties.
|
g_object_get(), to get GObject properties. All VIPS objects are
|
||||||
|
immutable, meaning you can only get properties, you can't set them.
|
||||||
|
See <link linkend="libvips-header">VIPS Header</link> to read about
|
||||||
|
image properties.
|
||||||
|
</para>
|
||||||
|
|
||||||
|
<para>
|
||||||
VIPS is based on the GObject library and is therefore refcounted.
|
VIPS is based on the GObject library and is therefore refcounted.
|
||||||
vips_image_new_from_file() returns an object with a count of 1.
|
vips_image_new_from_file() returns an object with a count of 1.
|
||||||
When you are done with an image, use g_object_unref() to dispose of it.
|
When you are done with an image, use g_object_unref() to dispose of it.
|
||||||
|
@ -49,25 +63,89 @@
|
||||||
copy of the image, it will ref it. So you can unref an image as soon as
|
copy of the image, it will ref it. So you can unref an image as soon as
|
||||||
you no longer need it, you don't need to hang on to it in case anyone
|
you no longer need it, you don't need to hang on to it in case anyone
|
||||||
else is still using it.
|
else is still using it.
|
||||||
|
|
||||||
VIPS images are three-dimensional arrays, the dimensions being width,
|
|
||||||
height and bands. Each dimension can be up to 2 ** 31 pixels (or band
|
|
||||||
elements). An image has a format, meaning the machine number type used
|
|
||||||
to represent each value. VIPS supports 10 formats, from 8-bit unsigned
|
|
||||||
integer up to 128-bit double complex, see #VipsBandFormat.
|
|
||||||
|
|
||||||
In VIPS, images are uninterpreted arrays, meaning that from the point of
|
|
||||||
view of most operations, they are just large collections of numbers.
|
|
||||||
There's no difference between an RGBA (RGB with alpha) image and a CMYK
|
|
||||||
image, for example, they are both just four-band images. It's up to the
|
|
||||||
user of the library to pass the right sort of image to each operation.
|
|
||||||
|
|
||||||
To take an example, VIPS has vips_Lab2XYZ(), an operation to transform
|
|
||||||
an image from CIE LAB colour space to CIE XYZ space. It assumes the
|
|
||||||
first three bands represent pixels in LAB colour space and returns an
|
|
||||||
image where the first three bands
|
|
||||||
|
|
||||||
</para>
|
</para>
|
||||||
|
|
||||||
|
<para>
|
||||||
|
Use things like vips_invert() to manipulate your images. See <link
|
||||||
|
linkend="VipsOperation">VIPS Operations</link> for information on
|
||||||
|
running operations on images. When you are done, you can write
|
||||||
|
the final image to a disc file, to a formatted memory buffer, or to
|
||||||
|
C-style memory array. See vips_image_write_to_file() and friends.
|
||||||
|
</para>
|
||||||
|
|
||||||
|
<para>
|
||||||
|
VIPS keeps a log of error message, see <link
|
||||||
|
linkend="libvips-error">VIPS Error</link> to find out how to get and
|
||||||
|
set the error log.
|
||||||
|
</para>
|
||||||
|
|
||||||
|
<example>
|
||||||
|
<title>VIPS from C example</title>
|
||||||
|
<programlisting language="C">
|
||||||
|
/* compile with:
|
||||||
|
*
|
||||||
|
* gcc -g -Wall try211.c `pkg-config vips --cflags --libs`
|
||||||
|
*/
|
||||||
|
|
||||||
|
#include <stdio.h>
|
||||||
|
#include <vips/vips.h>
|
||||||
|
|
||||||
|
int
|
||||||
|
main( int argc, char **argv )
|
||||||
|
{
|
||||||
|
GOptionContext *context;
|
||||||
|
GOptionGroup *main_group;
|
||||||
|
GError *error = NULL;
|
||||||
|
VipsImage *in;
|
||||||
|
double mean;
|
||||||
|
VipsImage *out;
|
||||||
|
|
||||||
|
if( vips_init( argv[0] ) )
|
||||||
|
vips_error_exit( NULL );
|
||||||
|
|
||||||
|
context = g_option_context_new( "hello infile outfile - VIPS demo" );
|
||||||
|
|
||||||
|
main_group = g_option_group_new( NULL, NULL, NULL, NULL, NULL );
|
||||||
|
g_option_context_set_main_group( context, main_group );
|
||||||
|
g_option_context_add_group( context, vips_get_option_group() );
|
||||||
|
|
||||||
|
if( !g_option_context_parse( context, &argc, &argv, &error ) ) {
|
||||||
|
if( error ) {
|
||||||
|
fprintf( stderr, "%s\n", error->message );
|
||||||
|
g_error_free( error );
|
||||||
|
}
|
||||||
|
|
||||||
|
vips_error_exit( NULL );
|
||||||
|
}
|
||||||
|
|
||||||
|
if( argc != 3 )
|
||||||
|
vips_error_exit( "usage: %s infile outfile", argv[0] );
|
||||||
|
|
||||||
|
if( !(in = vips_image_new_from_file( argv[1], NULL )) )
|
||||||
|
vips_error_exit( NULL );
|
||||||
|
|
||||||
|
printf( "image width = %d\n", vips_image_get_width( in ) );
|
||||||
|
|
||||||
|
if( vips_avg( in, &mean, NULL ) )
|
||||||
|
vips_error_exit( NULL );
|
||||||
|
|
||||||
|
printf( "mean pixel value = %g\n", mean );
|
||||||
|
|
||||||
|
if( vips_invert( in, &out, NULL ) )
|
||||||
|
vips_error_exit( NULL );
|
||||||
|
|
||||||
|
g_object_unref( in );
|
||||||
|
|
||||||
|
if( vips_image_write_to_file( out, argv[2], NULL ) )
|
||||||
|
vips_error_exit( NULL );
|
||||||
|
|
||||||
|
g_object_unref( out );
|
||||||
|
|
||||||
|
return( 0 );
|
||||||
|
}
|
||||||
|
</programlisting>
|
||||||
|
</example>
|
||||||
|
|
||||||
</refsect1>
|
</refsect1>
|
||||||
|
|
||||||
</refentry>
|
</refentry>
|
||||||
|
|
|
@ -63,9 +63,45 @@
|
||||||
*
|
*
|
||||||
* The image class and associated types and macros.
|
* The image class and associated types and macros.
|
||||||
*
|
*
|
||||||
* Images can be created from files on disc (with vips_image_new_from_file()),
|
* Images can be created from formatted files on disc, from C-style arrays on
|
||||||
* from formatted buffers held in memory (with vips_image_new_from_buffer()),
|
* disc, from formatted areas of memory, or from C-style arrays in memory. See
|
||||||
* and from C-style arrays held in memory (with vips_image_new_from_memory()).
|
* vips_image_new_from_file() and friends.
|
||||||
|
* Creating an image is fast. VIPS reads just enough of
|
||||||
|
* the image to be able to get the various properties, such as width in
|
||||||
|
* pixels. It delays reading any pixels until they are really needed.
|
||||||
|
*
|
||||||
|
* Once you have an image, you can get properties from it in the usual way.
|
||||||
|
* You can use projection functions, like vips_image_get_width() or
|
||||||
|
* g_object_get(), to get %GObject properties.
|
||||||
|
*
|
||||||
|
* VIPS images are three-dimensional arrays, the dimensions being width,
|
||||||
|
* height and bands. Each dimension can be up to 2 ** 31 pixels (or band
|
||||||
|
* elements). An image has a format, meaning the machine number type used
|
||||||
|
* to represent each value. VIPS supports 10 formats, from 8-bit unsigned
|
||||||
|
* integer up to 128-bit double complex, see vips_image_get_format()..
|
||||||
|
*
|
||||||
|
* In VIPS, images are uninterpreted arrays, meaning that from the point of
|
||||||
|
* view of most operations, they are just large collections of numbers.
|
||||||
|
* There's no difference between an RGBA (RGB with alpha) image and a CMYK
|
||||||
|
* image, for example, they are both just four-band images. It's up to the
|
||||||
|
* user of the library to pass the right sort of image to each operation.
|
||||||
|
*
|
||||||
|
* To take an example, VIPS has vips_Lab2XYZ(), an operation to transform
|
||||||
|
* an image from CIE LAB colour space to CIE XYZ space. It assumes the
|
||||||
|
* first three bands represent pixels in LAB colour space and returns an
|
||||||
|
* image where the first three bands are transformed to XYZ and any
|
||||||
|
* remaining bands are just copied. Pass it a RGB image by mistake and
|
||||||
|
* you'll just get nonsense.
|
||||||
|
*
|
||||||
|
* VIPS has a feature to help (a little) with this: it sets a
|
||||||
|
* #VipsInterpretation hint for each image (see
|
||||||
|
* vips_image_get_interpretation()); a hint which says how pixels should
|
||||||
|
* probably be interpreted. For example, vips_Lab2XYZ() will set the
|
||||||
|
* interpretation of the output image to #VIPS_INTERPRETATION_XYZ. A
|
||||||
|
* few utility operations will also use interpretation as a guide. For
|
||||||
|
* example, you can give vips_colourspace() an input image and a desired
|
||||||
|
* colourspace and it will use the input's interpretation hint to apply
|
||||||
|
* the best sequence of colourspace transforms to get to the desired space.
|
||||||
*
|
*
|
||||||
* Use things like vips_invert() to manipulate your images. When you are done,
|
* Use things like vips_invert() to manipulate your images. When you are done,
|
||||||
* you can write images to disc files (with vips_image_write_to_file()),
|
* you can write images to disc files (with vips_image_write_to_file()),
|
||||||
|
@ -77,7 +113,6 @@
|
||||||
* linkend="libvips-header">header</link> for getting and setting image
|
* linkend="libvips-header">header</link> for getting and setting image
|
||||||
* metadata. See <link linkend="VipsObject">object</link> for a discussion of
|
* metadata. See <link linkend="VipsObject">object</link> for a discussion of
|
||||||
* the lower levels.
|
* the lower levels.
|
||||||
*
|
|
||||||
*/
|
*/
|
||||||
|
|
||||||
/**
|
/**
|
||||||
|
|
Loading…
Reference in New Issue