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