docs/g-ir-scanner.1

   1 .\" Man page generated from reStructuredText.
   2 .
   3 .TH G-IR-SCANNER 1 "" "" ""
   4 .SH NAME
   5 g-ir-scanner \- Extracting C metadata from sources and headers
   6 .
   7 .nr rst2man-indent-level 0
   8 .
   9 .de1 rstReportMargin
  10 \\$1 \\n[an-margin]
  11 level \\n[rst2man-indent-level]
  12 level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
  13 -
  14 \\n[rst2man-indent0]
  15 \\n[rst2man-indent1]
  16 \\n[rst2man-indent2]
  17 ..
  18 .de1 INDENT
  19 .\" .rstReportMargin pre:
  20 . RS \\$1
  21 . nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin]
  22 . nr rst2man-indent-level +1
  23 .\" .rstReportMargin post:
  24 ..
  25 .de UNINDENT
  26 . RE
  27 .\" indent \\n[an-margin]
  28 .\" old: \\n[rst2man-indent\\n[rst2man-indent-level]]
  29 .nr rst2man-indent-level -1
  30 .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
  31 .in \\n[rst2man-indent\\n[rst2man-indent-level]]u
  32 ..
  33 .SH SYNOPSIS
  34 .sp
  35 \fBg\-ir\-scanner\fP [OPTION...] FILES...
  36 .SH DESCRIPTION
  37 .sp
  38 g\-ir\-scanner is a tool which generates GIR XML files by parsing headers and
  39 introspecting GObject based libraries. It is usually invoked during the normal
  40 build step for a project and the information is saved to disk and later
  41 installed, so that language bindings and other applications can use it. Header
  42 files and source files are passed in as arguments on the command line. The
  43 suffix determines whether a file be treated as a source file (.c) or a header
  44 file (.h). Currently only C based libraries are supported by the scanner.
  45 .SH OPTIONS
  46 .INDENT 0.0
  47 .TP
  48 .B \-\-help
  49 Show help options
  50 .TP
  51 .B \-\-quiet
  52 If passed, do not print details of normal operation.
  53 .TP
  54 .B \-\-warn\-all
  55 Display warnings for public API which is not introspectable.
  56 .TP
  57 .B \-\-warn\-error
  58 Make warnings be fatal errors.
  59 .TP
  60 .BI \-\-format\fB= FORMAT
  61 This parameters decides which the resulting format will be used. The
  62 default value is gir.
  63 .TP
  64 .BI \-\-include\fB= NAME
  65 Add the specified introspection dependency to the scanned namespace.
  66 NAME is of the form NAMESPACE\-VERSION, like Gtk\-3.0.
  67 .TP
  68 .BI \-\-include\-uninstalled\fB= PATH
  69 Add the specified introspection dependency to the scanned namespace.
  70 This differs from \fB\-\-include\fP in that it takes a file path, and does not
  71 process the pkg\-config dependencies (since they may not be installed yet).
  72 .TP
  73 .BI \-\-add\-include\-path\fB= PATH
  74 Add a directory to the path which the scanner uses to find GIR files. Can
  75 be used multiple times to specify multiple directories
  76 .TP
  77 .BI \-i\fP,\fB  \-\-library\fB= LIBRARY
  78 Specifies a library that will be introspected. This means that the
  79 *_get_type() functions in it will be called for GObject data types. The
  80 name of the library should not contain the leading lib prefix nor the
  81 ending shared library suffix.
  82 .TP
  83 .BI \-L\fP,\fB  \-\-library\-path\fB= PATH
  84 Include this directory when searching for a library. This option can be
  85 specified multiple times to include more than one directory to look for
  86 libraries in.
  87 .TP
  88 .BI \-I\fB directory
  89 Include this directory in the list of directories to be searched for
  90 header files. You need to pass to the scanner all the directories you\(aqd
  91 normally pass to the compiler when using the specified source files.
  92 .TP
  93 .BI \-\-c\-include\fB= C_INCLUDES
  94 Headers which should be included in C programs. This option can be
  95 specified multiple times to include more than one header.
  96 .TP
  97 .BI \-n\fP,\fB  \-\-namespace\fB= NAME
  98 The namespace name. This name should be capitalized, eg the first letter
  99 should be upper case. Examples: Gtk, Clutter, WebKit.
 100 .TP
 101 .B \-\-no\-libtool
 102 Disable usage of libtool for compiling stub introspection binary. Use this
 103 if your build system does not require libtool.
 104 .TP
 105 .B \-\-libtool
 106 Full path to libtool executable. Typically used for Automake systems.
 107 .TP
 108 .BI \-\-nsversion\fB= VERSION
 109 The namespace version. For instance 1.0. This is usually the platform
 110 version, eg 2.0 for Gtk+, not 2.12.7.
 111 .TP
 112 .BI \-p\fP,\fB  \-\-program\fB= PROGRAM
 113 Specifies a binary that will be introspected. This means that the
 114 *_get_type() functions in it will be called for GObject data types. The
 115 binary must be modified to take a \fB\-\-introspect\-dump=\fP option, and to pass
 116 the argument to this function to g_irepository_dump.
 117 .TP
 118 .BI \-\-program\-arg\fB= ARG
 119 Additional argument to pass to program for introspection.
 120 .TP
 121 .BI \-\-identifier\-prefix\fB= PREFIX
 122 This option may be specified multiple times. Each one gives a prefix that
 123 will be stripped from all C identifiers. If none specified, the namespace
 124 will be used. Eg, an identifier prefix of Foo will export the identifier
 125 typdef struct _FooBar FooBar; as Foo.Bar.
 126 .TP
 127 .BI \-\-symbol\-prefix\fB= PREFIX
 128 This option may be specified multiple times. Each one gives a
 129 prefix that will be stripped from all C symbols. Eg, an symbol
 130 prefix of foo will export the symbol foo_bar_do_something as
 131 Foo.Bar.do_something.
 132 .TP
 133 .B \-\-accept\-unprefixed
 134 If specified, the scanner will accept identifiers and symbols which do not
 135 match the namespace prefix. Try to avoid using this if possible.
 136 .TP
 137 .BI \-\-output\fB= FILENAME
 138 Name of the file to output. Normally namespace + format extension. Eg,
 139 GLib\-2.0.gir.
 140 .TP
 141 .BI \-\-pkg\fB= PACKAGE
 142 List of pkg\-config packages to get compiler and linker flags from. This
 143 option can be specified multiple times to include flags from several
 144 pkg\-config packages.
 145 .TP
 146 .BI \-\-pkg\-export\fB= PACKAGE
 147 List of pkg\-config packages that are provided by the generated gir. This
 148 option can be specified multiple times if the gir provides more packages.
 149 If not specified, the packages specified with \fB\-\-pkg=\fP will be used.
 150 .TP
 151 .B \-\-verbose
 152 Be verbose, include some debugging information.
 153 .UNINDENT
 154 .SH ENVIRONMENT VARIABLES
 155 .sp
 156 The g\-ir\-scanner uses the \fBXDG_DATA_DIRS\fP variable to check for dirs, the
 157 girs are located in \fBXDG_DATA_DIRS/gir\-1.0\fP\&. It is normally set on a
 158 distribution so you shouldn\(aqt need to set it yourself.
 159 .sp
 160 The variable \fBGI_SCANNER_DISABLE_CACHE\fP ensures that the scanner will not
 161 write cache data to \fB$HOME\fP\&.
 162 .sp
 163 The variable \fBGI_SCANNER_DEBUG\fP can be used to debug issues in the
 164 build\-system that involve g\-ir\-scanner. When it is set to \fBsave\-temps\fP, then
 165 g\-ir\-scanner will not remove temporary files and directories after it
 166 terminates.
 167 .sp
 168 The variable \fBGI_HOST_OS\fP can be used to control the OS name on the host
 169 that runs the scanner. It has the same semantics as the Python \fBos.name\fP
 170 property.
 171 .sp
 172 The variable \fBGI_CROSS_LAUNCHER\fP can be used to wrap the GType introspection
 173 binary generated by g\-ir\-scanner before executing it. It is useful when
 174 generating introspection data in a cross-compilation environment.
 175 .SH BUGS
 176 .sp
 177 Report bugs at \fI\%https://gitlab.gnome.org/GNOME/gobject\-introspection/issues\fP
 178 .SH HOMEPAGE AND CONTACT
 179 .sp
 180 \fI\%https://gi.readthedocs.io/\fP
 181 .SH AUTHORS
 182 .sp
 183 Johan Dahlin
 184 .\" Generated by docutils manpage writer.
 185 .