source: trunk/tools/wrc/README.wrc@ 10367

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 complaints 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 a C array from a binary .res file
   -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 non 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 resoursec 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 avalable 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 is 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 stronly
oppose to the other way arround.


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 send 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.