git.roojs.org Git - gnome.gobject-introspection/blob - docs/g-ir-scanner.1

   1 .TH "g-ir-scanner" 1
   2 .SH NAME
   3 g-ir-scanner \- extracting C metadata from sources and headers
   4 .SH SYNOPSIS
   5 .B g-ir-scanner
   6 [OPTION...] FILES...
   7 .SH DESCRIPTION
   8 g-ir-scanner is a tool which generates GIR XML files by parsing headers
   9 and introspecting GObject based libraries.
  10 It is usually invoked during the normal build step for a project and
  11 the information is saved to disk and later installed so language bindings
  12 and other applications can use it.
  13 Header files and source files are passed in arguments on the command line.
  14 The suffix determines if it should be treated as source (.c) or header (.h),
  15 currently only C based libraries are supported by the scanner.
  16 .SH OPTIONS
  17 .TP
  18 .B \---help
  19 Show help options
  20 .TP
  21 .B \---format=FORMAT
  22 This parameters decides which the resulting format will be used.
  23 The default value is gir.
  24 .TP
  25 .B \---include=NAME
  26 Parses another metadata file. The format is determined by looking
  27 at the file suffix. If a library depends on another the corresponding
  28 metadata file should be included so references to external types are
  29 correctly specified.
  30 .TP
  31 .B \---add-include-path=PATH
  32 Add a directory to the path which the scanner uses to find GIR files.
  33 Can be used multiple times to specify multiple directories
  34 .TP
  35 .B \-i, ---library=LIBRARY
  36 Specifies a library that will be introspected. This means that the
  37 *_get_type() functions in it will be called for GObject data types.
  38 The name of the library should not contain the leading lib prefix nor
  39 the ending shared library suffix.
  40 .TP
  41 .B \-L, ---library-path=PATH
  42 Include this directory when searching for a library.
  43 This option can be specified multiple times to include more than one
  44 directory to look for libraries in.
  45 .TP
  46 .B \-Idirectory
  47 Include this directory in the list of directories to be searched for
  48 header files.  You need to pass to the scanner all the directories
  49 you'd normally pass to the compiler when using the specified source
  50 files.
  51 .TP
  52 .B \-n, ---namespace=NAME
  53 The namespace name. This name should be capitalized, eg the first letter
  54 should be upper case. Examples: Gtk, Clutter, WebKit.
  55 .TP
  56 .B \---no-libtool
  57 Disable usage of libtool for compiling stub introspection binary.  Use this
  58 if your build system does not require libtool.
  59 .TP
  60 .B \---libtool
  61 Full path to libtool executable.  Typically used for Automake systems.
  62 .TP
  63 .B ---nsversion=VERSION
  64 The namespace version. For instance 1.0. This is usually the platform version,
  65 eg 2.0 for Gtk+, not 2.12.7.
  66 .TP
  67 .B \-p, ---program=PROGRAM
  68 Specifies a binary that will be introspected. This means that the
  69 *_get_type() functions in it will be called for GObject data types.
  70 The binary must be modified to take a --introspect= option, and
  71 to pass the argument to this function to g_irepository_dump.
  72 .TP
  73 .B \---program-arg=ARG
  74 Additional argument to pass to program for introspection.
  75 .TP
  76 .B \, ---strip-prefix=PREFIX
  77 If this option is specified a prefix will be stripped from all functions.
  78 If not specified, the lower case version of the namespace will be used.
  79 Eg, a strip prefix of
  80 .B g_
  81 and a namespace set to
  82 .B GLib
  83 will export the function
  84 .B g_type_name
  85 as
  86 .B GLib.type_name.
  87 .TP
  88 .B \, ---output=FILENAME
  89 Name of the file to output. Normally namespace + format extension.
  90 Eg, GLib.gir.
  91 .TP
  92 .B \, ---pkg=PACKAGE
  93 List of pkg-config packages to get compiler and linker flags from.
  94 This option can be specified multiple times to include flags from
  95 several pkg-config packages.
  96 .TP
  97 .B \---verbose
  98 Be verbose, include some debugging information.
  99 .TP
 100 .B \---noclosure
 101 Do not delete unknown types from the resulting format.
 102 .TP
 103 .B \---typelib-xml
 104 Convert the resulting xml to only output the types relevant
 105 to the typelib compiler. This is mainly useful for verifying the
 106 correctness of the typelib itself.
 107 .TP
 108 .B \---inject=FILENAME
 109 Injects a variant of a GIR file into the scanner. This is used to add
 110 custom functions to a GIR wrapping a library without modifying the upstream
 111 library itself. The Format of the inject file is similar to a GIR,
 112 but the root node is <injections> rather than <repository> and
 113 <inject path="..."> where ... is an xpath expression.
 114
 115 Example:
 116
 117   <inject path="namespace/class[@name='TestDrawable']">
 118     <method name="get_width" c:identifier="girepo_test_drawable_get_width">
 119       <return-value transfer-ownership="none">
 120         <type name="int" c:type="gint"/>
 121       </return-value>
 122     </method>
 123   </inject>
 124
 125 The example above will add a new method called get_with to the TestDrawable class.
 126 .TP
 127 .B \---xpath-assertions=FILENAME
 128 Loads a list xpath assertions from FILENAME, this is useful for verifying
 129 that the GIR itself is properly generated.
 130 .TP
 131 .SH BUGS
 132 Report bugs at http://bugzilla.gnome.org/ in the glib product and
 133 introspection component.
 134 .SH HOMEPAGE and CONTACT
 135 http://live.gnome.org/GObjectIntrospection
 136 .SH AUTHORS
 137 Johan Dahlin
 138