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>--version</option></term>
  61 <listitem><para>
  62 Print program version and exit
  63 </para></listitem>
  64 </varlistentry>
  65
  66 <varlistentry>
  67 <term><option>--target=<replaceable>TARGET</replaceable></option></term>
  68 <listitem><para>
  69 Store the compiled resources in the file <replaceable>TARGET</replaceable>.
  70 If not specified a filename based on the <replaceable>FILE</replaceable>
  71 basename is used.
  72 </para></listitem>
  73 </varlistentry>
  74
  75 <varlistentry>
  76 <term><option>--sourcedir=<replaceable>DIRECTORY</replaceable></option></term>
  77 <listitem><para>
  78 The files referenced in <replaceable>FILE</replaceable> are loaded from
  79 this directory. If not specified, the current directory is used.
  80 </para></listitem>
  81 </varlistentry>
  82
  83 <varlistentry>
  84 <term><option>--generate</option></term>
  85 <listitem><para>
  86 Write the output file in the format selected for by its filename extension:
  87 <variablelist>
  88 <varlistentry>
  89 <term><literal>.c</literal></term>
  90 <listitem><para>C source</para></listitem>
  91 </varlistentry>
  92 <varlistentry>
  93 <term><literal>.h</literal></term>
  94 <listitem><para>C header</para></listitem>
  95 </varlistentry>
  96 <varlistentry>
  97 <term><literal>.gresource</literal></term>
  98 <listitem><para>resource bundle</para></listitem>
  99 </varlistentry>
 100 </variablelist>
 101 </para></listitem>
 102 </varlistentry>
 103
 104 <varlistentry>
 105 <term><option>--generate-source</option></term>
 106 <listitem><para>
 107 Instead of a writing the resource bundle in binary form create a C source file
 108 that contains the resource bundle. This can then be compiled into an
 109 application for easy access.
 110 </para></listitem>
 111 </varlistentry>
 112
 113 <varlistentry>
 114 <term><option>--generate-header</option></term>
 115 <listitem><para>
 116 Generate a header file for use with C code generated by
 117 <option>--generate-source</option>.
 118 </para></listitem>
 119 </varlistentry>
 120
 121 <varlistentry>
 122 <term><option>--generate-dependencies</option></term>
 123 <listitem><para>
 124 Prints the list of files that the resource bundle references to standard output.
 125 This can be used to track dependencies in the build system. For example, the
 126 following make rule would mark <replaceable>test.gresource</replaceable> as
 127 depending on all the files that <replaceable>test.gresource.xml</replaceable>
 128 includes, so that is is automatically rebuilt if any of them change:
 129 <programlisting>
 130 test.gresource: test.gresource.xml $(shell $(GLIB_COMPILE_RESOURCES) --generate-dependencies test.gresource.xml)
 131 </programlisting>
 132 Note that this may or may not be portable to non-GNU <command>make</command>.
 133 </para>
 134 <para>
 135 Also see <option>--dependency-file</option>.
 136 </para>
 137 </listitem>
 138 </varlistentry>
 139
 140 <varlistentry>
 141 <term><option>--c-name</option></term>
 142 <listitem><para>
 143 Specify the prefix used for the C identifiers in the code generated by
 144 <option>--generate-source</option> and <option>--generate-header</option>.
 145 </para></listitem>
 146 </varlistentry>
 147
 148 <varlistentry>
 149 <term><option>--manual-register</option></term>
 150 <listitem><para>
 151 By default code generated by <option>--generate-source</option> uses automatic
 152 initialization of the resource. This works on most systems by using the
 153 compiler support for constructors. However, some (uncommon) compilers may not
 154 support this, you can then specify <option>--manual-register</option>,
 155 which will generate custom register and unregister functions that your code
 156 can manually call at initialization and uninitialization time.
 157 </para></listitem>
 158 </varlistentry>
 159
 160 <varlistentry>
 161 <term><option>--internal</option></term>
 162 <listitem><para>
 163 By default code generated by <option>--generate-source</option> declares all
 164 initialization functions as <type>extern</type>.  So they are exported
 165 unless this is prevented by a link script or other means.  Since libraries
 166 usually want to use the functions only internally it can be more useful to
 167 declare them as
 168 <link linkend="G-GNUC-INTERNAL:CAPS"><literal>G_GNUC_INTERNAL</literal></link>
 169 which is what <option>--internal</option> does.
 170 </para></listitem>
 171 </varlistentry>
 172
 173 <varlistentry>
 174 <term><option>--dependency-file=<replaceable>FILE</replaceable></option></term>
 175 <listitem><para>
 176 Write dependencies in the same style as gcc -M -MF to the given file.
 177 If <option>FILE</option> is -, the dependencies are written to the standard
 178 output. Unlike <option>--generate-dependencies</option>, this option can be
 179 combined with other <option>--generate</option> options to generate dependencies
 180 as a side-effect of generating sources.
 181 </para></listitem>
 182 </varlistentry>
 183
 184 <varlistentry>
 185 <term><option>--generate-phony-targets</option></term>
 186 <listitem><para>
 187 When creating a dependency file with <option>--dependency-file</option>
 188 include phony targets in the same style as gcc -MP. This would typically
 189 be used with <literal>make</literal>.
 190 </para></listitem>
 191 </varlistentry>
 192
 193 </variablelist>
 194 </refsect1>
 195
 196 <refsect1><title>Environment</title>
 197 <variablelist>
 198
 199 <varlistentry>
 200 <term><envar>XMLLINT</envar></term>
 201 <listitem><para>
 202 The full path to the <command>xmllint</command> executable. This is used to
 203 preprocess resources with the <literal>xml-stripblanks</literal> preprocessing
 204 option. If this environment variable is not set, <command>xmllint</command> is
 205 searched for in the <envar>PATH</envar>.
 206 </para></listitem>
 207 </varlistentry>
 208
 209 <varlistentry>
 210 <term><envar>GDK_PIXBUF_PIXDATA</envar></term>
 211 <listitem><para>
 212 The full path to the <command>gdk-pixbuf-pixdata</command> executable. This is
 213 used to preprocess resources with the <literal>to-pixdata</literal> preprocessing
 214 option. If this environment variable is not set, <command>gdk-pixbuf-pixdata</command>
 215 is searched for in the <envar>PATH</envar>.
 216 </para></listitem>
 217 </varlistentry>
 218
 219 <varlistentry>
 220 <term><envar>JSON_GLIB_FORMAT</envar></term>
 221 <listitem><para>
 222 The full path to the <command>json-glib-format</command> executable. This is used
 223 to preprocess resources with the <literal>json-stripblanks</literal> preprocessing
 224 option. If this environment variable is not set, <command>json-glib-format</command>
 225 is searched for in the <envar>PATH</envar>.
 226 </para></listitem>
 227 </varlistentry>
 228
 229 </variablelist>
 230 </refsect1>
 231 </refentry>