docs/reference/gio/glib-compile-resources.xml

   1 <refentry id="glib-compile-resources" lang="en">
   2
   3 <refmeta>
   4   <refentrytitle>glib-compile-resources</refentrytitle>
   5   <manvolnum>1</manvolnum>
   6   <refmiscinfo class="manual">User Commands</refmiscinfo>
   7 </refmeta>
   8
   9 <refnamediv>
  10   <refname>glib-compile-resources</refname>
  11   <refpurpose>GLib resource compiler</refpurpose>
  12 </refnamediv>
  13
  14 <refsynopsisdiv>
  15   <cmdsynopsis>
  16     <command>glib-compile-resources</command>
  17     <arg choice="opt" rep="repeat">option</arg>
  18     <arg choice="req">file</arg>
  19   </cmdsynopsis>
  20 </refsynopsisdiv>
  21
  22 <refsect1><title>Description</title>
  23 <para><command>glib-compile-resources</command> reads the resource description from
  24 <replaceable>file</replaceable> and the files that it references
  25 and creates a binary resource bundle that is suitable for use with the
  26 <link linkend="GResource"><type>GResource</type></link> API.
  27 The resulting bundle is then written out as-is, or as C source for linking into
  28 an application.
  29 </para>
  30 <para>
  31 The XML resource files normally have the filename extension <filename>.gresource.xml</filename>.
  32 For a detailed description of the XML file format, see the
  33 <link linkend="GResource"><type>GResource</type></link> documentation.
  34 </para>
  35
  36 <refsect2><title>Options</title>
  37 <variablelist>
  38
  39 <varlistentry>
  40 <term><option>-h</option>, <option>--help</option></term>
  41 <listitem><para>
  42 Print help and exit
  43 </para></listitem>
  44 </varlistentry>
  45
  46 <varlistentry>
  47 <term><option>--target=<replaceable>TARGETFILE</replaceable></option></term>
  48 <listitem><para>
  49 Store the compiled resources in <replaceable>TARGETFILE</replaceable>. If not specified a filename based
  50 on the <replaceable>file</replaceable> basename is used.
  51 </para></listitem>
  52 </varlistentry>
  53
  54 <varlistentry>
  55 <term><option>--sourcedir</option></term>
  56 <listitem><para>
  57 The files references in <replaceable>file</replaceable> are loaded from this directory. If
  58 not specified the current directory is used.
  59 </para></listitem>
  60 </varlistentry>
  61
  62 <varlistentry>
  63 <term><option>--generate</option></term>
  64 <listitem><para>
  65 Write the output file in the format selected for by its filename extension:
  66 <variablelist>
  67 <varlistentry>
  68 <term><literal>.c</literal></term>
  69 <listitem><para>C source</para></listitem>
  70 </varlistentry>
  71 <varlistentry>
  72 <term><literal>.h</literal></term>
  73 <listitem><para>C header</para></listitem>
  74 </varlistentry>
  75 <varlistentry>
  76 <term><literal>.gresource</literal></term>
  77 <listitem><para>resource bundle</para></listitem>
  78 </varlistentry>
  79 </variablelist>
  80 </para></listitem>
  81 </varlistentry>
  82
  83 <varlistentry>
  84 <term><option>--generate-source</option></term>
  85 <listitem><para>
  86 Instead of a writing the resource bundle in binary form create a C source file that contains the
  87 resource bundle. This can then be compiled into an application for easy access.
  88 </para></listitem>
  89 </varlistentry>
  90
  91 <varlistentry>
  92 <term><option>--generate-header</option></term>
  93 <listitem><para>
  94 Generate a header file for use with C code generated by <option>--generate-source</option>.
  95 </para></listitem>
  96 </varlistentry>
  97
  98 <varlistentry>
  99 <term><option>--generate-dependencies</option></term>
 100 <listitem><para>
 101 Prints the list of files that the resource bundle references to standard output.
 102 This can be used to track dependencies in the build system. For example, the following
 103 make rule would mark <replaceable>test.gresource</replaceable> as depending on all the
 104 files that <replaceable>test.gresource.xml</replaceable> includes, so that is is automatically
 105 rebuilt if any of them change:
 106 <programlisting>
 107 test.gresource: test.gresource.xml $(shell $(GLIB_COMPILE_RESOURCES) --generate-dependencies test.gresource.xml)
 108 </programlisting>
 109 Note that this may or may not be portable to non-GNU <command>make</command>.
 110 </para>
 111 </listitem>
 112 </varlistentry>
 113
 114 <varlistentry>
 115 <term><option>--c-name</option></term>
 116 <listitem><para>
 117 Specify the prefix used for the C identifiers in the code generated by
 118 <option>--generate-source</option> and <option>--generate-headers</option>.
 119 </para></listitem>
 120 </varlistentry>
 121
 122 <varlistentry>
 123 <term><option>--manual-register</option></term>
 124 <listitem><para>
 125 By default code generated by <option>--generate-source</option> uses automatic initialization
 126 of the resource. This works on most systems by using the compiler support for constructors.
 127 However, some (uncommon) compilers may not support this, you can then specify <option>--manual-register</option>,
 128 which will generate custom register and unregister functions that your code can manually call
 129 at initialization and uninitialization time.
 130 </para></listitem>
 131 </varlistentry>
 132
 133 </variablelist>
 134 </refsect2>
 135
 136 <refsect2><title>Environment Variables</title>
 137 <variablelist>
 138
 139 <varlistentry>
 140 <term><envar>XMLLINT</envar></term>
 141 <listitem><para>
 142 The full path to the xmllint executable. This is used to preprocess resources with the
 143 <literal>xml-stripblanks</literal> preprocessing option. If this environment variable is not
 144 set, xmllint is searched in the <envar>PATH</envar>.
 145 </para></listitem>
 146 </varlistentry>
 147
 148 <varlistentry>
 149 <term><envar>GDK_PIXBUF_PIXDATA</envar></term>
 150 <listitem><para>
 151 The full path to the gdk-pixbuf-pixdata executable. This is used to preprocess resources with the
 152 <literal>to-pixdata</literal> preprocessing option. If this environment variable is not
 153 set, gdk-pixbuf-pixdata is searched in the <envar>PATH</envar>.
 154 </para></listitem>
 155 </varlistentry>
 156
 157 </variablelist>
 158 </refsect2>
 159
 160 </refsect1>
 161 <refsect1><title>See also</title>
 162 </refsect1>
 163 </refentry>