share/man/man1/windres.1

   1 .\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42)
   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 >0, 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 "2023-04-26" "binutils-2.40.00" "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.  The default preprocessor is \f(CW\*(C`gcc\*(C'\fR.
 249 .IP "\fB\-\-preprocessor\-arg\fR \fIoption\fR" 4
 250 .IX Item "--preprocessor-arg option"
 251 When \fBwindres\fR reads an \f(CW\*(C`rc\*(C'\fR file, it runs it through
 252 the C preprocessor first.  This option may be used to specify additional
 253 text to be passed to preprocessor on its command line.
 254 This option can be used multiple times to add multiple options to the
 255 preprocessor command line.
 256 If the \fB\-\-preprocessor\fR option has not been specified then a
 257 default set of preprocessor arguments will be used, with any
 258 \&\fB\-\-preprocessor\-arg\fR options being placed after them on the
 259 command line.  These default arguments are \f(CW\*(C`\-E\*(C'\fR,
 260 \&\f(CW\*(C`\-xc\-header\*(C'\fR and \f(CW\*(C`\-DRC_INVOKED\*(C'\fR.
 261 .IP "\fB\-I\fR \fIdirectory\fR" 4
 262 .IX Item "-I directory"
 263 .PD 0
 264 .IP "\fB\-\-include\-dir\fR \fIdirectory\fR" 4
 265 .IX Item "--include-dir directory"
 266 .PD
 267 Specify an include directory to use when reading an \f(CW\*(C`rc\*(C'\fR file.
 268 \&\fBwindres\fR will pass this to the preprocessor as an \fB\-I\fR
 269 option.  \fBwindres\fR will also search this directory when looking for
 270 files named in the \f(CW\*(C`rc\*(C'\fR file.  If the argument passed to this command
 271 matches any of the supported \fIformats\fR (as described in the \fB\-J\fR
 272 option), it will issue a deprecation warning, and behave just like the
 273 \&\fB\-J\fR option.  New programs should not use this behaviour.  If a
 274 directory happens to match a \fIformat\fR, simple prefix it with \fB./\fR
 275 to disable the backward compatibility.
 276 .IP "\fB\-D\fR \fItarget\fR" 4
 277 .IX Item "-D target"
 278 .PD 0
 279 .IP "\fB\-\-define\fR \fIsym\fR\fB[=\fR\fIval\fR\fB]\fR" 4
 280 .IX Item "--define sym[=val]"
 281 .PD
 282 Specify a \fB\-D\fR option to pass to the preprocessor when reading an
 283 \&\f(CW\*(C`rc\*(C'\fR file.
 284 .IP "\fB\-U\fR \fItarget\fR" 4
 285 .IX Item "-U target"
 286 .PD 0
 287 .IP "\fB\-\-undefine\fR \fIsym\fR" 4
 288 .IX Item "--undefine sym"
 289 .PD
 290 Specify a \fB\-U\fR option to pass to the preprocessor when reading an
 291 \&\f(CW\*(C`rc\*(C'\fR file.
 292 .IP "\fB\-r\fR" 4
 293 .IX Item "-r"
 294 Ignored for compatibility with rc.
 295 .IP "\fB\-v\fR" 4
 296 .IX Item "-v"
 297 Enable verbose mode.  This tells you what the preprocessor is if you
 298 didn't specify one.
 299 .IP "\fB\-c\fR \fIval\fR" 4
 300 .IX Item "-c val"
 301 .PD 0
 302 .IP "\fB\-\-codepage\fR \fIval\fR" 4
 303 .IX Item "--codepage val"
 304 .PD
 305 Specify the default codepage to use when reading an \f(CW\*(C`rc\*(C'\fR file.
 306 \&\fIval\fR should be a hexadecimal prefixed by \fB0x\fR or decimal
 307 codepage code. The valid range is from zero up to 0xffff, but the
 308 validity of the codepage is host and configuration dependent.
 309 .IP "\fB\-l\fR \fIval\fR" 4
 310 .IX Item "-l val"
 311 .PD 0
 312 .IP "\fB\-\-language\fR \fIval\fR" 4
 313 .IX Item "--language val"
 314 .PD
 315 Specify the default language to use when reading an \f(CW\*(C`rc\*(C'\fR file.
 316 \&\fIval\fR should be a hexadecimal language code.  The low eight bits are
 317 the language, and the high eight bits are the sublanguage.
 318 .IP "\fB\-\-use\-temp\-file\fR" 4
 319 .IX Item "--use-temp-file"
 320 Use a temporary file to instead of using popen to read the output of
 321 the preprocessor. Use this option if the popen implementation is buggy
 322 on the host (eg., certain non-English language versions of Windows 95 and
 323 Windows 98 are known to have buggy popen where the output will instead
 324 go the console).
 325 .IP "\fB\-\-no\-use\-temp\-file\fR" 4
 326 .IX Item "--no-use-temp-file"
 327 Use popen, not a temporary file, to read the output of the preprocessor.
 328 This is the default behaviour.
 329 .IP "\fB\-h\fR" 4
 330 .IX Item "-h"
 331 .PD 0
 332 .IP "\fB\-\-help\fR" 4
 333 .IX Item "--help"
 334 .PD
 335 Prints a usage summary.
 336 .IP "\fB\-V\fR" 4
 337 .IX Item "-V"
 338 .PD 0
 339 .IP "\fB\-\-version\fR" 4
 340 .IX Item "--version"
 341 .PD
 342 Prints the version number for \fBwindres\fR.
 343 .IP "\fB\-\-yydebug\fR" 4
 344 .IX Item "--yydebug"
 345 If \fBwindres\fR is compiled with \f(CW\*(C`YYDEBUG\*(C'\fR defined as \f(CW1\fR,
 346 this will turn on parser debugging.
 347 .IP "\fB@\fR\fIfile\fR" 4
 348 .IX Item "@file"
 349 Read command-line options from \fIfile\fR.  The options read are
 350 inserted in place of the original @\fIfile\fR option.  If \fIfile\fR
 351 does not exist, or cannot be read, then the option will be treated
 352 literally, and not removed.
 353 .Sp
 354 Options in \fIfile\fR are separated by whitespace.  A whitespace
 355 character may be included in an option by surrounding the entire
 356 option in either single or double quotes.  Any character (including a
 357 backslash) may be included by prefixing the character to be included
 358 with a backslash.  The \fIfile\fR may itself contain additional
 359 @\fIfile\fR options; any such options will be processed recursively.
 360 .SH "SEE ALSO"
 361 .IX Header "SEE ALSO"
 362 the Info entries for \fIbinutils\fR.
 363 .SH "COPYRIGHT"
 364 .IX Header "COPYRIGHT"
 365 Copyright (c) 1991\-2023 Free Software Foundation, Inc.
 366 .PP
 367 Permission is granted to copy, distribute and/or modify this document
 368 under the terms of the \s-1GNU\s0 Free Documentation License, Version 1.3
 369 or any later version published by the Free Software Foundation;
 370 with no Invariant Sections, with no Front-Cover Texts, and with no
 371 Back-Cover Texts.  A copy of the license is included in the
 372 section entitled \*(L"\s-1GNU\s0 Free Documentation License\*(R".