tools/wrc/README.wrc

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