| Release 1.1.8 of wrc (24-Aug-2000), the wine resource compiler. |
| |
| See the file CHANGES for differences between the version and what has been |
| corrected in the current version. |
| |
| Wrc features: |
| |
| - full source preprocessing |
| - 16 and 32 bit support |
| - LANGUAGE support (32 bit only) |
| - most resource types are supported |
| - enhanced expression capabilities and resource naming |
| - indirect loadable resources |
| - NE/PE resource directory generation |
| - binary .res file generation/reading |
| - byte-order conversions |
| |
| Wrc generates an assembly file that can be assembled with GNU's gas, or |
| passed to gcc. The assembly became necessary for two reasons. First, C does |
| not ensure relative position of declared data. Secondly, C complains about |
| complex initialization schemes that became necessary with the NE/PE |
| directory generation. |
| |
| |
| Wrc command-line |
| ---------------- |
| You can get this message by typing 'wrc -?': |
| |
| Usage: wrc [options...] [infile[.rc|.res]] |
| -a n Alignment of resource (win16 only, default is 4) |
| -A Auto register resources (only with gcc 2.7 and better) |
| -b Create an assembly array from a binary .res file |
| -B x Set output byte-order x={n[ative], l[ittle], b[ig]} |
| (win32 only; default is n[ative] which equals little-endian) |
| -c Add 'const' prefix to C constants |
| -C cp Set the resource's codepage to cp (default is 0) |
| -d n Set debug level to 'n' |
| -D id[=val] Define preprocessor identifier id=val |
| -e Disable recognition of win32 keywords in 16bit compile |
| -E Preprocess only |
| -g Add symbols to the global c namespace |
| -h Also generate a .h file |
| -H file Same as -h but written to file |
| -I path Set include search dir to path (multiple -I allowed) |
| -l lan Set default language to lan (default is neutral {0, 0}) |
| -L Leave case of embedded filenames as is |
| -m Do not remap numerical resource IDs |
| -n Do not generate .s file |
| -N Do not preprocess input |
| -o file Output to file (default is infile.[res|s|h] |
| -p prefix Give a prefix for the generated names |
| -r Create binary .res file (compile only) |
| -s Add structure with win32/16 (PE/NE) resource directory |
| -t Generate indirect loadable resource tables |
| -T Generate only indirect loadable resources tables |
| -V Print version end exit |
| -w 16|32 Select win16 or win32 output (default is win32) |
| -W Enable pedantic warnings |
| |
| Input is taken from stdin if no sourcefile specified. |
| |
| Debug level 'n' is a bitmask with following meaning: |
| * 0x01 Tell which resource is parsed (verbose mode) |
| * 0x02 Dump internal structures |
| * 0x04 Create a parser trace (yydebug=1) |
| * 0x08 Preprocessor messages |
| * 0x10 Preprocessor lex messages |
| * 0x20 Preprocessor yacc trace |
| |
| The -o option only applies to the final destination file, which is |
| in case of normal compile a .s file. You must use the '-H header.h' |
| option to override the header-filename. |
| If no input filename is given and the output name is not overridden |
| with -o and/or -H, then the output is written to "wrc.tab.[sh]" |
| |
| For more info see the wrc manpage. |
| |
| |
| Preprocessing |
| ------------- |
| The preprocessor is a fully operational C preprocessor. It handles all |
| directives supported by ANSI-C. It also includes some additions from |
| gcc/egcs. |
| Wrc understands these directives: |
| #define (both simple and macro) |
| #undef |
| #if |
| #ifdef |
| #ifndef |
| #elif |
| #else |
| #endif |
| #error |
| #warning |
| #line |
| # |
| #pragma (ignored) |
| #ident (ignored) |
| |
| The extensions include '#'-line directives. |
| Not handled at the moment are variable argument macros. They are parsed, |
| but not expanded properly. This will be corrected in the future. |
| |
| The preprocessor handles the special defines and aditionally defines an |
| extra set of defines: |
| Define | Value | Comment |
| ---------------+---------------+--------------- |
| RC_INVOKED | 1 | Always defined |
| __FLAT__ | 1 | Only defined if win32 compile |
| __WIN32__ | 1 | Only defined if win32 compile |
| __FILE__ | "..." | Current filename as string |
| __LINE__ | nnn | Current linenumber as integer |
| __TIME__ | "23:59:59" | Timestring of compilation |
| __DATE__ | "May 1 2000" | Datestring of compilation |
| __WRC__ | 1 | Wrc's major version |
| __WRC_MINOR__ | 1 | Wrc's minor version |
| __WRC_MICRO__ | 7 | Wrc's minor version |
| __WRC_PATCH__ | 8 | Alias of __WRC_MICRO__ |
| |
| Include-files are not read twice if they are protected with this scheme: |
| #ifndef SOME_DEFINE |
| #define SOME_DEFINE |
| ... |
| #endif |
| This strategy has been borrowed from gcc/egcs and results in significantly |
| reduced preprocessing times (20..30%). There must not be any junk before |
| the first #ifndef and not after the last #endif; comments and whitespace |
| excepted. Wrc will check the existance of the define prior to inclusion to |
| detect "#undef SOME_DEFINE" (notably poppack.h) and act accordingly. |
| |
| |
| 16 and 32 bit support |
| --------------------- |
| All of wrc is layed out in such a way that it enables compilation of both 16 |
| and 32 bit resources. They mainly differ in code-generation and extra |
| keywords. Win32 keywords are recognized by default in 16 bit compile. You |
| can disable recognition of win32 reserved keywords by using the '-e' option, |
| if you encounter .rc-files that use win32 reserved keywords (I strongly |
| recommend that you just rename things in the source). |
| |
| |
| Language support |
| ---------------- |
| Wrc also understands the LANGUAGE keyword (win32 only) for both global and |
| local definitions of language. There are differences with respect to MS' and |
| Borland's implementation. Wrc uses 0,0 as the default language if none is |
| specified. Both MS and Borland use the language of the system that the |
| compiler runs on. |
| |
| Language, version and characteristics can be bound to all resource types that |
| have inline data, such as RCDATA. This is an extension to MS' resource |
| compiler, which lacks this support completely. Only VERSIONINFO cannot have |
| version and characteristics attached, but languages are propagated properly if |
| you declare it correctly before the VERSIONINFO resource starts. |
| |
| Example: |
| |
| 1 RCDATA DISCARDABLE |
| LANGUAGE 1, 0 |
| VERSION 312 |
| CHARACTERISTICS 876 |
| { |
| 1, 2, 3, 4, 5, "and whatever more data you want" |
| '00 01 02 03 04 05 06 07 08' |
| } |
| |
| |
| Resource types supported |
| ------------------------ |
| All types are supported except for: |
| - RT_VXD |
| - RT_PLUGPLAY |
| - RT_HTML |
| - RT_DLGINCLUDE |
| |
| These types will be implemented as soon as I get a proper specification of |
| the layout. |
| |
| Font type resources (RT_FONT, RT_FONTDIR) are partially supported and will |
| be enhanced when I have the complete spec. The font resources work only if |
| you supply the FONTDIR resource yourself. |
| |
| |
| Expression capabilities and resource names |
| ------------------------------------------ |
| You can use an expression in most places where the resource definition |
| expects a number (except usertype type). Operators supported: |
| () parenthesis |
| * multiply |
| / divide |
| + plus/add |
| - minus/substract |
| | binary or |
| & binary and |
| ~ binary not (unary operator though) |
| NOT ... (sigh) |
| |
| Plus (+) and minus (-) can both be unary and binary. The NOT operator is |
| (primarily) used to disable window styles but I strongly suggest to refrain |
| from using this operator. |
| |
| Resource names can be both numerical (expressions) and character typed. Wrc |
| does support this insane (deep sigh) construct: |
| |
| MENU MENU |
| { |
| ... |
| } |
| |
| It is _ONLY_ supported for backwards compatibility so that old sources can |
| be compiled with winelib. DO NOT USE IT IN NEW RESOURCES, PLEASE! |
| |
| |
| Indirect loadable resources |
| --------------------------- |
| |
| Wrc can generate tables for indirect resource loading like winerc did. There |
| are two new structures defined in 'wine-base-dir/include/wrc_rsc.h': |
| |
| typedef struct wrc_resource16 |
| { |
| INT32 resid; /* The resource id if resname == NULL */ |
| LPSTR resname; |
| INT32 restype; /* The resource type-id if typename == NULL */ |
| LPSTR typename; |
| LPBYTE data; /* Actual resource data */ |
| UINT32 datasize; /* The size of the resource */ |
| } wrc_resource16_t; |
| |
| typedef struct wrc_resource32 |
| { |
| INT32 resid; /* The resource id if resname == NULL */ |
| LPWSTR resname; |
| INT32 restype; /* The resource type-id if typename == NULL */ |
| LPWSTR typename; |
| LPBYTE data; /* Actual resource data */ |
| UINT32 datasize; /* The size of the resource */ |
| } wrc_resource32_t; |
| |
| The extension to winerc lies in the addition of the 'typename' field to |
| support usertype resources with names for types. |
| |
| Note that _ALL_ names generated by wrc and to be used in interfacing with |
| wine are PASCAL-style strings, unlike winerc. The first element contains the |
| length and the strings are _not_ '\0'-terminated! |
| |
| You can also generate header files with wrc when specifying the '-h' or |
| '-H<filename>' option. |
| |
| |
| NE/PE resource directory generation |
| ----------------------------------- |
| A windows executable has a table/directory of resources available in that |
| module. Wrc will generate this directory with the '-s' option and place it |
| in the assembly output (and header-file). This will enable the separation |
| of different modules (dlls) in wine, which is the next project after wrc. |
| |
| The layout of the PE directory should be exactly like the executable file. |
| The NE directory layout _DIFFERS_ from the real NE executable in such way |
| that all offsets to actual resource data are relative to the NE directory and |
| _NOT_ the beginning of the file. |
| |
| |
| Binary .res file generation/reading |
| ----------------------------------- |
| Wrc can both generate (32 and 16 bit) and read (32 bit only) .res-files. |
| These can be used as intermediate files or binary files can be imported from |
| other sources. The reading of 16 bit .res-files is on the list for the next |
| release. |
| |
| You cannot convert 32 bit .res-files into 16 bit output or vice versa. I |
| might implement 16 bit res into 32 bit output in the future, but I strongly |
| oppose to the other way around. |
| |
| |
| Bugs |
| ---- |
| Inherent to programs you have bugs. These I know are there, plus a few |
| things that I noted in the above text (more lack of implementation than bug |
| though): |
| - No codepage translation |
| - UNICODE translations are not/not correct implemented |
| - No documentation ('wrc -?' gives command-line options and a manpage) |
| - grep for FIXME in the source |
| - Memory options are wrong under some conditions. There seems to be a |
| different action for win32 and win16 |
| - PUSHBOX control is unsupported. The MS docs use it plenty, but neither |
| MS' nor Borland's compiler supports it. |
| |
| Reporting bugs and patches |
| -------------------------- |
| Send problems to the wine newsgroup or, preferrably, directly to me at: |
| |
| bertho@akhphd.au.dk |
| |
| Please send the problematic .rc source with the bug so I can reproduce it. |
| Patches should _not_ be sent to Alexandre but to me. I will then review the |
| change and send a full patch to be included into the new wine release (I |
| prefer 'diff -u' format). You can always upload suggestions to wine |
| headquarters, but be sure to send me a copy. |
| |