| blob | c6b590e496bced197854e1567caaec749ea40358 |
1 Release 1.1.8 of wrc (24-Aug-2000), the wine resource compiler.
3 See the file CHANGES for differences between the version and what has been
4 corrected in the current version.
6 Wrc features:
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
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.
25 Wrc command-line
26 ----------------
27 You can get this message by typing 'wrc -?':
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
60 Input is taken from stdin if no sourcefile specified.
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
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]"
76 For more info see the wrc manpage.
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)
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.
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__
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.
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).
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.
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.
156 Example:
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 }
168 Resource types supported
169 ------------------------
170 All types are supported except for:
171 - RT_VXD
172 - RT_PLUGPLAY
173 - RT_HTML
174 - RT_DLGINCLUDE
176 These types will be implemented as soon as I get a proper specification of
177 the layout.
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.
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)
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.
202 Resource names can be both numerical (expressions) and character typed. Wrc
203 does support this insane (deep sigh) construct:
205 MENU MENU
206 {
207 ...
208 }
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!
214 Indirect loadable resources
215 ---------------------------
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':
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;
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;
240 The extension to winerc lies in the addition of the 'typename' field to
241 support usertype resources with names for types.
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!
247 You can also generate header files with wrc when specifying the '-h' or
248 '-H<filename>' option.
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.
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.
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.
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.
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.
290 Reporting bugs and patches
291 --------------------------
292 Send problems to the wine newsgroup or, preferrably, directly to me at:
294 bertho@akhphd.au.dk
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.