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

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