binutils/doc/windres.1

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