tools/wrc/README.wrc

   1 Release 1.0.2 of wrc (20-Jun-1998), 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 - source preprocessing
   9 - 16 and 32 bit support
  10 - LANGUAGE support (32 bit only)
  11 - almost all 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
  17 Wrc generates an assembly file that can be assembled with GNU's gas, or
  18 passed to gcc. The assembly became necessary for two reasons. First, C does
  19 not ensure relative position of declared data. Secondly, C complaints about
  20 complex initialization schemes that became necessary with the NE/PE
  21 directory generation.
  22
  23
  24 Wrc command-line
  25 ----------------
  26 You can get this message by typing 'wrc -?':
  27
  28 Usage: wrc [options...] [infile[.rc|.res]]
  29    -a n        Alignment of resource (win16 only, default is 4)
  30    -A          Auto register resources (only with gcc 2.7 and better)
  31    -b          Create a C array from a binary .res file
  32    -c          Add 'const' prefix to C constants
  33    -C cp       Set the resource's codepage to cp (default is 0)
  34    -d n        Set debug level to 'n'
  35    -D id[=val] Define preprocessor identifier id=val
  36    -e          Disable recognition of win32 keywords in 16bit compile
  37    -g          Add symbols to the global c namespace
  38    -h          Also generate a .h file
  39    -H file     Same as -h but written to file
  40    -I path     Set include search dir to path (multiple -I allowed)
  41    -l lan      Set default language to lan (default is neutral {0})
  42    -L          Leave case of embedded filenames as is
  43    -n          Do not generate .s file
  44    -o file     Output to file (default is infile.[res|s|h]
  45    -p prefix   Give a prefix for the generated names
  46    -r          Create binary .res file (compile only)
  47    -s          Add structure with win32/16 (PE/NE) resource directory
  48    -t          Generate indirect loadable resource tables
  49    -T          Generate only indirect loadable resources tables
  50    -V          Print version end exit
  51    -w 16|32    Select win16 or win32 output (default is win32)
  52    -W          Enable pedantic warnings
  53
  54 Input is taken from stdin if no sourcefile specified.
  55
  56 Debug level 'n' is a bitmask with following meaning:
  57     * 0x01 Tell which resource is parsed (verbose mode)
  58     * 0x02 Dump internal structures
  59     * 0x04 Create a parser trace (yydebug=1)
  60
  61 The -o option only applies to the final destination file, which is
  62 in case of normal compile a .s file. You must use the '-H header.h'
  63 option to override the header-filename.
  64 If no input filename is given and the output name is not overridden
  65 with -o and/or -H, then the output is written to "wrc.tab.[sh]"
  66
  67
  68 Preprocessing
  69 -------------
  70 The build-in preprocessor is not a full implementation of the C counterpart.
  71 Wrc does not understand function-type macros. These are discarded as they
  72 are scanned. This will be a future project. Wrc does understand these:
  73 #define
  74 #if
  75 #ifdef
  76 #ifndef
  77 #elif
  78 #else
  79 #endif
  80 #error
  81
  82 Also 'defined' is supported as operator (both with and without parenthesis).
  83 '#if' expressions can be anything valid that evaluates to an integer
  84 expression (where 0 is false and anything else is true). Others (#pragma,
  85 #line) are ignored. A special case '#' generates an error. This is due to
  86 the implementation to enable generation of errors on preprocessing and will
  87 be improved in the future.
  88
  89
  90 16 and 32 bit support
  91 ---------------------
  92 All of wrc is layed out in such a way that it enables compilation of both 16
  93 and 32 bit resources. They mainly differ in code-generation and extra
  94 keywords. Win32 keywords are recognized by default in 16 bit compile. You
  95 can disable recognition of win32 reserved keywords by using the '-e' option,
  96 if you encounter .rc-files that use win32 reserved keywords (I strongly
  97 recommend that you just rename things in the source).
  98
  99
 100 Language support
 101 ----------------
 102 Wrc also understands the LANGUAGE keyword (win32 only) for both global and
 103 local definitions of language. There are differences with respect to MS' and
 104 Borland's implementation. Wrc uses 0,0 as the default language if non is
 105 specified. Both MS and Borland use the language of the system that the
 106 compiler runs on.
 107
 108 Not all resource-types can have local language keywords attached yet
 109 (notably: BITMAP, CURSOR, ICON and usertype). This is due to implementation
 110 of filename-scanning and the complexity that it poses. This will be changed
 111 in the next release. You can work arround this problem by putting a LANGUAGE
 112 statement before (and evt. after) the code in the resource file.
 113
 114
 115 Resource types supported
 116 ------------------------
 117 All types are supported except for:
 118 - FONT
 119 - MESSAGETABLE
 120 - extensions like TOOLBAR and the like (is this a user-type?)
 121
 122 These types will be implemented as soon as I get a proper specification of
 123 the layout.
 124
 125 Note: Usertype resources with character strings as types have a different
 126 layout and do not accept expressions when a numerical type is specified. The
 127 must be enclosed in double quotes. These are examples of valid usertype
 128 resources:
 129
 130 MyName "MyType" mydata.bin
 131 MyName 12345    mydata.bin
 132 MyName "MyType" "mydata.bin"
 133 MyName 12345    "mydata.bin"
 134
 135 MyName "MyType"
 136 {
 137   ..., data, ...
 138 }
 139
 140 or
 141
 142 MyName 12345
 143 {
 144  ..., data, ...
 145 }
 146
 147
 148 Expression capabilities and resource names
 149 ------------------------------------------
 150 You can use an expression in most places where the resource definition
 151 expects a number (except usertype type). Operators supported:
 152 ()      parenthesis
 153 *       multiply
 154 /       divide
 155 +       add
 156 -       minus/substract
 157 |       binary or
 158 &       binary and
 159 ~       binary not (unary operator though)
 160 NOT     ... (sigh)
 161
 162 Minus (-) can both be unary and binary. The NOT operator is (primarily)
 163 used to disable window styles but I strongly suggest to refrain from using
 164 this operator.
 165 There is a shift/reduce conflict on the unary minus, but this is not
 166 problematic. I was too lazy to make a new expression parser (next version or
 167 so). Unary plus (+) would cause another confilct, so I let it out for now.
 168
 169 Resource names can be both numerical (expressions) and character typed. Wrc
 170 does supports this insane (deep sigh) construct:
 171
 172 MENU MENU
 173 {
 174  ...
 175 }
 176
 177 It is _ONLY_ supported for backwards compatibility so that old sources can
 178 be compiled with winelib. DO NOT USE IT IN NEW RESOURCES, PLEASE!
 179
 180
 181 Indirect loadable resources
 182 ---------------------------
 183
 184 Wrc can generate tables for indirect resource loading like winerc did. There
 185 are two new structures defined in 'wine-base-dir/include/wrc_rsc.h':
 186
 187 typedef struct wrc_resource16
 188 {
 189         INT32   resid;          /* The resource id if resname == NULL */
 190         LPSTR   resname;
 191         INT32   restype;        /* The resource type-id if typename == NULL */
 192         LPSTR   typename;
 193         LPBYTE  data;           /* Actual resource data */
 194         UINT32  datasize;       /* The size of the resource */
 195 } wrc_resource16_t;
 196
 197 typedef struct wrc_resource32
 198 {
 199         INT32   resid;          /* The resource id if resname == NULL */
 200         LPWSTR  resname;
 201         INT32   restype;        /* The resource type-id if typename == NULL */
 202         LPWSTR  typename;
 203         LPBYTE  data;           /* Actual resource data */
 204         UINT32  datasize;       /* The size of the resource */
 205 } wrc_resource32_t;
 206
 207 The extension to winerc lies in the addition of the 'typename' field to
 208 support usertype resoursec with names for types.
 209
 210 Note that _ALL_ names generated by wrc and to be used in interfacing with
 211 wine are PASCAL-style strings, unlike winerc. The first element contains the
 212 length and the strings are _not_ '\0'-terminated!
 213
 214 You can also generate header files with wrc when specifying the '-h' or
 215 '-H<filename>' option.
 216
 217
 218 NE/PE resource directory generation
 219 -----------------------------------
 220 A windows executable has a table/directory of resources avalable in that
 221 module. Wrc will generate this directory with the '-s' option and place it
 222 in the assembly output (and header-file). This will enable the separation
 223 of different modules (dlls) in wine, which is the next project after wrc.
 224
 225 The layout of the PE directory should be exactly like the executable file.
 226 The NE-directory layout _DIFFERS_ from the real NE-executable in such way
 227 that all offsets to actual resource-data is relative to the NE-directory and
 228 _NOT_ the beginning of the file.
 229
 230
 231 Binary .res file generation/reading
 232 -----------------------------------
 233 Wrc can both generate (32 and 16 bit) and read (32 bit only) .res-files.
 234 These can be used as intermediate files or binary files can be imported from
 235 other sources. The reading of 16 bit .res-files is on the list for the next
 236 release.
 237
 238 You cannot convert 32 bit .res-files into 16 bit output or vice versa. I
 239 might implement 16 bit res into 32 bit output in the future, but I stronly
 240 oppose to the other way arround.
 241
 242
 243 Bugs
 244 ----
 245 Inherent to programs you have bugs. These I know are there, plus a few
 246 things that I noted in the above text (more lack of implementation than bug
 247 though):
 248 - No codepage translation
 249 - UNICODE translations are not/not correct implemented
 250 - No documentation ('wrc -?' gives command-line options though)
 251 - grep for FIXME in the source
 252 - Memory options are wrong under some conditions. There seems to be a
 253   different action for win32 and win16.
 254 - User-type resources have slightly different layout.
 255 - Filename scanning is still hopeless.
 256
 257 Reporting bugs and patches
 258 --------------------------
 259 Send problems to the wine newsgroup or, preferrably,  directly to me at:
 260
 261 bertho@akhphd.au.dk
 262
 263 Please send the problematic rc-source with the bug so I can reproduce it.
 264 Patches should _not_ be send to Alexandre but to me. I will then review the
 265 change and send a full patch to be included into the new wine release (I
 266 prefer 'diff -u' format). You can always upload suggestions to wine
 267 headquarters, but be sure to send me a copy.
 268