From f4671f46e807db0e02d763e3a1685ad012eace5b Mon Sep 17 00:00:00 2001 From: John Cupitt Date: Fri, 25 Jul 2014 09:22:49 +0100 Subject: [PATCH] more work on docs started adding .xml intro to vips sections --- TODO | 3 + bootstrap.sh | 11 +- doc/reference/Makefile.am | 12 +- doc/reference/binding.xml | 550 +++++++++++++++++++++++++++ doc/reference/extending.xml | 550 +++++++++++++++++++++++++++ doc/reference/libvips-docs.sgml.in | 37 +- doc/reference/using-C.xml | 73 ++++ doc/reference/using-command-line.xml | 151 ++++++++ libvips/iofuncs/init.c | 4 + libvips/iofuncs/operation.c | 78 +++- 10 files changed, 1446 insertions(+), 23 deletions(-) create mode 100644 doc/reference/binding.xml create mode 100644 doc/reference/extending.xml create mode 100644 doc/reference/using-C.xml create mode 100644 doc/reference/using-command-line.xml diff --git a/TODO b/TODO index 31a7f8c5..c100aee6 100644 --- a/TODO +++ b/TODO @@ -1,3 +1,6 @@ +- vips_object_unref_outputs() needs docs ... bindings will need it + + - maxpos_avg seems to give variable results diff --git a/bootstrap.sh b/bootstrap.sh index 7f4dfe7d..b4348a52 100755 --- a/bootstrap.sh +++ b/bootstrap.sh @@ -13,7 +13,16 @@ rm -f swig/vipsCC/*.cxx rm -f swig/vipsCC/VImage.h rm -f swig/vipsCC/VImage.py python/vipsCC/VError.py python/vipsCC/VMask.py python/vipsCC/Display.py rm -f benchmark/temp* -( cd doc ; mkdir poop ; mv reference/libvips-docs.sgml.in poop ; mv reference/Makefile.am poop ; mv reference/images poop ; rm -rf reference/* ; mv poop/* reference ; rmdir poop ) +( cd doc ; \ + mkdir poop ; \ + mv reference/libvips-docs.sgml.in poop ; \ + mv reference/Makefile.am poop ; \ + mv reference/images poop ; \ + mv reference/*.xml poop ; \ + rm -rf reference/* ; \ + mv poop/* reference ; \ + rmdir poop \ +) # glib-gettextize asks us to copy these files to m4 if they aren't there # I don't have $ACDIR/isc-posix.m4, how mysterious diff --git a/doc/reference/Makefile.am b/doc/reference/Makefile.am index 9f69e115..2b577b31 100644 --- a/doc/reference/Makefile.am +++ b/doc/reference/Makefile.am @@ -134,12 +134,20 @@ HTML_IMAGES = \ # Extra SGML files that are included by $(DOC_MAIN_SGML_FILE). # e.g. content_files=running.sgml building.sgml changes-2.0.sgml -content_files= +content_files = \ + using-command-line.xml \ + using-C.xml \ + extending.xml \ + binding.xml # SGML files where gtk-doc abbrevations (#GtkWidget) are expanded # These files must be listed here *and* in content_files # e.g. expand_content_files=running.sgml -expand_content_files= +expand_content_files = \ + using-command-line.xml \ + using-C.xml \ + extending.xml \ + binding.xml # CFLAGS and LDFLAGS for compiling gtkdoc-scangobj with your library. # Only needed if you are using gtkdoc-scangobj to dynamically query widget diff --git a/doc/reference/binding.xml b/doc/reference/binding.xml new file mode 100644 index 00000000..105fca44 --- /dev/null +++ b/doc/reference/binding.xml @@ -0,0 +1,550 @@ + + + + + Compiling the GLib package + 3 + GLib Library + + + + Compiling the GLib Package + How to compile GLib itself + + + + Building the Library on UNIX + + On UNIX, GLib uses the standard GNU build system, + using autoconf for package + configuration and resolving portability issues, + automake for building makefiles + that comply with the GNU Coding Standards, and + libtool for building shared + libraries on multiple platforms. The normal sequence for + compiling and installing the GLib library is thus: + + + ./configure + make + make install + + + + + The standard options provided by GNU + autoconf may be passed to the + configure script. Please see the + autoconf documentation or run + ./configure --help for information about + the standard options. + + + The GTK+ documentation contains + further details + about the build process and ways to influence it. + + + + Dependencies + + 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 autoconf) are + pkg-config and GNU make. + + + + + pkg-config + is a tool for tracking the compilation flags needed for + libraries that are used by the GLib library. (For each + library, a small .pc 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 pkg-config + needed to build GLib is mirrored in the + dependencies directory + on the GTK+ FTP + site. + + + + + The GLib Makefiles make use of several features specific to + GNU + make, and will not build correctly with other + versions of make. You will need to + install it if you don't already have it on your system. (It + may be called gmake rather than + make.) + + + + + 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. + + + + + The GNU + libiconv library is needed to build GLib if your + system doesn't have the iconv() + function for doing conversion between character + encodings. Most modern systems should have + iconv(), however many older systems lack + an iconv() implementation. On such systems, + you must install the libiconv library. This can be found at: + http://www.gnu.org/software/libiconv. + + + If your system has an iconv() implementation but + you want to use libiconv instead, you can pass the + --with-libiconv option to configure. This forces + libiconv to be used. + + + Note that if you have libiconv installed in your default include + search path (for instance, in /usr/local/), but + don't enable it, you will get an error while compiling GLib because + the iconv.h that libiconv installs hides the + system iconv. + + + 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. + + + 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. + + + + + The libintl library from the GNU gettext + package is needed if your system doesn't have the + gettext() functionality for handling + message translation databases. + + + + + A thread implementation is needed. The thread support in GLib + can be based upon POSIX threads or win32 threads. + + + + + GRegex uses the PCRE library + 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 + to, but it is not recommended. + + + + + 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. + + + + + The optional SELinux support in GIO requires libselinux. + To build GLib without SELinux support, use the + option. + + + + + The optional support for DTrace requires the + sys/sdt.h header, which is provided + by SystemTap on Linux. To build GLib without DTrace, use + the configure option. + + + + + The optional support for + SystemTap + can be disabled with the + configure option. + + + + + + + Extra Configuration Options + + + In addition to the normal options, the + configure script in the GLib + library supports these additional arguments: + + + + <systemitem>--enable-debug</systemitem> + + + 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 + runtime debugging. + 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 + should not + be used for stable releases of GLib. + + + + + <systemitem>--disable-gc-friendly</systemitem> and + <systemitem>--enable-gc-friendly</systemitem> + + + By default, and with --disable-gc-friendly + 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 Valgrind 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 --enable-gc-friendly option makes Glib + clear memory in these situations: + + + + + + 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. + + + + + 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. + + + + + The above applies to GPtrArray as well. + + + + + 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. + + + + + 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. + + + + + + Since clearing the memory has a cost, + --disable-gc-friendly is the default. + + + + + <systemitem>--disable-mem-pools</systemitem> and + <systemitem>--enable-mem-pools</systemitem> + + + 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 g_malloc() + and g_free() functions. Code currently affected by + this: + + + + GMemChunks become basically non-effective + + + + + GSignal disables all caching + (potentially very slow) + + + + + GType doesn't honour the + GTypeInfo + n_preallocs field anymore + + + + + the GBSearchArray flag + G_BSEARCH_ALIGN_POWER2 becomes non-functional + + + + + + + + <systemitem>--with-threads</systemitem> + + + Specify a thread implementation to use. Available options are + 'posix' or 'win32'. Normally, configure + should be able to work out the system threads API on its own. + + + + + <systemitem>--disable-regex</systemitem> and + <systemitem>--enable-regex</systemitem> + + + 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. + + + + + <systemitem>--with-pcre</systemitem> + + + Specify whether to use the internal or the system-supplied + PCRE library. + + + + 'internal' means that GRegex will be compiled to use + the internal PCRE library. + + + + + 'system' means that GRegex will be compiled to use + the system-supplied PCRE library. + + + + Using the internal PCRE is the preferred solution: + + + + System-supplied PCRE has a separated copy of the big tables + used for Unicode handling. + + + + + Some systems have PCRE libraries compiled without some needed + features, such as UTF-8 and Unicode support. + + + + + 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. + + + + + + + + <systemitem>--disable-included-printf</systemitem> and + <systemitem>--enable-included-printf</systemitem> + + + By default the configure script will try + to auto-detect whether the C library provides a suitable set + of printf() functions. In detail, configure + 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. + + + These options can be used to explicitly control whether + an implementation of the printf() family should be included or not. + + + + + <systemitem>--disable-Bsymbolic</systemitem> and + <systemitem>--enable-Bsymbolic</systemitem> + + + 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 + LD_PRELOAD. Therefore, it may make + sense to turn this feature off in some situations. + The option allows + to do that. + + + + + <systemitem>--disable-gtk-doc</systemitem> and + <systemitem>--enable-gtk-doc</systemitem> + + + By default the configure script will try + to auto-detect whether the + gtk-doc 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 + gtk-doc 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. + + + + + <systemitem>--disable-man</systemitem> and + <systemitem>--enable-man</systemitem> + + + By default the configure script will try + to auto-detect whether xsltproc + 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. + + + + + <systemitem>--disable-xattr</systemitem> and + <systemitem>--enable-xattr</systemitem> + + + By default the configure 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. + + + + + <systemitem>--disable-selinux</systemitem> and + <systemitem>--enable-selinux</systemitem> + + + By default the configure 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. + + + + + <systemitem>--disable-dtrace</systemitem> and + <systemitem>--enable-dtrace</systemitem> + + + By default the configure script will + detect if DTrace support is available, and use it. + + + + + <systemitem>--disable-systemtap</systemitem> and + <systemitem>--enable-systemtap</systemitem> + + + This option requires DTrace support. If it is available, then + the configure script will also check for + the presence of SystemTap. + + + + + <systemitem>--enable-gcov</systemitem> and + <systemitem>--disable-gcov</systemitem> + + + Enable the generation of coverage reports for the GLib tests. + This requires the lcov frontend to gcov from the + Linux Test Project. + To generate a coverage report, use the lcov make target. The + report is placed in the glib-lcov directory. + + + + + <systemitem>--with-runtime-libdir=RELPATH</systemitem> + + + 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. /usr + is mounted. + For example, if LIBDIR is /usr/lib and + ../../lib is passed to + --with-runtime-libdir then the + runtime libraries are installed into /lib rather + than /usr/lib. + + + + + <systemitem>--with-python</systemitem> + + + 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. + + + + + diff --git a/doc/reference/extending.xml b/doc/reference/extending.xml new file mode 100644 index 00000000..105fca44 --- /dev/null +++ b/doc/reference/extending.xml @@ -0,0 +1,550 @@ + + + + + Compiling the GLib package + 3 + GLib Library + + + + Compiling the GLib Package + How to compile GLib itself + + + + Building the Library on UNIX + + On UNIX, GLib uses the standard GNU build system, + using autoconf for package + configuration and resolving portability issues, + automake for building makefiles + that comply with the GNU Coding Standards, and + libtool for building shared + libraries on multiple platforms. The normal sequence for + compiling and installing the GLib library is thus: + + + ./configure + make + make install + + + + + The standard options provided by GNU + autoconf may be passed to the + configure script. Please see the + autoconf documentation or run + ./configure --help for information about + the standard options. + + + The GTK+ documentation contains + further details + about the build process and ways to influence it. + + + + Dependencies + + 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 autoconf) are + pkg-config and GNU make. + + + + + pkg-config + is a tool for tracking the compilation flags needed for + libraries that are used by the GLib library. (For each + library, a small .pc 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 pkg-config + needed to build GLib is mirrored in the + dependencies directory + on the GTK+ FTP + site. + + + + + The GLib Makefiles make use of several features specific to + GNU + make, and will not build correctly with other + versions of make. You will need to + install it if you don't already have it on your system. (It + may be called gmake rather than + make.) + + + + + 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. + + + + + The GNU + libiconv library is needed to build GLib if your + system doesn't have the iconv() + function for doing conversion between character + encodings. Most modern systems should have + iconv(), however many older systems lack + an iconv() implementation. On such systems, + you must install the libiconv library. This can be found at: + http://www.gnu.org/software/libiconv. + + + If your system has an iconv() implementation but + you want to use libiconv instead, you can pass the + --with-libiconv option to configure. This forces + libiconv to be used. + + + Note that if you have libiconv installed in your default include + search path (for instance, in /usr/local/), but + don't enable it, you will get an error while compiling GLib because + the iconv.h that libiconv installs hides the + system iconv. + + + 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. + + + 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. + + + + + The libintl library from the GNU gettext + package is needed if your system doesn't have the + gettext() functionality for handling + message translation databases. + + + + + A thread implementation is needed. The thread support in GLib + can be based upon POSIX threads or win32 threads. + + + + + GRegex uses the PCRE library + 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 + to, but it is not recommended. + + + + + 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. + + + + + The optional SELinux support in GIO requires libselinux. + To build GLib without SELinux support, use the + option. + + + + + The optional support for DTrace requires the + sys/sdt.h header, which is provided + by SystemTap on Linux. To build GLib without DTrace, use + the configure option. + + + + + The optional support for + SystemTap + can be disabled with the + configure option. + + + + + + + Extra Configuration Options + + + In addition to the normal options, the + configure script in the GLib + library supports these additional arguments: + + + + <systemitem>--enable-debug</systemitem> + + + 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 + runtime debugging. + 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 + should not + be used for stable releases of GLib. + + + + + <systemitem>--disable-gc-friendly</systemitem> and + <systemitem>--enable-gc-friendly</systemitem> + + + By default, and with --disable-gc-friendly + 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 Valgrind 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 --enable-gc-friendly option makes Glib + clear memory in these situations: + + + + + + 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. + + + + + 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. + + + + + The above applies to GPtrArray as well. + + + + + 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. + + + + + 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. + + + + + + Since clearing the memory has a cost, + --disable-gc-friendly is the default. + + + + + <systemitem>--disable-mem-pools</systemitem> and + <systemitem>--enable-mem-pools</systemitem> + + + 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 g_malloc() + and g_free() functions. Code currently affected by + this: + + + + GMemChunks become basically non-effective + + + + + GSignal disables all caching + (potentially very slow) + + + + + GType doesn't honour the + GTypeInfo + n_preallocs field anymore + + + + + the GBSearchArray flag + G_BSEARCH_ALIGN_POWER2 becomes non-functional + + + + + + + + <systemitem>--with-threads</systemitem> + + + Specify a thread implementation to use. Available options are + 'posix' or 'win32'. Normally, configure + should be able to work out the system threads API on its own. + + + + + <systemitem>--disable-regex</systemitem> and + <systemitem>--enable-regex</systemitem> + + + 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. + + + + + <systemitem>--with-pcre</systemitem> + + + Specify whether to use the internal or the system-supplied + PCRE library. + + + + 'internal' means that GRegex will be compiled to use + the internal PCRE library. + + + + + 'system' means that GRegex will be compiled to use + the system-supplied PCRE library. + + + + Using the internal PCRE is the preferred solution: + + + + System-supplied PCRE has a separated copy of the big tables + used for Unicode handling. + + + + + Some systems have PCRE libraries compiled without some needed + features, such as UTF-8 and Unicode support. + + + + + 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. + + + + + + + + <systemitem>--disable-included-printf</systemitem> and + <systemitem>--enable-included-printf</systemitem> + + + By default the configure script will try + to auto-detect whether the C library provides a suitable set + of printf() functions. In detail, configure + 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. + + + These options can be used to explicitly control whether + an implementation of the printf() family should be included or not. + + + + + <systemitem>--disable-Bsymbolic</systemitem> and + <systemitem>--enable-Bsymbolic</systemitem> + + + 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 + LD_PRELOAD. Therefore, it may make + sense to turn this feature off in some situations. + The option allows + to do that. + + + + + <systemitem>--disable-gtk-doc</systemitem> and + <systemitem>--enable-gtk-doc</systemitem> + + + By default the configure script will try + to auto-detect whether the + gtk-doc 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 + gtk-doc 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. + + + + + <systemitem>--disable-man</systemitem> and + <systemitem>--enable-man</systemitem> + + + By default the configure script will try + to auto-detect whether xsltproc + 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. + + + + + <systemitem>--disable-xattr</systemitem> and + <systemitem>--enable-xattr</systemitem> + + + By default the configure 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. + + + + + <systemitem>--disable-selinux</systemitem> and + <systemitem>--enable-selinux</systemitem> + + + By default the configure 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. + + + + + <systemitem>--disable-dtrace</systemitem> and + <systemitem>--enable-dtrace</systemitem> + + + By default the configure script will + detect if DTrace support is available, and use it. + + + + + <systemitem>--disable-systemtap</systemitem> and + <systemitem>--enable-systemtap</systemitem> + + + This option requires DTrace support. If it is available, then + the configure script will also check for + the presence of SystemTap. + + + + + <systemitem>--enable-gcov</systemitem> and + <systemitem>--disable-gcov</systemitem> + + + Enable the generation of coverage reports for the GLib tests. + This requires the lcov frontend to gcov from the + Linux Test Project. + To generate a coverage report, use the lcov make target. The + report is placed in the glib-lcov directory. + + + + + <systemitem>--with-runtime-libdir=RELPATH</systemitem> + + + 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. /usr + is mounted. + For example, if LIBDIR is /usr/lib and + ../../lib is passed to + --with-runtime-libdir then the + runtime libraries are installed into /lib rather + than /usr/lib. + + + + + <systemitem>--with-python</systemitem> + + + 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. + + + + + diff --git a/doc/reference/libvips-docs.sgml.in b/doc/reference/libvips-docs.sgml.in index 4996f20b..f8254d3b 100644 --- a/doc/reference/libvips-docs.sgml.in +++ b/doc/reference/libvips-docs.sgml.in @@ -11,22 +11,44 @@ For VIPS @VIPS_VERSION@. The latest version of this documentation can be found on the VIPS website. + url="http://http://www.vips.ecs.soton.ac.uk/index.php?title=Documentation">VIPS website. + + VIPS Overview + + VIPS is a free image processing system. It is good with large + images (images larger than the amount of RAM you have available), with + many CPUs (speed scales linearly to at least 32 threads), for working + with colour, for scientific analysis and for general research + and development. As well as JPEG, TIFF and PNG images, it also + supports scientific formats like FITS, Matlab, Analyze, PFM, + Radiance and OpenSlide. It works on many UNIX-like platforms, + as well as Windows and OS X. VIPS is released under the GNU Library + General Public License (GNU LGPL). + + + + + + + + Core VIPS API + - - + - - - - + + + + + + @@ -63,6 +85,7 @@ API Index + diff --git a/doc/reference/using-C.xml b/doc/reference/using-C.xml new file mode 100644 index 00000000..f06e7acc --- /dev/null +++ b/doc/reference/using-C.xml @@ -0,0 +1,73 @@ + + + + + Using VIPS from C + 3 + VIPS Library + + + + Using VIPS + How to use the VIPS library + + + + Using VIPS from C + + VIPS comes with a convenient, high-level C API. You should read the API + docs for full details, but this section will try to give a brief + overview. The vips program is handy for getting a + summary of an operation's parameters. + + When your program starts, use vips_init() to set up + the VIPS library. You should pass it the name of your program, usually + argv[0]. Use vips_shutdown() + when you exit. + + You can add the VIPS flags to your GObject command-line processing + with vips_get_option_group(), see below. + + 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. + + 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 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. + If you pass an image to an operation and that operation needs to keep a + 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 + + + + + diff --git a/doc/reference/using-command-line.xml b/doc/reference/using-command-line.xml new file mode 100644 index 00000000..b097a166 --- /dev/null +++ b/doc/reference/using-command-line.xml @@ -0,0 +1,151 @@ + + + + + VIPS from the command-line + 1 + VIPS Library + + + + Using VIPS + How to use the VIPS library + + + + Using VIPS from the command-line + + Use the vips command to execute VIPS operations from + the command-line. You can show all classes with: + + + vips list classes + + + This produces output something like: + + + VipsOperation (operation), operations + VipsSystem (system), run an external command + VipsArithmetic (arithmetic), arithmetic operations + VipsBinary (binary), binary operations + VipsAdd (add), add two images + .... and so on + + + Each line shows the canonical name of the class (for example + VipsAdd), the class nickname + (add in this case), and a short description. + Some subclasses of operation will show more, for example subclasses of + VipsForeign will show some of the extra flags + supported by the file load/save operations. + + You can get help on a specific operation by running it with no arguments, + for example: + + + vips gamma + + + produces the output: + + + gamma an image + usage: + gamma in out + where: + in - Input image, input VipsImage + out - Output image, output VipsImage + optional arguments: + exponent - Gamma factor, input gdouble + operation flags: sequential-unbuffered + + + vips gamma applies a gamma factor to an image. By + default, it uses 2.4, the sRGB gamma factor, but you can specify any + gamma with the exponent option. You can use the + C API docs for vips_gamma() if you need more + information. + + Use it from the command-line like this: + + + vips gamma k2.jpg x.jpg --exponent 0.42 + + + This will read file k2.jpg, un-gamma it, and + write the result to file x.jpg. + + Some operations take arrays of values as arguments, for example, + vips affine needs an array of four numbers for the + 2x2 transform matrix. You pass arrays as space-separated lists, for + example: + + + vips affine k2.jpg x.jpg "2 0 0 1" + + + Or vips bandjoin needs an array of input images to + join, run it like this: + + + vips bandjoin "k2.jpg k4.jpg" x.tif + + + vips will automatically convert between image file + formats for you. Input images are detected by sniffing their first few + bytes; output formats are set from the filename suffix. You can see a + list of all the supported file formats with something like: + + + vips list classes | grep -i foreign + + + Then get a list of the options a format supports with, for example: + + + vips jpegsave + + + You can pass options to the implicit load and save operations enclosed + in square brackets after the filename. For example: + + + vips affine k2.jpg x.jpg[Q=90,strip] "2 0 0 1" + + + Will write x.jpg at quality level 90 and will + strip all metadata from the image. + + Finally, vips has a couple of useful extra options. + + + + + Use to get + vips to display a simple progress indicator. + + + + + + Use and vips will + leak-test on exit, and also display an estimate of peak memory use. + + + + + + + VIPS comes with a couple of other useful programs. + vipsheader is a command which can print image header + fields. vipsedit can change fields in vips format + images. vipsthumbnail can make image thumbnails + quickly. + + + + + diff --git a/libvips/iofuncs/init.c b/libvips/iofuncs/init.c index 8c8311bb..3cf907e9 100644 --- a/libvips/iofuncs/init.c +++ b/libvips/iofuncs/init.c @@ -131,6 +131,10 @@ vips_get_argv0( void ) * * * + * checks that the libvips your program is expecting is + * binary-compatible with the vips library you're running against + * + * * initialises any libraries that VIPS is using, including GObject * and the threading system, if neccessary * diff --git a/libvips/iofuncs/operation.c b/libvips/iofuncs/operation.c index ffbeff03..049c8859 100644 --- a/libvips/iofuncs/operation.c +++ b/libvips/iofuncs/operation.c @@ -63,24 +63,46 @@ * It also maintains a cache of recent operations. You can tune the cache * behaviour in various ways, see vips_cache_set_max() and friends. * - * Use vips_call() to call any vips operation from C. For example: + * vips_call(), vips_call_split() and vips_call_split_option_string() are used + * by vips to implement the C API. They can execute any #VipsOperation, + * passing in a set of required and optional arguments. Normally you would not + * use these functions directly: every operation has a tiny wrapper function + * which provides type-safety for the required arguments. For example, + * vips_embed() is defined as: * * |[ - * VipsImage *in = ... - * VipsImaghe *out; + * int + * vips_embed( VipsImage *in, VipsImage **out, + * int x, int y, int width, int height, ... ) + * { + * va_list ap; + * int result; * - * if( vips_call( "embed", in, &out, 10, 10, 100, 100, - * "extend", VIPS_EXTEND_COPY, - * NULL ) ) - * ... + * va_start( ap, height ); + * result = vips_call_split( "embed", ap, in, out, x, y, width, height ); + * va_end( ap ); + * + * return( result ); + * } * ]| * - * Will execute vips_embed() setting the optional `extend` property to - * #VIPS_EXTEND_COPY. + * If you are writing a language binding, you won't need these. Instead, make + * a new operation with vips_operation_new() (all it does is look up the + * operation by name with vips_type_find(), then call g_object_new() for you), + * then use vips_argument_map() and friends to loop over the operation's + * arguments setting them. Once you have set all arguments, use + * vips_cache_operation_build() to look up the operation in the cache and + * either build or dup it. If something goes wrong, you'll need to use + * vips_object_unref_outputs() and g_object_unref(). :wq * - * If you want to search for operations, see what arguments they need, and - * test argument properties, see - * object. + + + * + * Use vips_call() to call any vips operation from C. If you want to search + * for operations, see what arguments they need, and test argument + * properties, see + * object. Each operation also has a + * wrapper function, of course, to give type safety for required arguments. * * vips_call_split() lets you run an operation with the optional and required * arguments split into separate lists. vips_call_split_option_string() lets @@ -752,6 +774,36 @@ vips_call_by_name( const char *operation_name, return( result ); } +/** + * vips_call: + * @operation_name: + * @...: required args, then a %NULL-terminated list of argument/value pairs + * + * vips_call() calls the named operation, passing in required arguments, and + * then setting any optional ones from the remainder of the arguments as a set + * of name/value pairs. + * + * For example, vips_embed() takes six required arguments, @in, @out, @x, @y, + * @width, @height; and has two optional arguments, @extend and @background. + * You can run it with vips_call() like this: + * + * |[ + * VipsImage *in = ... + * VipsImage *out; + * + * if( vips_call( "embed", in, &out, 10, 10, 100, 100, + * "extend", VIPS_EXTEND_COPY, + * NULL ) ) + * ... error + * ]| + * + * Normally of course you'd just use the vips_embed() wrapper function and get + * type-safety for the required arguments. + * + * See also: vips_call_split(), vips_call_options(). + * + * Returns: 0 on success, -1 on error + */ int vips_call( const char *operation_name, ... ) { @@ -760,7 +812,7 @@ vips_call( const char *operation_name, ... ) va_list required; va_list optional; - if( !(operation = vips_operation_new( operation_name ) ) ) + if( !(operation = vips_operation_new( operation_name )) ) return( -1 ); /* We have to break the va_list into separate required and optional