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"
|
||||
"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
|
||||
]>
|
||||
<refentry id="glib-building">
|
||||
<refentry id="binding">
|
||||
<refmeta>
|
||||
<refentrytitle>Compiling the GLib package</refentrytitle>
|
||||
<refentrytitle>Writing bindings for libvips</refentrytitle>
|
||||
<manvolnum>3</manvolnum>
|
||||
<refmiscinfo>GLib Library</refmiscinfo>
|
||||
<refmiscinfo>VIPS Library</refmiscinfo>
|
||||
</refmeta>
|
||||
|
||||
<refnamediv>
|
||||
<refname>Compiling the GLib Package</refname>
|
||||
<refpurpose>How to compile GLib itself</refpurpose>
|
||||
<refname>Binding</refname>
|
||||
<refpurpose>How to write bindings for libvips</refpurpose>
|
||||
</refnamediv>
|
||||
|
||||
<refsect1 id="building">
|
||||
<title>Building the Library on UNIX</title>
|
||||
<refsect1 id="binding-goi">
|
||||
<title>Binding and gobject-introspection</title>
|
||||
<para>
|
||||
On UNIX, GLib uses the standard GNU build system,
|
||||
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>
|
||||
Stuff about goi.
|
||||
</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>
|
||||
|
||||
</refentry>
|
||||
|
@ -2,549 +2,23 @@
|
||||
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
|
||||
"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
|
||||
]>
|
||||
<refentry id="glib-building">
|
||||
<refentry id="extending">
|
||||
<refmeta>
|
||||
<refentrytitle>Compiling the GLib package</refentrytitle>
|
||||
<refentrytitle>Extending VIPS</refentrytitle>
|
||||
<manvolnum>3</manvolnum>
|
||||
<refmiscinfo>GLib Library</refmiscinfo>
|
||||
<refmiscinfo>VIPS Library</refmiscinfo>
|
||||
</refmeta>
|
||||
|
||||
<refnamediv>
|
||||
<refname>Compiling the GLib Package</refname>
|
||||
<refpurpose>How to compile GLib itself</refpurpose>
|
||||
<refname>Extending</refname>
|
||||
<refpurpose>How to add operations to VIPS</refpurpose>
|
||||
</refnamediv>
|
||||
|
||||
<refsect1 id="building">
|
||||
<title>Building the Library on UNIX</title>
|
||||
<refsect1 id="extending-subclassing">
|
||||
<title>Adding operations to VIPS</title>
|
||||
<para>
|
||||
On UNIX, GLib uses the standard GNU build system,
|
||||
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>
|
||||
all about subclassing.
|
||||
</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>
|
||||
|
||||
</refentry>
|
||||
|
@ -21,27 +21,41 @@
|
||||
docs for full details, but this section will try to give a brief
|
||||
overview. The <command>vips</command> program is handy for getting a
|
||||
summary of an operation's parameters.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
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
|
||||
<literal>argv[0]</literal>. Use <function>vips_shutdown()</function>
|
||||
when you exit.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
You can add the VIPS flags to your GObject command-line processing
|
||||
with vips_get_option_group(), see below.
|
||||
</para>
|
||||
|
||||
The basic data object is #VipsImage. You can create an image from a
|
||||
file on disc or from an area of memory, either as a C-style array,
|
||||
or as a formatted object, like JPEG. See vips_image_new_from_file() and
|
||||
friends.
|
||||
Loading an 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>
|
||||
The basic data object is the #VipsImage, see <link
|
||||
linkend="VipsImage">VIPS Image</link> for details on the
|
||||
image class. You can create an image from a file on disc or from an
|
||||
area of memory, either as a C-style array, or as a formatted object,
|
||||
like JPEG. See vips_image_new_from_file() and friends. Loading an
|
||||
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.
|
||||
You can use projection functions like vips_image_get_width(), or
|
||||
g_object_get() to get GObject properties.
|
||||
You can use projection functions, like vips_image_get_width() or
|
||||
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_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.
|
||||
@ -49,25 +63,89 @@
|
||||
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
|
||||
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>
|
||||
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>
|
||||
|
||||
</refentry>
|
||||
|
@ -63,9 +63,45 @@
|
||||
*
|
||||
* The image class and associated types and macros.
|
||||
*
|
||||
* Images can be created from files on disc (with vips_image_new_from_file()),
|
||||
* from formatted buffers held in memory (with vips_image_new_from_buffer()),
|
||||
* and from C-style arrays held in memory (with vips_image_new_from_memory()).
|
||||
* Images can be created from formatted files on disc, from C-style arrays on
|
||||
* disc, from formatted areas of memory, or from C-style arrays in memory. See
|
||||
* 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,
|
||||
* 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
|
||||
* metadata. See <link linkend="VipsObject">object</link> for a discussion of
|
||||
* the lower levels.
|
||||
*
|
||||
*/
|
||||
|
||||
/**
|
||||
|
Loading…
x
Reference in New Issue
Block a user