mirror of
https://gitlab.gnome.org/GNOME/glib.git
synced 2024-12-24 14:36:13 +01:00
docs: Move the GResource SECTION
Move it to the struct docs. Signed-off-by: Philip Withnall <philip@tecnocode.co.uk> Helps: #3037
This commit is contained in:
Philip Withnall
parent
bbb5479d5a
commit
b0b5ed8c34
193
gio/gresource.c
193
gio/gresource.c
@ -48,69 +48,72 @@ static void register_lazy_static_resources (void);
|
||||
G_DEFINE_BOXED_TYPE (GResource, g_resource, g_resource_ref, g_resource_unref)
|
||||
|
||||
/**
|
||||
* SECTION:gresource
|
||||
* @short_description: Resource framework
|
||||
* @include: gio/gio.h
|
||||
* GResource:
|
||||
*
|
||||
* Applications and libraries often contain binary or textual data that is
|
||||
* really part of the application, rather than user data. For instance
|
||||
* #GtkBuilder .ui files, splashscreen images, GMenu markup XML, CSS files,
|
||||
* icons, etc. These are often shipped as files in `$datadir/appname`, or
|
||||
* manually included as literal strings in the code.
|
||||
* [class@Gtk.Builder] `.ui` files, splashscreen images, [class@Gio.Menu] markup
|
||||
* XML, CSS files, icons, etc. These are often shipped as files in
|
||||
* `$datadir/appname`, or manually included as literal strings in the code.
|
||||
*
|
||||
* The #GResource API and the [glib-compile-resources][glib-compile-resources] program
|
||||
* provide a convenient and efficient alternative to this which has some nice properties. You
|
||||
* maintain the files as normal files, so its easy to edit them, but during the build the files
|
||||
* are combined into a binary bundle that is linked into the executable. This means that loading
|
||||
* the resource files are efficient (as they are already in memory, shared with other instances) and
|
||||
* simple (no need to check for things like I/O errors or locate the files in the filesystem). It
|
||||
* The `GResource` API and the
|
||||
* [`glib-compile-resources`](glib-compile-resources.html) program provide a
|
||||
* convenient and efficient alternative to this which has some nice properties.
|
||||
* You maintain the files as normal files, so it’s easy to edit them, but during
|
||||
* the build the files are combined into a binary bundle that is linked into the
|
||||
* executable. This means that loading the resource files are efficient (as they
|
||||
* are already in memory, shared with other instances) and simple (no need to
|
||||
* check for things like I/O errors or locate the files in the filesystem). It
|
||||
* also makes it easier to create relocatable applications.
|
||||
*
|
||||
* Resource files can also be marked as compressed. Such files will be included in the resource bundle
|
||||
* in a compressed form, but will be automatically uncompressed when the resource is used. This
|
||||
* is very useful e.g. for larger text files that are parsed once (or rarely) and then thrown away.
|
||||
* Resource files can also be marked as compressed. Such files will be included
|
||||
* in the resource bundle in a compressed form, but will be automatically
|
||||
* uncompressed when the resource is used. This is very useful e.g. for larger
|
||||
* text files that are parsed once (or rarely) and then thrown away.
|
||||
*
|
||||
* Resource files can also be marked to be preprocessed, by setting the value of the
|
||||
* `preprocess` attribute to a comma-separated list of preprocessing options.
|
||||
* The only options currently supported are:
|
||||
*
|
||||
* `xml-stripblanks` which will use the xmllint command
|
||||
* to strip ignorable whitespace from the XML file. For this to work,
|
||||
* the `XMLLINT` environment variable must be set to the full path to
|
||||
* the xmllint executable, or xmllint must be in the `PATH`; otherwise
|
||||
* the preprocessing step is skipped.
|
||||
* - `xml-stripblanks` which will use the [`xmllint`](man:xmllint(1)) command
|
||||
* to strip ignorable whitespace from the XML file. For this to work,
|
||||
* the `XMLLINT` environment variable must be set to the full path to
|
||||
* the xmllint executable, or xmllint must be in the `PATH`; otherwise
|
||||
* the preprocessing step is skipped.
|
||||
*
|
||||
* `to-pixdata` (deprecated since gdk-pixbuf 2.32) which will use the
|
||||
* `gdk-pixbuf-pixdata` command to convert images to the #GdkPixdata format,
|
||||
* which allows you to create pixbufs directly using the data inside the
|
||||
* resource file, rather than an (uncompressed) copy of it. For this, the
|
||||
* `gdk-pixbuf-pixdata` program must be in the `PATH`, or the
|
||||
* `GDK_PIXBUF_PIXDATA` environment variable must be set to the full path to the
|
||||
* `gdk-pixbuf-pixdata` executable; otherwise the resource compiler will abort.
|
||||
* `to-pixdata` has been deprecated since gdk-pixbuf 2.32, as #GResource
|
||||
* supports embedding modern image formats just as well. Instead of using it,
|
||||
* embed a PNG or SVG file in your #GResource.
|
||||
* - `to-pixdata` (deprecated since gdk-pixbuf 2.32) which will use the
|
||||
* `gdk-pixbuf-pixdata` command to convert images to the [class@Gdk.Pixdata]
|
||||
* format, which allows you to create pixbufs directly using the data inside
|
||||
* the resource file, rather than an (uncompressed) copy of it. For this, the
|
||||
* `gdk-pixbuf-pixdata` program must be in the `PATH`, or the
|
||||
* `GDK_PIXBUF_PIXDATA` environment variable must be set to the full path to
|
||||
* the `gdk-pixbuf-pixdata` executable; otherwise the resource compiler will
|
||||
* abort. `to-pixdata` has been deprecated since gdk-pixbuf 2.32, as
|
||||
* `GResource` supports embedding modern image formats just as well. Instead
|
||||
* of using it, embed a PNG or SVG file in your `GResource`.
|
||||
*
|
||||
* `json-stripblanks` which will use the `json-glib-format` command to strip
|
||||
* ignorable whitespace from the JSON file. For this to work, the
|
||||
* `JSON_GLIB_FORMAT` environment variable must be set to the full path to the
|
||||
* `json-glib-format` executable, or it must be in the `PATH`;
|
||||
* otherwise the preprocessing step is skipped. In addition, at least version
|
||||
* 1.6 of `json-glib-format` is required.
|
||||
* - `json-stripblanks` which will use the
|
||||
* [`json-glib-format`](man:json-glib-format(1)) command to strip ignorable
|
||||
* whitespace from the JSON file. For this to work, the `JSON_GLIB_FORMAT`
|
||||
* environment variable must be set to the full path to the
|
||||
* `json-glib-format` executable, or it must be in the `PATH`; otherwise the
|
||||
* preprocessing step is skipped. In addition, at least version 1.6 of
|
||||
* `json-glib-format` is required.
|
||||
*
|
||||
* Resource files will be exported in the GResource namespace using the
|
||||
* Resource files will be exported in the `GResource` namespace using the
|
||||
* combination of the given `prefix` and the filename from the `file` element.
|
||||
* The `alias` attribute can be used to alter the filename to expose them at a
|
||||
* different location in the resource namespace. Typically, this is used to
|
||||
* include files from a different source directory without exposing the source
|
||||
* directory in the resource namespace, as in the example below.
|
||||
*
|
||||
* Resource bundles are created by the [glib-compile-resources][glib-compile-resources] program
|
||||
* which takes an XML file that describes the bundle, and a set of files that the XML references. These
|
||||
* are combined into a binary resource bundle.
|
||||
* Resource bundles are created by the
|
||||
* [`glib-compile-resources`](glib-compile-resources.html) program
|
||||
* which takes an XML file that describes the bundle, and a set of files that
|
||||
* the XML references. These are combined into a binary resource bundle.
|
||||
*
|
||||
* An example resource description:
|
||||
* |[
|
||||
* ```xml
|
||||
* <?xml version="1.0" encoding="UTF-8"?>
|
||||
* <gresources>
|
||||
* <gresource prefix="/org/gtk/Example">
|
||||
@ -120,74 +123,92 @@ G_DEFINE_BOXED_TYPE (GResource, g_resource, g_resource_ref, g_resource_unref)
|
||||
* <file alias="example.css">data/example.css</file>
|
||||
* </gresource>
|
||||
* </gresources>
|
||||
* ]|
|
||||
* ```
|
||||
*
|
||||
* This will create a resource bundle with the following files:
|
||||
* |[
|
||||
* ```
|
||||
* /org/gtk/Example/data/splashscreen.png
|
||||
* /org/gtk/Example/dialog.ui
|
||||
* /org/gtk/Example/menumarkup.xml
|
||||
* /org/gtk/Example/example.css
|
||||
* ]|
|
||||
* ```
|
||||
*
|
||||
* Note that all resources in the process share the same namespace, so use Java-style
|
||||
* path prefixes (like in the above example) to avoid conflicts.
|
||||
* Note that all resources in the process share the same namespace, so use
|
||||
* Java-style path prefixes (like in the above example) to avoid conflicts.
|
||||
*
|
||||
* You can then use [glib-compile-resources][glib-compile-resources] to compile the XML to a
|
||||
* binary bundle that you can load with g_resource_load(). However, its more common to use the --generate-source and
|
||||
* --generate-header arguments to create a source file and header to link directly into your application.
|
||||
* You can then use [`glib-compile-resources`](glib-compile-resources.html) to
|
||||
* compile the XML to a binary bundle that you can load with
|
||||
* [func@Gio.Resource.load]. However, it’s more common to use the
|
||||
* `--generate-source` and `--generate-header` arguments to create a source file
|
||||
* and header to link directly into your application.
|
||||
* This will generate `get_resource()`, `register_resource()` and
|
||||
* `unregister_resource()` functions, prefixed by the `--c-name` argument passed
|
||||
* to [glib-compile-resources][glib-compile-resources]. `get_resource()` returns
|
||||
* the generated #GResource object. The register and unregister functions
|
||||
* register the resource so its files can be accessed using
|
||||
* g_resources_lookup_data().
|
||||
* to [`glib-compile-resources`](glib-compile-resources.html). `get_resource()`
|
||||
* returns the generated `GResource` object. The register and unregister
|
||||
* functions register the resource so its files can be accessed using
|
||||
* [func@Gio.resources_lookup_data].
|
||||
*
|
||||
* Once a #GResource has been created and registered all the data in it can be accessed globally in the process by
|
||||
* using API calls like g_resources_open_stream() to stream the data or g_resources_lookup_data() to get a direct pointer
|
||||
* to the data. You can also use URIs like "resource:///org/gtk/Example/data/splashscreen.png" with #GFile to access
|
||||
* the resource data.
|
||||
* Once a `GResource` has been created and registered all the data in it can be
|
||||
* accessed globally in the process by using API calls like
|
||||
* [func@Gio.resources_open_stream] to stream the data or
|
||||
* [func@Gio.resources_lookup_data] to get a direct pointer to the data. You can
|
||||
* also use URIs like `resource:///org/gtk/Example/data/splashscreen.png` with
|
||||
* [iface@Gio.File] to access the resource data.
|
||||
*
|
||||
* Some higher-level APIs, such as #GtkApplication, will automatically load
|
||||
* resources from certain well-known paths in the resource namespace as a
|
||||
* Some higher-level APIs, such as [class@Gtk.Application], will automatically
|
||||
* load resources from certain well-known paths in the resource namespace as a
|
||||
* convenience. See the documentation for those APIs for details.
|
||||
*
|
||||
* There are two forms of the generated source, the default version uses the compiler support for constructor
|
||||
* and destructor functions (where available) to automatically create and register the #GResource on startup
|
||||
* or library load time. If you pass `--manual-register`, two functions to register/unregister the resource are created
|
||||
* instead. This requires an explicit initialization call in your application/library, but it works on all platforms,
|
||||
* even on the minor ones where constructors are not supported. (Constructor support is available for at least Win32, Mac OS and Linux.)
|
||||
* There are two forms of the generated source, the default version uses the
|
||||
* compiler support for constructor and destructor functions (where available)
|
||||
* to automatically create and register the `GResource` on startup or library
|
||||
* load time. If you pass `--manual-register`, two functions to
|
||||
* register/unregister the resource are created instead. This requires an
|
||||
* explicit initialization call in your application/library, but it works on all
|
||||
* platforms, even on the minor ones where constructors are not supported.
|
||||
* (Constructor support is available for at least Win32, Mac OS and Linux.)
|
||||
*
|
||||
* Note that resource data can point directly into the data segment of e.g. a library, so if you are unloading libraries
|
||||
* during runtime you need to be very careful with keeping around pointers to data from a resource, as this goes away
|
||||
* when the library is unloaded. However, in practice this is not generally a problem, since most resource accesses
|
||||
* are for your own resources, and resource data is often used once, during parsing, and then released.
|
||||
* Note that resource data can point directly into the data segment of e.g. a
|
||||
* library, so if you are unloading libraries during runtime you need to be very
|
||||
* careful with keeping around pointers to data from a resource, as this goes
|
||||
* away when the library is unloaded. However, in practice this is not generally
|
||||
* a problem, since most resource accesses are for your own resources, and
|
||||
* resource data is often used once, during parsing, and then released.
|
||||
*
|
||||
* When debugging a program or testing a change to an installed version, it is often useful to be able to
|
||||
* replace resources in the program or library, without recompiling, for debugging or quick hacking and testing
|
||||
* purposes. Since GLib 2.50, it is possible to use the `G_RESOURCE_OVERLAYS` environment variable to selectively overlay
|
||||
* resources with replacements from the filesystem. It is a %G_SEARCHPATH_SEPARATOR-separated list of substitutions to perform
|
||||
* during resource lookups. It is ignored when running in a setuid process.
|
||||
* # Overlays
|
||||
*
|
||||
* When debugging a program or testing a change to an installed version, it is
|
||||
* often useful to be able to replace resources in the program or library,
|
||||
* without recompiling, for debugging or quick hacking and testing purposes.
|
||||
* Since GLib 2.50, it is possible to use the `G_RESOURCE_OVERLAYS` environment
|
||||
* variable to selectively overlay resources with replacements from the
|
||||
* filesystem. It is a `G_SEARCHPATH_SEPARATOR`-separated list of substitutions
|
||||
* to perform during resource lookups. It is ignored when running in a setuid
|
||||
* process.
|
||||
*
|
||||
* A substitution has the form
|
||||
*
|
||||
* |[
|
||||
* /org/gtk/libgtk=/home/desrt/gtk-overlay
|
||||
* ]|
|
||||
* ```
|
||||
* /org/gtk/libgtk=/home/desrt/gtk-overlay
|
||||
* ```
|
||||
*
|
||||
* The part before the `=` is the resource subpath for which the overlay applies. The part after is a
|
||||
* filesystem path which contains files and subdirectories as you would like to be loaded as resources with the
|
||||
* The part before the `=` is the resource subpath for which the overlay
|
||||
* applies. The part after is a filesystem path which contains files and
|
||||
* subdirectories as you would like to be loaded as resources with the
|
||||
* equivalent names.
|
||||
*
|
||||
* In the example above, if an application tried to load a resource with the resource path
|
||||
* `/org/gtk/libgtk/ui/gtkdialog.ui` then GResource would check the filesystem path
|
||||
* `/home/desrt/gtk-overlay/ui/gtkdialog.ui`. If a file was found there, it would be used instead. This is an
|
||||
* overlay, not an outright replacement, which means that if a file is not found at that path, the built-in
|
||||
* version will be used instead. Whiteouts are not currently supported.
|
||||
* In the example above, if an application tried to load a resource with the
|
||||
* resource path `/org/gtk/libgtk/ui/gtkdialog.ui` then `GResource` would check
|
||||
* the filesystem path `/home/desrt/gtk-overlay/ui/gtkdialog.ui`. If a file was
|
||||
* found there, it would be used instead. This is an overlay, not an outright
|
||||
* replacement, which means that if a file is not found at that path, the
|
||||
* built-in version will be used instead. Whiteouts are not currently
|
||||
* supported.
|
||||
*
|
||||
* Substitutions must start with a slash, and must not contain a trailing slash before the '='. The path after
|
||||
* the slash should ideally be absolute, but this is not strictly required. It is possible to overlay the
|
||||
* location of a single resource with an individual file.
|
||||
* Substitutions must start with a slash, and must not contain a trailing slash
|
||||
* before the `=`. The path after the slash should ideally be absolute, but
|
||||
* this is not strictly required. It is possible to overlay the location of a
|
||||
* single resource with an individual file.
|
||||
*
|
||||
* Since: 2.32
|
||||
*/
|
||||
|
||||
Loading…
Reference in New Issue
Block a user