tools/wrc/README.wrc

   1 Release 1.1.8 of wrc (24-Aug-2000), the wine resource compiler.
   2
   3 See the file CHANGES for differences between the version and what has been
   4 corrected in the current version.
   5
   6 Wrc features:
   7
   8 - full source preprocessing
   9 - 16 and 32 bit support
  10 - LANGUAGE support (32 bit only)
  11 - most resource types are supported
  12 - enhanced expression capabilities and resource naming
  13 - indirect loadable resources
  14 - NE/PE resource directory generation
  15 - binary .res file generation/reading
  16 - byte-order conversions
  17
  18 Wrc generates an assembly file that can be assembled with GNU's gas, or
  19 passed to gcc. The assembly became necessary for two reasons. First, C does
  20 not ensure relative position of declared data. Secondly, C complains about
  21 complex initialization schemes that became necessary with the NE/PE
  22 directory generation.
  23
  24
  25 Wrc command-line
  26 ----------------
  27 You can get this message by typing 'wrc -?':
  28
  29 Usage: wrc [options...] [infile[.rc|.res]]
  30    -a n        Alignment of resource (win16 only, default is 4)
  31    -b          Create an assembly array from a binary .res file
  32    -B x        Set output byte-order x={n[ative], l[ittle], b[ig]}
  33                (win32 only; default is n[ative] which equals little-endian)
  34    -c          Add 'const' prefix to C constants
  35    -C cp       Set the resource's codepage to cp (default is 0)
  36    -d n        Set debug level to 'n'
  37    -D id[=val] Define preprocessor identifier id=val
  38    -e          Disable recognition of win32 keywords in 16bit compile
  39    -E          Preprocess only
  40    -g          Add symbols to the global c namespace
  41    -h          Also generate a .h file
  42    -H file     Same as -h but written to file
  43    -I path     Set include search dir to path (multiple -I allowed)
  44    -l lan      Set default language to lan (default is neutral {0, 0})
  45    -L          Leave case of embedded filenames as is
  46    -m          Do not remap numerical resource IDs
  47    -n          Do not generate .s file
  48    -N          Do not preprocess input
  49    -o file     Output to file (default is infile.[res|s|h]
  50    -p prefix   Give a prefix for the generated names
  51    -r          Create binary .res file (compile only)
  52    -s          Add structure with win32/16 (PE/NE) resource directory
  53    -V          Print version end exit
  54    -w 16|32    Select win16 or win32 output (default is win32)
  55    -W          Enable pedantic warnings
  56
  57 Input is taken from stdin if no sourcefile specified.
  58
  59 Debug level 'n' is a bitmask with following meaning:
  60     * 0x01 Tell which resource is parsed (verbose mode)
  61     * 0x02 Dump internal structures
  62     * 0x04 Create a parser trace (yydebug=1)
  63     * 0x08 Preprocessor messages
  64     * 0x10 Preprocessor lex messages
  65     * 0x20 Preprocessor yacc trace
  66
  67 The -o option only applies to the final destination file, which is
  68 in case of normal compile a .s file. You must use the '-H header.h'
  69 option to override the header-filename.
  70 If no input filename is given and the output name is not overridden
  71 with -o and/or -H, then the output is written to "wrc.tab.[sh]"
  72
  73 For more info see the wrc manpage.
  74
  75
  76 Preprocessing
  77 -------------
  78 The preprocessor is a fully operational C preprocessor. It handles all
  79 directives supported by ANSI-C. It also includes some additions from
  80 gcc/egcs.
  81 Wrc understands these directives:
  82 #define         (both simple and macro)
  83 #undef
  84 #if
  85 #ifdef
  86 #ifndef
  87 #elif
  88 #else
  89 #endif
  90 #error
  91 #warning
  92 #line
  93 #
  94 #pragma         (ignored)
  95 #ident          (ignored)
  96
  97 The extensions include '#'-line directives.
  98 Not handled at the moment are variable argument macros. They are parsed,
  99 but not expanded properly. This will be corrected in the future.
 100
 101 The preprocessor handles the special defines and aditionally defines an
 102 extra set of defines:
 103   Define       | Value         | Comment
 104 ---------------+---------------+---------------
 105 RC_INVOKED     | 1             | Always defined
 106 __FLAT__       | 1             | Only defined if win32 compile
 107 __WIN32__      | 1             | Only defined if win32 compile
 108 __FILE__       | "..."         | Current filename as string
 109 __LINE__       | nnn           | Current linenumber as integer
 110 __TIME__       | "23:59:59"    | Timestring of compilation
 111 __DATE__       | "May  1 2000" | Datestring of compilation
 112 __WRC__        | 1             | Wrc's major version
 113 __WRC_MINOR__  | 1             | Wrc's minor version
 114 __WRC_MICRO__  | 7             | Wrc's minor version
 115 __WRC_PATCH__  | 8             | Alias of __WRC_MICRO__
 116
 117 Include-files are not read twice if they are protected with this scheme:
 118 #ifndef SOME_DEFINE
 119 #define SOME_DEFINE
 120 ...
 121 #endif
 122 This strategy has been borrowed from gcc/egcs and results in significantly
 123 reduced preprocessing times (20..30%). There must not be any junk before
 124 the first #ifndef and not after the last #endif; comments and whitespace
 125 excepted. Wrc will check the existance of the define prior to inclusion to
 126 detect "#undef SOME_DEFINE" (notably poppack.h) and act accordingly.
 127
 128
 129 16 and 32 bit support
 130 ---------------------
 131 All of wrc is layed out in such a way that it enables compilation of both 16
 132 and 32 bit resources. They mainly differ in code-generation and extra
 133 keywords. Win32 keywords are recognized by default in 16 bit compile. You
 134 can disable recognition of win32 reserved keywords by using the '-e' option,
 135 if you encounter .rc-files that use win32 reserved keywords (I strongly
 136 recommend that you just rename things in the source).
 137
 138
 139 Language support
 140 ----------------
 141 Wrc also understands the LANGUAGE keyword (win32 only) for both global and
 142 local definitions of language. There are differences with respect to MS' and
 143 Borland's implementation. Wrc uses 0,0 as the default language if none is
 144 specified. Both MS and Borland use the language of the system that the
 145 compiler runs on.
 146
 147 Language, version and characteristics can be bound to all resource types that
 148 have inline data, such as RCDATA. This is an extension to MS' resource
 149 compiler, which lacks this support completely. Only VERSIONINFO cannot have
 150 version and characteristics attached, but languages are propagated properly if
 151 you declare it correctly before the VERSIONINFO resource starts.
 152
 153 Example:
 154
 155 1 RCDATA DISCARDABLE
 156 LANGUAGE 1, 0
 157 VERSION 312
 158 CHARACTERISTICS 876
 159 {
 160         1, 2, 3, 4, 5, "and whatever more data you want"
 161         '00 01 02 03 04 05 06 07 08'
 162 }
 163
 164
 165 Resource types supported
 166 ------------------------
 167 All types are supported except for:
 168 - RT_VXD
 169 - RT_PLUGPLAY
 170 - RT_HTML
 171 - RT_DLGINCLUDE
 172
 173 These types will be implemented as soon as I get a proper specification of
 174 the layout.
 175
 176 Font type resources (RT_FONT, RT_FONTDIR) are partially supported and will
 177 be enhanced when I have the complete spec. The font resources work only if
 178 you supply the FONTDIR resource yourself.
 179
 180
 181 Expression capabilities and resource names
 182 ------------------------------------------
 183 You can use an expression in most places where the resource definition
 184 expects a number (except usertype type). Operators supported:
 185 ()      parenthesis
 186 *       multiply
 187 /       divide
 188 +       plus/add
 189 -       minus/substract
 190 |       binary or
 191 &       binary and
 192 ~       binary not (unary operator though)
 193 NOT     ... (sigh)
 194
 195 Plus (+) and minus (-) can both be unary and binary. The NOT operator is
 196 (primarily) used to disable window styles but I strongly suggest to refrain
 197 from using this operator.
 198
 199 Resource names can be both numerical (expressions) and character typed. Wrc
 200 does support this insane (deep sigh) construct:
 201
 202 MENU MENU
 203 {
 204  ...
 205 }
 206
 207 It is _ONLY_ supported for backwards compatibility so that old sources can
 208 be compiled with winelib. DO NOT USE IT IN NEW RESOURCES, PLEASE!
 209
 210
 211 NE/PE resource directory generation
 212 -----------------------------------
 213 A windows executable has a table/directory of resources available in that
 214 module. Wrc will generate this directory with the '-s' option and place it
 215 in the assembly output (and header-file). This will enable the separation
 216 of different modules (dlls) in wine, which is the next project after wrc.
 217
 218 The layout of the PE directory should be exactly like the executable file.
 219 The NE directory layout _DIFFERS_ from the real NE executable in such way
 220 that all offsets to actual resource data are relative to the NE directory and
 221 _NOT_ the beginning of the file.
 222
 223
 224 Binary .res file generation/reading
 225 -----------------------------------
 226 Wrc can both generate (32 and 16 bit) and read (32 bit only) .res-files.
 227 These can be used as intermediate files or binary files can be imported from
 228 other sources. The reading of 16 bit .res-files is on the list for the next
 229 release.
 230
 231 You cannot convert 32 bit .res-files into 16 bit output or vice versa. I
 232 might implement 16 bit res into 32 bit output in the future, but I strongly
 233 oppose to the other way around.
 234
 235
 236 Bugs
 237 ----
 238 Inherent to programs you have bugs. These I know are there, plus a few
 239 things that I noted in the above text (more lack of implementation than bug
 240 though):
 241 - No codepage translation
 242 - UNICODE translations are not/not correct implemented
 243 - No documentation ('wrc -?' gives command-line options and a manpage)
 244 - grep for FIXME in the source
 245 - Memory options are wrong under some conditions. There seems to be a
 246   different action for win32 and win16
 247 - PUSHBOX control is unsupported. The MS docs use it plenty, but neither
 248   MS' nor Borland's compiler supports it.
 249
 250 Reporting bugs and patches
 251 --------------------------
 252 Send problems to the wine newsgroup or, preferrably,  directly to me at:
 253
 254 bertho@akhphd.au.dk
 255
 256 Please send the problematic .rc source with the bug so I can reproduce it.
 257 Patches should _not_ be sent to Alexandre but to me. I will then review the
 258 change and send a full patch to be included into the new wine release (I
 259 prefer 'diff -u' format). You can always upload suggestions to wine
 260 headquarters, but be sure to send me a copy.