binutils/doc/windres.1

   1 .\" Automatically generated by Pod::Man 2.23 (Pod::Simple 3.14)
   2 .\"
   3 .\" Standard preamble:
   4 .\" ========================================================================
   5 .de Sp \" Vertical space (when we can't use .PP)
   6 .if t .sp .5v
   7 .if n .sp
   8 ..
   9 .de Vb \" Begin verbatim text
  10 .ft CW
  11 .nf
  12 .ne \\$1
  13 ..
  14 .de Ve \" End verbatim text
  15 .ft R
  16 .fi
  17 ..
  18 .\" Set up some character translations and predefined strings.  \*(-- will
  19 .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
  20 .\" double quote, and \*(R" will give a right double quote.  \*(C+ will
  21 .\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
  22 .\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
  23 .\" nothing in troff, for use with C<>.
  24 .tr \(*W-
  25 .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
  26 .ie n \{\
  27 .    ds -- \(*W-
  28 .    ds PI pi
  29 .    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
  30 .    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
  31 .    ds L" ""
  32 .    ds R" ""
  33 .    ds C` ""
  34 .    ds C' ""
  35 'br\}
  36 .el\{\
  37 .    ds -- \|\(em\|
  38 .    ds PI \(*p
  39 .    ds L" ``
  40 .    ds R" ''
  41 'br\}
  42 .\"
  43 .\" Escape single quotes in literal strings from groff's Unicode transform.
  44 .ie \n(.g .ds Aq \(aq
  45 .el       .ds Aq '
  46 .\"
  47 .\" If the F register is turned on, we'll generate index entries on stderr for
  48 .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
  49 .\" entries marked with X<> in POD.  Of course, you'll have to process the
  50 .\" output yourself in some meaningful fashion.
  51 .ie \nF \{\
  52 .    de IX
  53 .    tm Index:\\$1\t\\n%\t"\\$2"
  54 ..
  55 .    nr % 0
  56 .    rr F
  57 .\}
  58 .el \{\
  59 .    de IX
  60 ..
  61 .\}
  62 .\"
  63 .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
  64 .\" Fear.  Run.  Save yourself.  No user-serviceable parts.
  65 .    \" fudge factors for nroff and troff
  66 .if n \{\
  67 .    ds #H 0
  68 .    ds #V .8m
  69 .    ds #F .3m
  70 .    ds #[ \f1
  71 .    ds #] \fP
  72 .\}
  73 .if t \{\
  74 .    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
  75 .    ds #V .6m
  76 .    ds #F 0
  77 .    ds #[ \&
  78 .    ds #] \&
  79 .\}
  80 .    \" simple accents for nroff and troff
  81 .if n \{\
  82 .    ds ' \&
  83 .    ds ` \&
  84 .    ds ^ \&
  85 .    ds , \&
  86 .    ds ~ ~
  87 .    ds /
  88 .\}
  89 .if t \{\
  90 .    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
  91 .    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
  92 .    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
  93 .    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
  94 .    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
  95 .    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
  96 .\}
  97 .    \" troff and (daisy-wheel) nroff accents
  98 .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
  99 .ds 8 \h'\*(#H'\(*b\h'-\*(#H'
 100 .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
 101 .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
 102 .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
 103 .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
 104 .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
 105 .ds ae a\h'-(\w'a'u*4/10)'e
 106 .ds Ae A\h'-(\w'A'u*4/10)'E
 107 .    \" corrections for vroff
 108 .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
 109 .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
 110 .    \" for low resolution devices (crt and lpr)
 111 .if \n(.H>23 .if \n(.V>19 \
 112 \{\
 113 .    ds : e
 114 .    ds 8 ss
 115 .    ds o a
 116 .    ds d- d\h'-1'\(ga
 117 .    ds D- D\h'-1'\(hy
 118 .    ds th \o'bp'
 119 .    ds Th \o'LP'
 120 .    ds ae ae
 121 .    ds Ae AE
 122 .\}
 123 .rm #[ #] #H #V #F C
 124 .\" ========================================================================
 125 .\"
 126 .IX Title "WINDRES 1"
 127 .TH WINDRES 1 "2012-11-13" "binutils-2.23.1" "GNU Development Tools"
 128 .\" For nroff, turn off justification.  Always turn off hyphenation; it makes
 129 .\" way too many mistakes in technical documents.
 130 .if n .ad l
 131 .nh
 132 .SH "NAME"
 133 windres \- manipulate Windows resources.
 134 .SH "SYNOPSIS"
 135 .IX Header "SYNOPSIS"
 136 windres [options] [input\-file] [output\-file]
 137 .SH "DESCRIPTION"
 138 .IX Header "DESCRIPTION"
 139 \&\fBwindres\fR reads resources from an input file and copies them into
 140 an output file.  Either file may be in one of three formats:
 141 .ie n .IP """rc""" 4
 142 .el .IP "\f(CWrc\fR" 4
 143 .IX Item "rc"
 144 A text format read by the Resource Compiler.
 145 .ie n .IP """res""" 4
 146 .el .IP "\f(CWres\fR" 4
 147 .IX Item "res"
 148 A binary format generated by the Resource Compiler.
 149 .ie n .IP """coff""" 4
 150 .el .IP "\f(CWcoff\fR" 4
 151 .IX Item "coff"
 152 A \s-1COFF\s0 object or executable.
 153 .PP
 154 The exact description of these different formats is available in
 155 documentation from Microsoft.
 156 .PP
 157 When \fBwindres\fR converts from the \f(CW\*(C`rc\*(C'\fR format to the \f(CW\*(C`res\*(C'\fR
 158 format, it is acting like the Windows Resource Compiler.  When
 159 \&\fBwindres\fR converts from the \f(CW\*(C`res\*(C'\fR format to the \f(CW\*(C`coff\*(C'\fR
 160 format, it is acting like the Windows \f(CW\*(C`CVTRES\*(C'\fR program.
 161 .PP
 162 When \fBwindres\fR generates an \f(CW\*(C`rc\*(C'\fR file, the output is similar
 163 but not identical to the format expected for the input.  When an input
 164 \&\f(CW\*(C`rc\*(C'\fR file refers to an external filename, an output \f(CW\*(C`rc\*(C'\fR file
 165 will instead include the file contents.
 166 .PP
 167 If the input or output format is not specified, \fBwindres\fR will
 168 guess based on the file name, or, for the input file, the file contents.
 169 A file with an extension of \fI.rc\fR will be treated as an \f(CW\*(C`rc\*(C'\fR
 170 file, a file with an extension of \fI.res\fR will be treated as a
 171 \&\f(CW\*(C`res\*(C'\fR file, and a file with an extension of \fI.o\fR or
 172 \&\fI.exe\fR will be treated as a \f(CW\*(C`coff\*(C'\fR file.
 173 .PP
 174 If no output file is specified, \fBwindres\fR will print the resources
 175 in \f(CW\*(C`rc\*(C'\fR format to standard output.
 176 .PP
 177 The normal use is for you to write an \f(CW\*(C`rc\*(C'\fR file, use \fBwindres\fR
 178 to convert it to a \s-1COFF\s0 object file, and then link the \s-1COFF\s0 file into
 179 your application.  This will make the resources described in the
 180 \&\f(CW\*(C`rc\*(C'\fR file available to Windows.
 181 .SH "OPTIONS"
 182 .IX Header "OPTIONS"
 183 .IP "\fB\-i\fR \fIfilename\fR" 4
 184 .IX Item "-i filename"
 185 .PD 0
 186 .IP "\fB\-\-input\fR \fIfilename\fR" 4
 187 .IX Item "--input filename"
 188 .PD
 189 The name of the input file.  If this option is not used, then
 190 \&\fBwindres\fR will use the first non-option argument as the input file
 191 name.  If there are no non-option arguments, then \fBwindres\fR will
 192 read from standard input.  \fBwindres\fR can not read a \s-1COFF\s0 file from
 193 standard input.
 194 .IP "\fB\-o\fR \fIfilename\fR" 4
 195 .IX Item "-o filename"
 196 .PD 0
 197 .IP "\fB\-\-output\fR \fIfilename\fR" 4
 198 .IX Item "--output filename"
 199 .PD
 200 The name of the output file.  If this option is not used, then
 201 \&\fBwindres\fR will use the first non-option argument, after any used
 202 for the input file name, as the output file name.  If there is no
 203 non-option argument, then \fBwindres\fR will write to standard output.
 204 \&\fBwindres\fR can not write a \s-1COFF\s0 file to standard output.  Note,
 205 for compatibility with \fBrc\fR the option \fB\-fo\fR is also
 206 accepted, but its use is not recommended.
 207 .IP "\fB\-J\fR \fIformat\fR" 4
 208 .IX Item "-J format"
 209 .PD 0
 210 .IP "\fB\-\-input\-format\fR \fIformat\fR" 4
 211 .IX Item "--input-format format"
 212 .PD
 213 The input format to read.  \fIformat\fR may be \fBres\fR, \fBrc\fR, or
 214 \&\fBcoff\fR.  If no input format is specified, \fBwindres\fR will
 215 guess, as described above.
 216 .IP "\fB\-O\fR \fIformat\fR" 4
 217 .IX Item "-O format"
 218 .PD 0
 219 .IP "\fB\-\-output\-format\fR \fIformat\fR" 4
 220 .IX Item "--output-format format"
 221 .PD
 222 The output format to generate.  \fIformat\fR may be \fBres\fR,
 223 \&\fBrc\fR, or \fBcoff\fR.  If no output format is specified,
 224 \&\fBwindres\fR will guess, as described above.
 225 .IP "\fB\-F\fR \fItarget\fR" 4
 226 .IX Item "-F target"
 227 .PD 0
 228 .IP "\fB\-\-target\fR \fItarget\fR" 4
 229 .IX Item "--target target"
 230 .PD
 231 Specify the \s-1BFD\s0 format to use for a \s-1COFF\s0 file as input or output.  This
 232 is a \s-1BFD\s0 target name; you can use the \fB\-\-help\fR option to see a list
 233 of supported targets.  Normally \fBwindres\fR will use the default
 234 format, which is the first one listed by the \fB\-\-help\fR option.
 235 .IP "\fB\-\-preprocessor\fR \fIprogram\fR" 4
 236 .IX Item "--preprocessor program"
 237 When \fBwindres\fR reads an \f(CW\*(C`rc\*(C'\fR file, it runs it through the C
 238 preprocessor first.  This option may be used to specify the preprocessor
 239 to use, including any leading arguments.  The default preprocessor
 240 argument is \f(CW\*(C`gcc \-E \-xc\-header \-DRC_INVOKED\*(C'\fR.
 241 .IP "\fB\-\-preprocessor\-arg\fR \fIoption\fR" 4
 242 .IX Item "--preprocessor-arg option"
 243 When \fBwindres\fR reads an \f(CW\*(C`rc\*(C'\fR file, it runs it through
 244 the C preprocessor first.  This option may be used to specify additional
 245 text to be passed to preprocessor on its command line.
 246 This option can be used multiple times to add multiple options to the
 247 preprocessor command line.
 248 .IP "\fB\-I\fR \fIdirectory\fR" 4
 249 .IX Item "-I directory"
 250 .PD 0
 251 .IP "\fB\-\-include\-dir\fR \fIdirectory\fR" 4
 252 .IX Item "--include-dir directory"
 253 .PD
 254 Specify an include directory to use when reading an \f(CW\*(C`rc\*(C'\fR file.
 255 \&\fBwindres\fR will pass this to the preprocessor as an \fB\-I\fR
 256 option.  \fBwindres\fR will also search this directory when looking for
 257 files named in the \f(CW\*(C`rc\*(C'\fR file.  If the argument passed to this command
 258 matches any of the supported \fIformats\fR (as described in the \fB\-J\fR
 259 option), it will issue a deprecation warning, and behave just like the
 260 \&\fB\-J\fR option.  New programs should not use this behaviour.  If a
 261 directory happens to match a \fIformat\fR, simple prefix it with \fB./\fR
 262 to disable the backward compatibility.
 263 .IP "\fB\-D\fR \fItarget\fR" 4
 264 .IX Item "-D target"
 265 .PD 0
 266 .IP "\fB\-\-define\fR \fIsym\fR\fB[=\fR\fIval\fR\fB]\fR" 4
 267 .IX Item "--define sym[=val]"
 268 .PD
 269 Specify a \fB\-D\fR option to pass to the preprocessor when reading an
 270 \&\f(CW\*(C`rc\*(C'\fR file.
 271 .IP "\fB\-U\fR \fItarget\fR" 4
 272 .IX Item "-U target"
 273 .PD 0
 274 .IP "\fB\-\-undefine\fR \fIsym\fR" 4
 275 .IX Item "--undefine sym"
 276 .PD
 277 Specify a \fB\-U\fR option to pass to the preprocessor when reading an
 278 \&\f(CW\*(C`rc\*(C'\fR file.
 279 .IP "\fB\-r\fR" 4
 280 .IX Item "-r"
 281 Ignored for compatibility with rc.
 282 .IP "\fB\-v\fR" 4
 283 .IX Item "-v"
 284 Enable verbose mode.  This tells you what the preprocessor is if you
 285 didn't specify one.
 286 .IP "\fB\-c\fR \fIval\fR" 4
 287 .IX Item "-c val"
 288 .PD 0
 289 .IP "\fB\-\-codepage\fR \fIval\fR" 4
 290 .IX Item "--codepage val"
 291 .PD
 292 Specify the default codepage to use when reading an \f(CW\*(C`rc\*(C'\fR file.
 293 \&\fIval\fR should be a hexadecimal prefixed by \fB0x\fR or decimal
 294 codepage code. The valid range is from zero up to 0xffff, but the
 295 validity of the codepage is host and configuration dependent.
 296 .IP "\fB\-l\fR \fIval\fR" 4
 297 .IX Item "-l val"
 298 .PD 0
 299 .IP "\fB\-\-language\fR \fIval\fR" 4
 300 .IX Item "--language val"
 301 .PD
 302 Specify the default language to use when reading an \f(CW\*(C`rc\*(C'\fR file.
 303 \&\fIval\fR should be a hexadecimal language code.  The low eight bits are
 304 the language, and the high eight bits are the sublanguage.
 305 .IP "\fB\-\-use\-temp\-file\fR" 4
 306 .IX Item "--use-temp-file"
 307 Use a temporary file to instead of using popen to read the output of
 308 the preprocessor. Use this option if the popen implementation is buggy
 309 on the host (eg., certain non-English language versions of Windows 95 and
 310 Windows 98 are known to have buggy popen where the output will instead
 311 go the console).
 312 .IP "\fB\-\-no\-use\-temp\-file\fR" 4
 313 .IX Item "--no-use-temp-file"
 314 Use popen, not a temporary file, to read the output of the preprocessor.
 315 This is the default behaviour.
 316 .IP "\fB\-h\fR" 4
 317 .IX Item "-h"
 318 .PD 0
 319 .IP "\fB\-\-help\fR" 4
 320 .IX Item "--help"
 321 .PD
 322 Prints a usage summary.
 323 .IP "\fB\-V\fR" 4
 324 .IX Item "-V"
 325 .PD 0
 326 .IP "\fB\-\-version\fR" 4
 327 .IX Item "--version"
 328 .PD
 329 Prints the version number for \fBwindres\fR.
 330 .IP "\fB\-\-yydebug\fR" 4
 331 .IX Item "--yydebug"
 332 If \fBwindres\fR is compiled with \f(CW\*(C`YYDEBUG\*(C'\fR defined as \f(CW1\fR,
 333 this will turn on parser debugging.
 334 .IP "\fB@\fR\fIfile\fR" 4
 335 .IX Item "@file"
 336 Read command-line options from \fIfile\fR.  The options read are
 337 inserted in place of the original @\fIfile\fR option.  If \fIfile\fR
 338 does not exist, or cannot be read, then the option will be treated
 339 literally, and not removed.
 340 .Sp
 341 Options in \fIfile\fR are separated by whitespace.  A whitespace
 342 character may be included in an option by surrounding the entire
 343 option in either single or double quotes.  Any character (including a
 344 backslash) may be included by prefixing the character to be included
 345 with a backslash.  The \fIfile\fR may itself contain additional
 346 @\fIfile\fR options; any such options will be processed recursively.
 347 .SH "SEE ALSO"
 348 .IX Header "SEE ALSO"
 349 the Info entries for \fIbinutils\fR.
 350 .SH "COPYRIGHT"
 351 .IX Header "COPYRIGHT"
 352 Copyright (c) 1991, 1992, 1993, 1994, 1995, 1996, 1997, 1998,
 353 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009,
 354 2010, 2011, 2012
 355 Free Software Foundation, Inc.
 356 .PP
 357 Permission is granted to copy, distribute and/or modify this document
 358 under the terms of the \s-1GNU\s0 Free Documentation License, Version 1.3
 359 or any later version published by the Free Software Foundation;
 360 with no Invariant Sections, with no Front-Cover Texts, and with no
 361 Back-Cover Texts.  A copy of the license is included in the
 362 section entitled \*(L"\s-1GNU\s0 Free Documentation License\*(R".