[prev in list] [next in list] [prev in thread] [next in thread]
List: haiku-commits
Subject: [haiku-commits] haiku: hrev57717 - src/bin/rc/docs docs/develop/build/rc
From: Adrien Destugues <pulkomandy () pulkomandy ! tk>
Date: 2024-04-29 11:59:15
Message-ID: 20240429115915.08168433E1 () turing ! freelists ! org
[Download RAW message or body]
hrev57717 adds 1 changeset to branch 'master'
old head: 0128458ef2f4973f32912ea68ac185973e119a64
new head: 9f3bdf3d039430b5172c424def20ce5d9f7367d4
overview: https://git.haiku-os.org/haiku/log/?qt=range&q=9f3bdf3d0394+%5E0128458ef2f4
----------------------------------------------------------------------------
9f3bdf3d0394: rc: migrate documentation to Haiku internals pages
[ Adrien Destugues <adrien.destugues@opensource.viveris.fr> ]
----------------------------------------------------------------------------
Revision: hrev57717
Commit: 9f3bdf3d039430b5172c424def20ce5d9f7367d4
URL: https://git.haiku-os.org/haiku/commit/?id=9f3bdf3d0394
Author: Adrien Destugues <adrien.destugues@opensource.viveris.fr>
Date: Mon Apr 29 11:58:25 2024 UTC
----------------------------------------------------------------------------
16 files changed, 1246 insertions(+), 946 deletions(-)
docs/develop/build/index.rst | 1 +
docs/develop/build/rc/beres-deres.rst | 77 +++++
docs/develop/build/rc/grammar.rst | 480 ++++++++++++++++++++++++++++
docs/develop/build/rc/history.rst | 30 ++
docs/develop/build/rc/index.rst | 12 +
docs/develop/build/rc/librdef.rst | 54 ++++
docs/develop/build/rc/notes.rst | 76 +++++
docs/develop/build/rc/rc.rst | 507 ++++++++++++++++++++++++++++++
docs/develop/build/rc/todo.rst | 9 +
src/bin/rc/docs/beres-deres.html | 60 ----
src/bin/rc/docs/grammar.html | 309 ------------------
src/bin/rc/docs/history.html | 36 ---
src/bin/rc/docs/librdef.html | 64 ----
src/bin/rc/docs/notes.html | 43 ---
src/bin/rc/docs/rc.html | 412 ------------------------
src/bin/rc/docs/todo.html | 22 --
----------------------------------------------------------------------------
diff --git a/docs/develop/build/index.rst b/docs/develop/build/index.rst
index 0c4337375b..775d12af52 100644
--- a/docs/develop/build/index.rst
+++ b/docs/develop/build/index.rst
@@ -7,5 +7,6 @@ The build system
/build/jam
/build/sourcecode
/build/compilers
+ /build/rc/index
/build/ide
/build/repositories/README
diff --git a/docs/develop/build/rc/beres-deres.rst \
b/docs/develop/build/rc/beres-deres.rst new file mode 100644
index 0000000000..e1ac21e378
--- /dev/null
+++ b/docs/develop/build/rc/beres-deres.rst
@@ -0,0 +1,77 @@
+Differences with beres/deres
+############################
+
+Some of your old rdef files may fail to compile with rc. Besides different command \
line arguments, +rc also has slightly different syntax and semantics. These changes \
were made to allow for the future +expansion of the rdef grammar and to make resource \
scripts easier to write and understand. The +compiler should be backwards compatible \
with the majority of old scripts, but in some cases it was +necessary to break stuff.
+
+Differences with beres
+======================
+
+We allow the \0 escape in string literals.
+
+Our handling of the minus sign is more restrictive; we don't treat it like a unary \
minus operator, +which means you may only put one minus in front of a number to \
negate it (i.e. "- -10" is an error). +
+beres allows #define statements, but apparently ignores them. The compiler reports \
no error, but +any symbols you define are not recognized later on. We don't allow \
#defines (yet). +
+beres allows you to put enum symbols in resource data, and replaces the symbol with \
its value. For +some reason, it lets you assign any kind of data to enum symbols, \
such as strings and floats. Since +that is not valid C/C++ syntax, librdef does not \
allow this. As a result, it does not make much +sense for us to support enum symbols \
in resource data. +
+We only allow a few type casts, but enough to be backwards compatible. beres allows \
you to cast +from bool to all other types, between strings and numeric types, etc. \
The usefulness of this is +limited, so to keep things simple librdef doesn't allow \
that. +
+There is no need to put parentheses around a type code, even for simple data; beres \
sometimes +requires the parens and sometimes it doesn't. With rc, they are always \
optional (preferred notation +is without the parens).
+
+beres allows multiple type codes and/or type casts per resource statement/data \
field, but we allow +only one of each. Because we don't associate type codes with \
data (but only with the resource +itself or with individual message fields), we don't \
allow the shortcut notation that lets you put a +type code and cast inside one set of \
parentheses. +
+We do not allow arrays to have named fields, nor do we allow messages (and archives) \
to have +unnamed fields. beres apparently treats all compound data the same, but we \
don't, because not all +compound data is the same.
+
+When specifying array data, the "array" keyword is required. beres allows you to \
omit the array +keyword and just put the data between braces, but that conflicts with \
our handling of user-defined +types.
+
+Field names in message resources may only be string literals. beres allows \
identifiers but it +converts them to string literals anyway. Just like normal data, \
you may cast the field's data to a +different type, but not to a different type code. \
Specifying a non-standard type code is fine, but +it goes in front of the type name. \
Just like beres, rc considers "array", "message", and "archive" +to be valid data \
type names, but "message" and "archive" cannot be followed by a "what" code +(beres \
ignores that anyway). When you cast an archive to a message, we don't strip the \
"class" +field (in fact, we don't perform any conversion).
+
+We allow users to define their own types. The built-in types from beres (point, \
rect, and rgb_color) +are re-implemented as such user-defined types. The syntax for \
these three built-ins should still be +backwards compatible with old scripts.
+
+beres automatically adds names for resources that are specified as \
"resource(R_Symbol)", unless the +"explicit names only" option is set. We do that the \
other way around: we don't automatically add +names unless the user sets the "auto \
names" option. +
+Differences with deres
+======================
+
+We do not write the "generated at" time into the files.
+
+Type codes that cannot be represented as #'xxxx' are written as #num where num is a \
decimal number, not hexadecimal. +
+Floats and doubles have a bunch of extra zeroes.
+
+Hex numbers are always uppercase.
+
+We may render string literals somewhat differently.
+
+We only write a header file if the "auto names" option is set.
+
diff --git a/docs/develop/build/rc/grammar.rst b/docs/develop/build/rc/grammar.rst
new file mode 100644
index 0000000000..d4df4ea5ff
--- /dev/null
+++ b/docs/develop/build/rc/grammar.rst
@@ -0,0 +1,480 @@
+rdef grammar
+============
+
+This is the (somewhat boring) specification of the rdef file format as it is \
understood by librdef. +It also describes to a certain extent how the compiler works. \
You don't need to read this unless +you want to hack librdef. Knowledge of compiler \
theory and lex/yacc is assumed. +
+The lexer
+---------
+
+Like any compiler, librdef contains a lexer (aka scanner) and a parser. The lexer \
reads the input +file and chops it up into tokens. The lexer ignores single-line \
``//`` comments and ``/* ... */`` +multi-line comments. It also ignores whitespace \
and newlines. +
+The lexer recognizes the following tokens:
+
+BOOL
+ true or false
+
+INTEGER
+ You can specify integers as decimal numbers, hexadecimal numbers (starting with \
0x or 0X, alpha + digits are case insensitive), octal numbers (starting with a \
leading 0), binary numbers + (starting with 0b or 0B), or as a four character code \
('CCCC'). Valid range is 64 bits. At + this point, numbers are always unsigned. \
The minus sign is treated as a separate token, and is + dealt with by the parser.
+
+FLOAT
+ A floating point literal. Must contain a decimal point, may contain a signed \
exponent. Stored internally as a double. +
+STRING
+ UTF-8 compatible string literal, enclosed by double quotes. Can contain escape \
sequences + (\b \f \n \r \t \v \" \\ \0), octal escapes (\000) and hex escapes \
(\0x00 or \x00). May not + span more than one line, although you are allowed to \
specify multiple string literals in a row + and the lexer will automatically \
concatenate them. There is no maximum length. +
+RAW
+ Hexadecimal representation of raw data, enclosed by double quotes, and prefixed \
by a dollar + sign: $"12FFAB". Each byte is represented by two hex characters, so \
there must be an even + number of characters between the quotes. The alpha digits \
are not case sensitive. Like STRING, + a RAW token may not span more than one \
line, but multiple consecutive RAW tokens are + automatically concatenated. No \
maximum length. +
+IDENT
+ C/C++ identifier. First character is alphabetic or underscore. Other characters \
are + alphanumeric or underscore.
+
+TYPECODE
+ A hash sign followed by a 32-bit unsigned decimal number, hex number, or four \
character code. + Examples: #200, #0x00C8, #'MIMS'
+
+The following are treated as keywords and special symbols:
+
+``enum resource array message archive type import { } ( ) , ; = - + * / % ^ | & \
~`` +
+The lexer also deals with #include statements, which look like: #include \
"filename"\n. When you +#include a file, the lexer expects it to contain valid rdef \
syntax. So even though the include file +is probably a C/C++ header, it should not \
contain anything but the enum statement and/or comments. +The lexer only looks for \
include files in the include search paths that you have specified, so if +you want it \
to look in the current working directory you have to explicitly specify that. You may \
+nest #includes. +
+A note about UTF-8. Since the double quote (hex 0x22) is never part of the second or \
third byte of +a UTF-8 character, the lexer can safely deal with UTF-8 characters \
inside string literals. That is +also the reason that the decompiler does not escape \
characters that are not human-readable +(except the ones in the 7-bit ASCII range), \
because they could be part of a UTF-8 encoding. +The current version of librdef does \
not handle L"..." (wide char) strings, but nobody uses them anyway. +
+The parser
+----------
+
+The parser takes the tokens from the lexer and matches them against the rules of the \
grammar. What +follows is the grammar in a simplified variation of BNF, so the actual \
bison source file may look +a little different. Legend:
+
++-------------+-------------------------------------+
+| `[ a ]` | match a 0 or 1 times |
++-------------+-------------------------------------+
+| `{ b }` | match b 0 or more times |
++-------------+-------------------------------------+
+| `c | d` | match either c or d |
++-------------+-------------------------------------+
+| `( e f )` | group e and f together |
++-------------+-------------------------------------+
+| lowercase | nonterminal |
++-------------+-------------------------------------+
+| UPPER | token from the lexer |
++-------------+-------------------------------------+
+| `'c'` | token from the lexer |
++-------------+-------------------------------------+
+
+The rdef grammar consists of the following rules:
+
+
+script
+ {enum | typedef | resource}
+
+enum
+ ENUM '{' [symboldef {',' symboldef} [',']] '}' ';'
+
+symboldef
+ IDENT ['=' integer]
+
+typedef
+ TYPE [id] [TYPECODE] IDENT '{' fielddef {',' fielddef} '}' ';'
+
+fielddef
+ datatype IDENT ['[' INTEGER ']'] ['=' expr]
+
+resource
+ RESOURCE [id] [typecode] expr ';'
+
+id
+ '(' [(integer | IDENT) [',' STRING] | STRING] ')'
+
+typecode
+ ['('] TYPECODE [')']
+
+expr
+ expr BINARY_OPER expr | UNARY_OPER expr | data
+
+data
+ [typecast] (BOOL | integer | float | STRING | RAW | array | message | archive | \
type | define | '(' expr ')' ) +
+typecast
+ ['(' datatype ')']
+
+datatype
+ ARRAY | MESSAGE | ARCHIVE IDENT | IDENT
+
+integer
+ ['-'] INTEGER
+
+float
+ ['-'] FLOAT
+
+array
+ ARRAY ['{' [expr {',' expr}] '}'] | [ARRAY] IMPORT STRING
+
+message
+ MESSAGE ['(' integer ')'] ['{' [msgfield {',' msgfield}] '}']
+
+msgfield
+ [TYPECODE] [datatype] STRING '=' expr
+
+archive
+ ARCHIVE [archiveid] IDENT '{' msgfield {',' msgfield} '}'
+
+archiveid
+ '(' [STRING] [',' integer] ')'
+
+type
+ IDENT [data | '{' [typefield {',' typefield}] '}']
+
+typefield
+ [IDENT '='] expr
+
+define
+ IDENT
+
+Semantics
+---------
+
+Resource names
+##############
+
+There are several different ways to specify the ID and name of a new resource:
+
+``resource``
+ The resource is assigned the default name and ID of its data type.
+
+``resource()``
+ The resource is assigned the default name and ID of its data type.
+
+``resource(1)``
+ The resource is assigned the numeric ID 1, and the default name of its data \
type. +
+``resource("xxx")``
+ The resource is assigned the name "xxx" and the default ID of its data type.
+
+``resource(1, "xxx")``
+ The resource is assigned the numeric ID 1, and the name "xxx".
+
+``resource(sss)``
+ The resource is assigned the numeric ID that corresponds with the symbol sss, \
which should have + been defined in an enum earlier. If the "auto names" option is \
passed to the compiler, the + resource is also given the name "sss", otherwise the \
default name from its data type is used +
+``resource(sss, "xxx")``
+ The resource is assigned the numeric ID that corresponds with the symbol sss, \
and the name "xxx". +
+Data types and type casts
+#########################
+
+Resources (and message fields) have a type code and a data type. The data type \
determines the +format the data is stored in, while the type code tells the user how \
to interpret the data. +Typically, there is some kind of relation between the two, \
otherwise the resource will be a little +hard to read.
+
+The following table lists the compiler's built-in data types. (Users can also define \
their own +types; this is described in a later section.)
+
++---------+----------------+
+| bool | B_BOOL_TYPE |
++---------+----------------+
+| int8 | B_INT8_TYPE |
++---------+----------------+
+| uint8 | B_UINT8_TYPE |
++---------+----------------+
+| int16 | B_INT16_TYPE |
++---------+----------------+
+| uint16 | B_UINT16_TYPE |
++---------+----------------+
+| int32 | B_INT32_TYPE |
++---------+----------------+
+| uint32 | B_UINT32_TYPE |
++---------+----------------+
+| int64 | B_INT64_TYPE |
++---------+----------------+
+| uint64 | B_UINT64_TYPE |
++---------+----------------+
+| size_t | B_SIZE_T_TYPE |
++---------+----------------+
+| ssize_t | B_SSIZE_T_TYPE |
++---------+----------------+
+| off_t | B_OFF_T_TYPE |
++---------+----------------+
+| time_t | B_TIME_TYPE |
++---------+----------------+
+| float | B_FLOAT_TYPE |
++---------+----------------+
+| double | B_DOUBLE_TYPE |
++---------+----------------+
+| string | B_STRING_TYPE |
++---------+----------------+
+| raw | B_RAW_TYPE |
++---------+----------------+
+| array | B_RAW_TYPE |
++---------+----------------+
+| buffer | B_RAW_TYPE |
++---------+----------------+
+| message | B_MESSAGE_TYPE |
++---------+----------------+
+| archive | B_MESSAGE_TYPE |
++---------+----------------+
+
+The type code has no effect on how the data is stored. For example, if you do this:
+"resource(x) #'LONG' true", then the data will not automatically be stored as a \
32-bit number! +If you don't specify an explicit type code, the compiler uses the \
type of the data for that. +
+You can change the data type with a type cast. The following casts are allowed:
+
++--------------------+--------------------------------------------------------------------------+
+| bool | You cannot cast bool data. \
| ++--------------------+--------------------------------------------------------------------------+
+| integer | You can cast to all numeric data types. Casts to smaller \
datatypes will | +| | truncate the number. Casting negative \
numbers to unsigned datatypes (and | +| | vice versa) will wrap \
them, i.e. (uint8) -1 becomes 255. | \
++--------------------+--------------------------------------------------------------------------+
+| floating point | You can only cast to float or double. \
| ++--------------------+--------------------------------------------------------------------------+
+| string | You cannot cast string data. \
| ++--------------------+--------------------------------------------------------------------------+
+| raw, buffer, array | You can cast anything to raw, but not the other way around. \
| ++--------------------+--------------------------------------------------------------------------+
+| message, archive | You cannot cast message data. \
| ++--------------------+--------------------------------------------------------------------------+
+| type | You cannot cast user-defined types. \
| ++--------------------+--------------------------------------------------------------------------+
+
+In addition to the "simple" built-in data types, the compiler also natively supports \
several data +structures from the BeOS API (point, rect, rgb_color) and a few \
convenience types (app_signature, +app_flags, etc). These types all follow the same \
rules as user-defined types. +
+Arrays
+######
+
+The following definitions are semantically equivalent:
+
+.. code-block:: c
+
+ resource(x) $"AABB";
+ resource(x) array { $"AA" $"BB" };
+ resource(x) array { $"AA", $"BB" };
+
+The comma is optional and simply concatenates the two literals. When you decompile \
this code, +it always looks like:
+
+.. code-block:: c
+
+ resource(x) $"AABB";
+
+Strings behave differently. The following two definitions are equivalent, and \
concatenate the two +literals into one string:
+
+.. code-block::
+
+ resource(x) "AA" "BB";
+ resource(x) #'CSTR' array { "AA" "BB" };
+
+However, if you put a comma between the the strings, the compiler will still glue \
them together +but with a '\0' character in the middle. Now the resource contains \
*two* strings: "AA" and "BB". +You can also specify the '\0' character yourself:
+
+.. code-block::
+
+ resource(x) "AA\0BB";
+ resource(x) #'CSTR' array { "AA", "BB" };
+
+The following is not proper grammar; use an array instead:
+
+.. code-block:: c
+
+ resource(x) "AA", "BB";
+ resource(x) $"AA", $"BB";
+
+Note that the data type of an array is always raw data, no matter how you specify \
its contents. +Because raw literals may be empty ($""), so may arrays.
+
+Messages and archives
+#####################
+
+A message resource is a flattened BMessage. By default it has the data type \
B_MESSAGE_TYPE and +corresponding type code #'MSGG'. If you don't specify a "what" \
code for the message, it defaults to 0. +
+Message fields assume the type of their data, unless you specify a different type in \
front of the +field name. (Normal casting rules apply here.) You can also give the \
field a different type code, +which tells the BMessage how to interpret the data, but \
not how it is stored in the message. +This type code also goes in front of the field \
name. You can give the same name to multiple fields, +provided that they all have the \
same type. (The data of these fields does not have to be the same +size.) A message \
may be empty; it is still a valid BMessage, but it contains no fields. +
+An archive is also a flattened BMessage, but one that was made by Archive()'ing a \
BArchivable class, +such as BBitmap. The name of the archive, in this case BBitmap, \
is automatically added to the +message in a field called "class". The "archive" \
keyword is optionally followed by a set of +parentheses that enclose a string and/or \
an integer. The int is the "what" code, the string is +stored in a field called \
"add_on" (used for dynamic loading of BArchivables). Other than that, +archives and \
messages are identical. The compiler does not check whether the contents of the \
+archive actually make sense, so if you don't structure the data properly you may be \
unable to +unarchive the object later. Unlike a message, an archive may not be empty, \
because that is pointless. +
+User-defined types
+##################
+
+We allow users to define their own types. A "type" is just a fancy array, because \
the data from the +various fields is simply concatenated into one big block of bytes. \
The difference is that +user-defined types are much easier to fill in.
+
+A user-defined type has a symbolic name, a type code, and a number of data fields. \
After all the +fields have been concatenated, the type code is applied to the whole \
block. So, the data type of +this resource is always the same as its type code \
(unlike arrays, which are always raw data). +If no type code is specified, it \
defaults to B_RAW_TYPE. +
+The data fields always have a default value. For simple fields this is typically 0 \
(numeric types) +or empty (string, raw, message). The default value of a user-defined \
type as a whole is the +combination of the default values of its fields. Of course, \
the user can specify other defaults. +(When a user creates a new resource that uses \
such a type, he is basically overriding the default +values with his own.)
+
+The user may fill in the data fields by name, by order, or using a combination of \
both. Every time +the compiler sees an unnamed data item, it stuffs it into the next \
available field. Named data +items are simply assigned to the field with the same \
name, and may overwrite a value that was +previously put there "by order". Any fields \
that are not filled in keep their default value. For +example:
+
+.. code-block:: c
+
+ type vector { int32 x, int32 y, int32 z, int32 w = 4 };
+ resource(1) vector { 1, 3, x = 2 };
+
+Here, x is first set to 1, y is set to 3, x is now overwritten by the value 2, z is \
given the +default value 0, and w defaults to 4.
+
+Note: if a user-defined type contains string, raw, or message fields, the size of \
the type depends +on the data that the user puts into it, because these fields have a \
variable size. However, the +user may specify a fixed size for a field (number of \
bytes, enclosed in square brackets following +the field name). In this case, data \
that is too long will be truncated and data that is too short +will be padded with \
zeroes. You can do this for all types, but it really only makes sense for +strings \
and raw data. More about this in the manual. +
+A type definition may also contain a default resource ID and name. The default ID of \
built-in types +is usually 1 and the name is empty (NULL). For example:
+
+.. code-block:: c
+
+ type(10, "MyName") mytype { int32 a };
+ resource mytype 123;
+
+The resource is now called "MyName" and has ID 10. Obviously you can only do this \
once or you will +receive a duplicate resource error. If this type is used inside an \
array or other compound type, +the default ID and resource name are ignored. Note: \
this feature introduces a shift/reduce conflict +in the compiler:
+
+.. code-block:: c
+
+ resource (int8) 123;
+
+This probably doesn't do what you expect. The compiler now considers the "(int8)" to \
be the +resource ID, not a typecast. If you did not declare "int8" in an enum \
(probably not), this gives a +compiler error. Not a big problem, because it is \
unlikely that you will ever do this. Here is a +workaround:
+
+.. code-block:: c
+
+ resource() (int8) 123;
+
+The grammar and Bison
+#####################
+
+Above I mentioned one of the shift/reduce conflicts from the grammar. There are \
several others. +These are mostly the result of keeping the original grammar intact \
as much as possible, without +having to introduce weird syntax rules for the new \
features. These issues aren't fatal but if you +try to do something funky in your \
script, you may get an error message. +
+The main culprit here is the "( expr )" rule from "data", which allows you to nest \
expressions with +parens, e.g. "`(10 + 5) * 3`". This causes problems for Bison, \
because we already use parens all +over the place. Specifically, this rule conflicts \
with the empty "MESSAGE" from the "message" rule, +"ARRAY" from "array", and "IDENT" \
from "type". These rules have no other symbols following them, +which makes them \
ambiguous with respect to the "datatype" rules. Still with me? The parser will \
+typically pick the right one, though. +
+The nested expressions rule also caused a reduce/reduce conflict. To get rid of \
that, I had to +explicitly mention the names of the various types in the "typecast" \
rule, which introduces a little +code duplication but it's not too bad. Just so you \
know, the original rule was simply: +
+.. code-block::
+
+ typecast
+ : '(' datatype ')' { $$ = $2; }
+ ;
+
+The new rule is a little more bulky:
+
+.. code-block::
+
+ typecast
+ : '(' ARRAY ')' { ... }
+ | '(' MESSAGE ')' { ... }
+ ... and so on for all the datatypes ...
+ ;
+
+The unary minus operator is not part of the "expr" (or "data") rules, but of \
"integer" and "float". +This also causes a shift/reduce warning.
+
+And finally, "type" is a member of "data" which is called by "expr". One of the \
rules of "type" +refers back to "expr". This introduces a recursive dependency and a \
whole bunch of shift/reduce +conflicts. Fortunately, it seems to have no bad side \
effects. Yay! +
+Symbol table
+############
+
+The compiler uses two symbol tables: one for the enum symbols, and one with the data \
type +definitions. We need those tables to find the numeric ID/type definition that \
corresponds with an +identifier, and to make sure that there are no duplicate or \
missing identifiers. These two symbol +tables are independent, so you may use the \
same identifier both as an enum symbol and a type name. +
+The compiler does not need to keep a symbol table for the resources. Although the \
combination of a +resource's ID and its type code must be unique, we can use the \
BResources class to check for this +when we add a resource. There is no point in \
duplicating this functionality in the compiler. +(However, if we are merging the new \
resources into an existing resource file, we will simply +overwrite duplicates.)
+
+Misc remarks
+############
+
+As the grammar shows, the last field in an enum statement may be followed by a \
comma. This is +valid C/C++ syntax, and since the enum will typically end up in a \
header file, we support that +feature as well. For anything else between braces, the \
last item may not be followed by a comma. +
+The type code that follows the "resource" keyword may be enclosed by parens for \
historical reasons. +The preferred notation is without, just like in front of field \
names (where no parens are allowed). +
+Even though "ARCHIVE IDENT" is a valid data type, we simply ignore the identifier \
for now. Maybe +later we will support casting between different archives or whatever. \
For now, casting to an +archive is the same as casting to a message, since an archive \
is really a message. +
+User-defined types and defines have their own symbol tables. Due to the way the \
parser is +structured, we can only distinguish between types and defines by matching \
the identifier against +both symbol tables. Here types have priority, so you could \
'shadow' a define with a type name if +you were really evil. Maybe it makes sense for \
rc to use one symbol table for all things in the +future, especially since we're \
using yet another table for enums. We'll see.
diff --git a/docs/develop/build/rc/history.rst b/docs/develop/build/rc/history.rst
new file mode 100644
index 0000000000..01ab3279c0
--- /dev/null
+++ b/docs/develop/build/rc/history.rst
@@ -0,0 +1,30 @@
+History
+#######
+
+This is the change history of the rc resource compiler and librdef.
+
+Version 1.1 (December 22, 2003)
+===============================
+
+You can now import the contents of external files (such as pictures) into array \
resources or fields. This does away with the need to convert (large) binary files \
into text form. +
+You can now give type fields a fixed size, which can be handy for certain kinds of \
string or raw data resources (for example, app_version). +
+You can now use built-in symbolic constants such as B_SINGLE_LAUNCH for setting the \
app_flags and +app_version resources. There is no facility for defining your own \
symbols yet. (In case you were +wondering, no, you cannot use the enum statement for \
that.) +
+Added limited support for numerical expressions. You can now do simple math like `(1 \
+ 2) * 3`. +Only a few operators are supported, you can only use integer operands, \
and the results are always +cast to 32-bit integer as well. This should be more than \
enough for now; expressions can be made +more powerful in the future should the need \
arise. You'll use this feature mostly for OR'ing and +AND'ing symbolic constants (see \
above) together to make your scripts more readable. +
+Line number counter was not reset properly when compiling multiple rdef files in one \
go. +
+Bumped the API version number of librdef.so to 2.
+
+Version 1.0 (February 16, 2003)
+===============================
+
+Initial release
diff --git a/docs/develop/build/rc/index.rst b/docs/develop/build/rc/index.rst
new file mode 100644
index 0000000000..8355de1ee5
--- /dev/null
+++ b/docs/develop/build/rc/index.rst
@@ -0,0 +1,12 @@
+The rc resource compiler
+====================
+
+.. toctree::
+
+ /build/rc/rc
+ /build/rc/grammar
+ /build/rc/librdef
+ /build/rc/beres-deres
+ /build/rc/history
+ /build/rc/todo
+ /build/rc/notes
diff --git a/docs/develop/build/rc/librdef.rst b/docs/develop/build/rc/librdef.rst
new file mode 100644
index 0000000000..81f52fd29d
--- /dev/null
+++ b/docs/develop/build/rc/librdef.rst
@@ -0,0 +1,54 @@
+The librdef library
+===================
+
+Of course, it would be cool if other applications (such as GUI resource editors) \
could also import +and export rdef files. That is why the bulk of rc's functionality \
is implemented in a separate +shared library, librdef.so.
+
+Using the library in your own applications is very simple. Here are some quick \
instructions to get +you started:
+
+1. ``#include "rdef.h"`` in your sources
+2. link your app to librdef.so
+
+The API is rather bare-bones, but it gets the job done. The library uses files to \
transfer data to +and from your application. This may seem odd, but it is actually a \
big advantage. After calling the +API functions to compile an rdef file, you can use \
the standard BResources class to read the +resources from the output file. Chances \
are high that your application already knows how to do this. +
+To compile a resource file, the steps are typically this:
+
+
+1. Call ``rdef_add_include_dir()`` one or more times to add include file search \
paths. +2. Call ``rdef_add_input_file()`` one or more times to add the rdef files \
that you want to compile. +3. Call ``rdef_set_flags()`` to toggle compiler options.
+4. Call ``rdef_compile()`` with the name of the output file. This performs the \
actual compilation. +5. Call ``rdef_free_input_files()`` to clear the list of input \
files that you added earlier. +6. Call ``rdef_free_include_dirs()`` to clear the list \
of include directories that you added earlier. +
+Decompiling is very similar, although include directories are not used here:
+
+1. Call ``rdef_add_input_file()`` one or more times to add the resource files that \
you want to decompile. +2. Call ``rdef_set_flags()`` to toggle compiler options.
+3. Call ``rdef_decompile()`` with the name of the output file. The name of the \
header file (if any) will be automatically constructed by appending ".h" to the \
output file name. +4. Call ``rdef_free_input_files()`` to clear the list of input \
files that you added earlier. +
+If one of these functions returns something other than B_OK, an error occurred. You \
can look at the +following variables to find out more about the error, and construct \
meaningul error messages: +
+rdef_err
+ The error code that was returned.
+
+rdef_err_line
+ The line number where compilation failed.
+
+rdef_err_file
+ The file where the error occurred.
+
+rdef_err_msg
+ The error message from the compiler.
+
+For more information about using librdef, see "rdef.h", which explains the available \
functions and +data structures in more depth. For a real-world example, take a look \
at "rc.cpp", which contains +the complete implementation of the rc compiler. As \
you'll see, there really isn't much to it, +because librdef already does all the \
work.
diff --git a/docs/develop/build/rc/notes.rst b/docs/develop/build/rc/notes.rst
new file mode 100644
index 0000000000..f965426963
--- /dev/null
+++ b/docs/develop/build/rc/notes.rst
@@ -0,0 +1,76 @@
+Work notes
+==========
+
+These are my notes on the evolution of rc. I used to keep these in separate files on \
my development +machine, but it makes more sense to include them here. Warning: geeky \
stuff ahead. +
+Unlike in most parsers, the unary minus operator is currently not part of the 'data' \
rules, but + of 'integer' and 'float'. When expression support is more complete, it \
may make more sense to put + this in 'data'. However, 'integer' is used in other \
places as well and these places allow + negative numbers too. Maybe we can replace \
the calls to 'integer' with 'data' and allow the data + to the integer only (by \
always trying to cast it, perhaps). Then you can do stuff like + `resource(10 + 1) \
123;` But maybe that goes too far. +
+When filling in boolean fields of user-defined types or messages, you can do either
+ `field = true` or `field = false`. I thought it would be nice if you could also do \
just + `field` and `!field`. However, that introduced a reduce/reduce conflict in \
the parser. You see, + the name of the field is an IDENT token, but we already have \
something like that in the 'type' + rule of 'data'. The parser doesn't know what the \
IDENT is supposed to be: the name of the boolean + field or the name of the type. \
Maybe there is a solution for this by shuffling around the parser + rules a bit.
+
+Support for the built-in types point, rect, and rgb_color is currently hardcoded \
into the + decompiler. The other built-in types -- app_flags, mini_icon, etc -- are \
not supported at all. + It would be better to use the type symbol table for this as \
well. Then the decompiler can also + support user-defined types (although these type \
definitions must be provided to the decompiler + somehow). This is advanced stuff \
that probably no one will ever use. +
+The builtin types are added to the symbol table "by hand". You can see this near the \
bottom of + 'parser.y'. This is a bit cumbersome, so I have devised an alternative. \
We put the builtin type + definitions in an rdef script and install this in a \
"standard include dir", for example: + ~/config/include/rc. Before it compiles the \
user's rdef files, the compiler first loads all + scripts from that standard folder. \
(This also allows us to use these rdef files for decompiling, + and users can simply \
install their own. See above.) +
+In "auto names" mode, the decompiler currently does not use the enum symbol table. \
So if two + resources have the same name and that name is a valid C/C++ identifier, \
the decompiler will add + two conflicting symbols to the enum statement. This can \
also happen when multiple input file + have conflicting resource IDs.
+
+When you decompile certain apps (BeMail, Slayer) and then compile these rdef files \
again, the + archive and message fields in the new .rsrc file are larger than the \
original's. I think this is + because rc doesn't add the message fields as \
"fixedSize" (see the BMessage docs from the BeBook). + This doesn't really hurt, \
though, since the BMessage will be properly unflattened regardless. +
+Right now, archives are treated as messages. Maybe we should give them their own \
type, + B_ARCHIVED_OBJECT (type code 'ARCV').
+
+New options, stolen from other resource compilers (rez and beres):
+
+-D --define symbol[=value]
+ set the value of symbol to value (or 1 if no value supplied)
+
+--no-names
+ do not write any names in resource file
+
+-h
+ write resource as C struct in a header file
+
+-d
+ dump resource to stdout
+
+Attributes. I would be nice to have a tool that can take text-based descriptions of \
attributes and +write out an attribute file. Of course, rc is the ideal candidate for \
this, since it already does +the same for resources. However, resources and \
attributes are not the same. Attributes are +name/data pairs. The name should be \
unique. They don't have IDs. They do have a type code, but it +isn't used to identify \
the attribute. It is probably best to add a new kind of definition: +attribute(). \
Should this statement allow only simple data, or must attributes be able to handle \
+flattened messages, arrays, etc too? A source file should either contain resource() \
statements or +attribute() statements, not both.
+
+User-defined symbolic constants. To keep things simple, adding a #define keyword \
would suffice, +although this always creates global symbols so there is a chance of \
name collisions. In addition +(or instead) we can extend user-defined types to have \
their own (local) defines too. If we use the +#define keyword, we should infer the \
type of the constant from the data (100 is integer, 10.5 is a +float, etc). This is \
necessary because we don't have a separate preprocessor step like C/C++ does -- +that \
is why our symbolic constants are typed.
diff --git a/docs/develop/build/rc/rc.rst b/docs/develop/build/rc/rc.rst
new file mode 100644
index 0000000000..5612d45047
--- /dev/null
+++ b/docs/develop/build/rc/rc.rst
@@ -0,0 +1,507 @@
+Introduction
+============
+
+In the world of BeOS programming, a "resource" is data that is bundled with your \
application. +Typical examples are the application's icons and its signature, but you \
can attach any data you +want (bitmaps, text, cursors, etc). You stuff this data into \
a .rsrc file that will be linked to +your application when it is compiled.
+
+Because .rsrc files have a binary file format, you need to use special tools to edit \
them, such as +FileTypes, QuickRes, or Resourcer. Alternatively, you can use a \
"resource compiler". This is a +command line tool that takes a text-based resource \
script and turns it into a .rsrc file. +
+With a resource compiler, you express your resources as ASCII text using a special \
definition +language, which makes the resource files much easier to edit and \
maintain. You no longer need +separate GUI tools to build your .rsrc files, and you \
can even automate the whole process by +calling the compiler from your Makefile or \
Jamfile. Resource scripts will also make your life +easier if you use version \
control, because version control doesn't handle .rsrc files very well. +
+BeOS R5 comes with an (experimental) resource compiler called "beres", and a \
corresponding +decompiler called "deres". rc is an open source replacement (and \
enhancement) of these tools. It +is (mostly) backwards compatible, so you should be \
able to compile your old .rdef files without any +problems.
+
+How to install
+==============
+
+- Copy ``rc`` into ``/boot/home/config/non-packaged/bin``
+- Copy ``librdef.so`` into ``/boot/home/config/non-packaged/lib``
+- Let's party!
+
+Note: rc comes preinstalled in Haiku already.
+
+Writing resource scripts
+========================
+
+Writing resource scripts is not difficult, although the syntax may take some getting \
used to. A +resource script is a plain text file with one or more resource definition \
statements. In addition, +it may contain C or C++ style comments. By convention, \
resource script files have the extension ".rdef". +
+Here is an example of a simple resource script:
+
+.. code-block:: c
+
+ resource(1) true; /* this is a comment */
+ resource(2) 123; // and so is this
+ resource(3) 3.14;
+ resource(4) "hello world";
+ resource(5) $"0123456789ABCDEF";
+
+When compiled, this script produces a resource file with five resources. The above \
example also +illustrates the types of data that resources are allowed to have: \
boolean, integer, floating point, +character string (UTF-8), and raw data buffer \
(hexadecimal). +
+By default, integer data is stored as a 32-bit int, and floating point data is \
stored as a 4-byte +float. If you want to change the way the data is stored, you have \
to cast it: +
+.. code-block:: c
+
+ resource(6) (int8) 123;
+ resource(7) (double) 3.14;
+
+You can cast integer data to the following types: int8, uint8, int16, uint16, int32, \
uint32, int64, +uint64, ssize_t, size_t, off_t, time_t, float, double, raw. You can \
cast floating point data to: +float, double, raw. You are not allowed to cast \
boolean, string, or raw data to other types. +
+In addition to casting, you can also change the resource's type code. This does not \
change the way +the data is stored, only what it is called. To change the type code \
of a resource: +
+.. code-block::
+
+ resource(8) #'dude' 123;
+
+This changes the type of resource 8 to the four-character-code 'dude'. If you did \
not change it, it +would be 'LONG', which stands for 32-bit integer. By changing the \
type code, you assign a new +meaning to the resource. You can also specify type codes \
as decimal or hexadecimal numbers: +
+.. code-block::
+
+ resource(9) #200 123;
+ resource(10) #0xC8 123;
+
+For historical reasons, you may also enclose the type code in parens, but that is \
not the preferred +notation. Type casts and type codes can be combined:
+
+.. code-block::
+
+ resource(11) #'dude' (int8) 123;
+ resource(11) (#'dude') (int8) 123;
+
+In the above examples, we have given the resources numeric IDs. The combination of \
ID and type code +must be unique in the resource file; you cannot have two int32 \
resources with ID 1, for example. +However, it is perfectly fine (but not necessarily \
a good idea) to do the following, because the +data types are different:
+
+.. code-block:: c
+
+ resource(12) 123;
+ resource(12) "w00t!";
+
+For your own convenience, you can also name resources. Unlike the ID/type code \
combination, names +do not have to be unique.
+
+.. code-block:: c
+
+ resource(13, "Friday") "Bad Luck";
+
+You can also do simple maths. The emphasis here is on simple because the number of \
operators is +limited, they only work on integer data (or anything that can be cast \
to integer), and the result +is always 32-bit integer as well. Still, the lazy \
amongst you may find it handy: +
+.. code-block:: c
+
+ resource(14) 2 * (4 + 3);
+
+Since it is likely that you will be using these resources from a C/C++ program, it \
may be +convenient to refer to them by symbolic names instead of hardcoded numeric \
ID's. The rdef format +allows you to do this:
+
+.. code-block:: c
+
+ {
+ R_AppName = 1,
+ R_SomeOtherThing = 2
+ };
+
+ resource(R_AppName) "MyKillerApp";
+
+The compiler will automatically substitute the symbol R_AppName with the number 1. \
(You don't have +to start these symbol names with the prefix ``R_``, but it is \
somewhat of a convention.) +
+Now how do you tell your C/C++ app about these symbolic names? You simply put the \
enum into a +header file that you include both from your application's source code \
and your rdef file. The +header file, which we'll call "myresources.h", now looks \
like this: +
+.. code-block:: c
+
+ {
+ R_AppName = 1,
+ R_SomeOtherThing = 2
+ }
+
+And the rdef file becomes this:
+
+.. code-block:: c
+
+ #include "myresources.h"
+
+ resource(R_AppName) "MyKillerApp";
+
+Don't let the .h suffix fool you: the header file is still considered to be an rdef \
file, and must +contain valid rdef syntax. If you add any other C/C++ code, your \
resource script will fail to +compile. Of course, you shouldn't add any other rdef \
syntax to the header either (unless you want +your C++ compiler to start \
complaining). Besides comments, the only safe thing to put in that +header file is \
the enum statement, because both rdef and C/C++ understand it. +
+Just like IDs, symbolic identifiers can be combined with a name:
+
+.. code-block:: c
+
+ resource(R_AppName, "AppName") "MyKillerApp";
+
+If you don't specify a name, and invoke the compiler with the ``--auto-names`` \
option, it +automatically uses the symbolic ID for the name as well. So the ID of the \
following resource is 1 +(because that is what R_AppName corresponds to) and its name \
becomes "R_AppName": +
+.. code-block:: c
+
+ resource(R_AppName) "MyKillerApp";
+
+Big fat resources
+=================
+
+The resources we have made so far consisted of a single data item, but you can also \
supply a +collection of data values. The simplest of these compound data structures \
is the array: +
+.. code-block:: c
+
+ resource(20) array { 1234, 5678 };
+
+An array is nothing more than a raw buffer. The above statement takes the two 32-bit \
integers 1234 +and 5678 and stuffs them into a new 64-bit buffer. You can put any \
kind of data into an array, even +other arrays:
+
+.. code-block:: c
+
+ resource(21) array
+ {
+ "hello",
+ 3.14,
+ true,
+ array { "a", "nested", "array" },
+ $"AABB"
+ };
+
+It is up to you to remember the structure of this array, because array resources \
don't keep track +of what kind of values you put into them and where you put these \
values. For that, we have messages. +A message resource is a flattened BMessage:
+
+.. code-block::
+
+ resource(22) message('blah')
+ {
+ "Name" = "Santa Claus",
+ "Number" = 3.14,
+ "Array" = array { "a", "nested", "array" },
+ "Other Msg" = message { "field" = "value" }
+ };
+
+A message has an optional "what" code, in this case 'blah', and one or more fields. \
A field has a +name (between double quotes), a value, and a data type. By default, \
the field assumes the type of +its data, but you can also specify an explicit data \
type and type code in front of the field name: +
+.. code-block::
+
+ resource(23) message('bla2')
+ {
+ "integer1" = (int8) 123, // use cast to change data type
+ int16 "integer2" = 12345, // specify data type
+ #'dude' "buffer1" = $"aabbccdd", // specify a new type code
+ #'dude' raw "buffer2" = $"aabbccdd" // you can also combine them
+ };
+
+A special type of message is the "archive". The BeOS API allows you to take a \
BArchivable class an +flatten it into a BMessage. You can also add such archives to \
your resource scripts: +
+.. code-block::
+
+ resource(24) #'BBMP' archive BBitmap
+ {
+ "_frame" = rect { 0.0, 0.0, 63.0, 31.0 },
+ "_cspace" = 8200,
+ "_bmflags" = 1,
+ "_rowbytes" = 256,
+ "_data" = array
+ {
+ ... /* here goes the bitmap data */ ...
+ }
+ };
+
+So what's this "rect" thing in the "_frame" field? Besides arrays and messages, the \
compiler also +supports a number of other data structures from the BeAPI:
+
++-----------+-------------------------+--------------------------------+
+| Type | Corresponds to | Fields |
++===========+=========================+================================+
+| point | BPoint, B_POINT_TYPE | float x, y |
++-----------+-------------------------+--------------------------------+
+| rect | BRect, B_RECT_TYPE | float left, top, right, bottom |
++-----------+-------------------------+--------------------------------+
+| rgb_color | rgb_color, B_COLOR_TYPE | uint8 red, greed, blue, alpha |
++-----------+-------------------------+--------------------------------+
+
+To add a color resource to your script, you can do:
+
+.. code-block:: c
+
+ resource(25) rgb_color { 255, 128, 0, 0 };
+
+Or you can use the field names, in which case the order of the fields does not \
matter: +
+.. code-block:: c
+
+ resource(26) rgb_color
+ {
+ blue = 0, green = 128, alpha = 0, red = 255
+ };
+
+You can also make your own data structures, or as we refer to them, "user-defined \
types". Suppose +that your application wants to store its GUI elements in the \
resources: +
+.. code-block::
+
+ type #'menu' menu
+ {
+ string name,
+ int32 count, // how many items
+ array items // the menu items
+ };
+
+ type #'item' menuitem
+ {
+ string name,
+ message msg,
+ bool enabled = true // default value is "true"
+ };
+
+A type has a name, an optional type code, and one or more fields. You are advised \
not to pick a +type code that already belongs to one of the built-in types, to avoid \
any confusion. Each field has +a data type, a name, and a default value. If you don't \
specify a default, it is typically 0 or +empty. To create a new menu resource using \
the types from the above example, you might do: +
+.. code-block::
+
+ resource(27) menu
+ {
+ name = "File",
+ count = 3,
+ items = array
+ {
+ menuitem { "New...", message('fnew') },
+ menuitem { "Print...", message('fprt'), false },
+ menuitem { "Exit", message('_QRQ') }
+ }
+ };
+
+Like an array, a type resource doesn't remember its internal structure. You can \
regard types as +fancy arrays that are easier to fill in, a template if you will. \
User-defined types work under the +same rules as the built-in types point, rect, and \
rgb_color, so you can specify the fields in order +or by their names. If you don't \
specify a field, its default value will be used. +
+Types can also have a default resource ID and/or name. If you omit to give the \
resource an ID or a +name, it uses the defaults from its data type. For example, \
this: +
+.. code-block:: c
+
+ type myint { int32 i };
+ resource(10, "MyName") myint { 123 };
+
+Is equivalent to this:
+
+.. code-block:: c
+
+ type(10, "MyName") myint { int32 i };
+ resource myint { 123 };
+
+And to save you even more typing, simple types that have only one field can also be \
specified as: +
+.. code-block:: c
+
+ resource myint 123;
+
+Most data types have a fixed size; a uint16 is always 2 bytes long, a float always \
comprises 4 +bytes, and so on. But the sizes of string and raw data resources depend \
on what you put in them. +Sometimes you may want to force these kinds of resources to \
have a fixed size as well. You can do +this as follows:
+
+.. code-block:: c
+
+ type fixed { string s[64] };
+
+Any resources with type "fixed" will always contain a 64-byte string, no matter how \
many characters +you actually specify. Too much data will be truncated; too little \
data will be padded with zeroes. +Note that string resources are always terminated \
with a null character, so string "s" in the above +type only allows for 63 real \
characters. The number between the square brackets always indicates +bytes (unlike \
C/C++ arrays which use a similar notation). +
+If you have (large) binary files that you want to include in the resources, such as \
pictures of +Buffy, you don't need to convert the binary data to text form first. You \
can simply "import" the +file:
+
+.. code-block::
+
+ resource(22) #'PNG ' import "buffy.png";
+
+Imported resources are always arrays (raw data), and you can specify the import \
statement +everywhere that array data is valid.
+
+Application resources
+=====================
+
+All BeOS applications (except command line apps) have a basic set of resources, such \
as a MIME +signature, launch flags, icons, and a few others. Adding these kinds of \
resources is easy, because +rc also has a number of built-in types for that:
+
++---------------+------------------------------+--------------------------------------------------+
+| Type | Corresponds to | Fields \
| ++===============+==============================+==================================================+
+| app_signature | the apps's MIME signature | string signature \
| ++---------------+------------------------------+--------------------------------------------------+
+| app_flags | the application launch flags | uint32 flags \
| ++---------------+------------------------------+--------------------------------------------------+
+| app_version | version information | uint32 major, middle, minor, \
variety, internal | +| | | string \
short_info, long_info | \
++---------------+------------------------------+--------------------------------------------------+
+| large_icon | 32x32 icon | array of 1024 bytes \
| ++---------------+------------------------------+--------------------------------------------------+
+| mini_icon | 16x16 icon | array of 256 bytes \
| ++---------------+------------------------------+--------------------------------------------------+
+| vector_icon | HVIF vector icon (type VICN) | array of bytes \
| ++---------------+------------------------------+--------------------------------------------------+
+| file_types | supported file types | message \
| ++---------------+------------------------------+--------------------------------------------------+
+
+Here are some examples on how to use these resources. These things are also \
documented in the +Storage Kit section of the BeBook, so refer to that for more \
information. +
+The signature:
+
+.. code-block:: c
+
+ resource app_signature "application/x-vnd.YourName.YourApp";
+
+The application flags determine how your application is launched. You must 'OR' \
together a combination of the following symbols: +
+- ``B_SINGLE_LAUNCH``
+- ``B_MULTIPLE_LAUNCH``
+- ``B_EXCLUSIVE_LAUNCH``
+- ``B_BACKGROUND_APP``
+- ``B_ARGV_ONLY``
+
+For example:
+
+.. code-block:: c
+
+ resource app_flags B_SINGLE_LAUNCH | B_BACKGROUND_APP;
+
+The version information resource contains a number of fields for you to fill in. \
Most are pretty +obvious, except maybe for the "variety" field. It can take one of \
the following values: +
+``B_APPV_DEVELOPMENT``
+ development version
+
+``B_APPV_ALPHA``
+ alpha version
+
+``B_APPV_BETA``
+ beta version
+
+``B_APPV_GAMMA``
+ gamma version
+
+``B_APPV_GOLDEN_MASTER``
+ golden master
+
+``B_APPV_FINAL``
+ release version
+
+For example:
+
+.. code-block:: c
+
+ resource app_version
+ {
+ major = 1,
+ middle = 0,
+ minor = 0,
+ variety = B_APPV_BETA,
+ internal = 0,
+ short_info = "My Cool Program",
+ long_info = "My Cool Program - Copyright Me"
+ };
+
+The supported file types resource contains a list of MIME types, not unlike this:
+
+.. code-block:: c
+
+ resource file_types message
+ {
+ "types" = "text/plain",
+ "types" = "text"
+ };
+
+Compiling
+=========
+
+rc is a command line tool, which means you must run it from a Terminal window. \
Typical usage example: +
+.. code-block:: sh
+
+ rc -o things.rsrc things.rdef
+
+This tells rc that you wish to compile the script "things.rdef" to the resource file \
"things.rsrc". +The default name for the output file is "out.rsrc", but you can \
change that with the ``-o`` +or ``--output`` switch, just like we did here.
+
+You can specify multiple rdef files if you wish, and they will all be compiled into \
one big +resource file. If your rdef files #include files that are not in the current \
working directory, +you can add include paths with the ``-I`` or ``--include`` \
option. For a complete list of options, +type ``rc --help``.
+
+If your project uses a Makefile, you can have rc automatically generate the resource \
file for you: +
+.. code-block:: make
+
+ things.rsrc: things.rdef
+ rc -o $@ $^</PRE></BLOCKQUOTE>
+
+.. TODO: also explain how to integrate rc in jamfiles
+
+Decompiling
+===========
+
+Of course you can write the resource scripts by hand, but if you already have a \
.rsrc file you can +tell rc to decompile it. This will produce a ready-to-go rdef \
script, and save you some trouble. +(Although in some cases it may be necessary to \
edit the script a little to suit your needs.) Note +that rc isn't limited to just \
.rsrc files; you can decompile any file that has resources, +including applications.
+
+For example, to decompile the file "things.rsrc" into "things.rdef", do:
+
+.. code-block:: sh
+
+ rc --decompile -o things.rdef things.rsrc
+
+The decompiler produces an rdef resource script with the name "out.rdef", but you \
can change that +name with the ``-o`` or ``--output`` switches. If you specify the \
``--auto-names`` option, rc will also +write a C/C++ header file. Any resources whose \
name is a valid C/C++ identifier will be added to +the header file. Now your program \
can access the resource using this symbolic name. +
+Note: Even though rc can decompile multiple .rsrc files into one script, it does not \
detect +conflicts in resource names or IDs. In such cases, the resulting .rdef and/or \
.h files may give +errors when you try to compile them.
+
+Authors
+=======
+
+The rc resource compiler and its companion library librdef were written by `Matthijs \
Hollmans <mailto:mahlzeit@users.sourceforge.net>`_ for the `Haiku \
<http://www.haiku-os.org>`_ project. Thanks to Ingo Weinhold for the Jamfile and the \
Jam rules. Comments, bug reports, suggestions, and patches are \
welcome!
diff --git a/docs/develop/build/rc/todo.rst b/docs/develop/build/rc/todo.rst
new file mode 100644
index 0000000000..7eef1691c9
--- /dev/null
+++ b/docs/develop/build/rc/todo.rst
@@ -0,0 +1,9 @@
+Ye Olde To Do List
+##################
+
+What will future versions of rc bring? Here are some ideas.
+
+- Attributes, so you can also use rdef scripts to add attributes to your files \
instead of (or in addition to) resources. +- Expand the expressions to handle other \
data types besides integer data. This would include floating point (+ - * /), string \
(+), raw (+), and booleans (! && ||). +- Allow users to create their own \
symbolic constants. +
diff --git a/src/bin/rc/docs/beres-deres.html b/src/bin/rc/docs/beres-deres.html
deleted file mode 100644
index 429b7f3266..0000000000
--- a/src/bin/rc/docs/beres-deres.html
+++ /dev/null
@@ -1,60 +0,0 @@
-<HTML>
-<HEAD>
-<TITLE>Differences with beres/deres</TITLE>
-</HEAD>
-<BODY BGCOLOR="#FFFFFF">
-
-<H1>Differences with beres/deres</H1>
-
-<P>Some of your old rdef files may fail to compile with rc. Besides different \
command line arguments, rc also has slightly different syntax and semantics. These \
changes were made to allow for the future expansion of the rdef grammar and to make \
resource scripts easier to write and understand. The compiler should be backwards \
compatible with the majority of old scripts, but in some cases it was necessary to \
break stuff.</P>
-
-<H2>Differences with beres</H2>
-
-<UL>
-
-<LI>We allow the \0 escape in string literals.</LI>
-
-<LI>Our handling of the minus sign is more restrictive; we don't treat it like a \
unary minus operator, which means you may only put one minus in front of a number to \
negate it (i.e. "- -10" is an error).</LI>
-
-<LI>beres allows #define statements, but apparently ignores them. The compiler \
reports no error, but any symbols you define are not recognized later on. We don't \
allow #defines (yet).</LI>
-
-<LI>beres allows you to put enum symbols in resource data, and replaces the symbol \
with its value. For some reason, it lets you assign any kind of data to enum symbols, \
such as strings and floats. Since that is not valid C/C++ syntax, librdef does not \
allow this. As a result, it does not make much sense for us to support enum symbols \
in resource data.</LI>
-
-<LI>We only allow a few type casts, but enough to be backwards compatible. beres \
allows you to cast from bool to all other types, between strings and numeric types, \
etc. The usefulness of this is limited, so to keep things simple librdef doesn't \
allow that.</LI>
-
-<LI>There is no need to put parentheses around a type code, even for simple data; \
beres sometimes requires the parens and sometimes it doesn't. With rc, they are \
always optional (preferred notation is without the parens).</LI>
-
-<LI>beres allows multiple type codes and/or type casts per resource statement/data \
field, but we allow only one of each. Because we don't associate type codes with data \
(but only with the resource itself or with individual message fields), we don't allow \
the shortcut notation that lets you put a type code and cast inside one set of \
parentheses.</LI>
-
-<LI>We do not allow arrays to have named fields, nor do we allow messages (and \
archives) to have unnamed fields. beres apparently treats all compound data the same, \
but we don't, because not all compound data is the same.</LI>
-
-<LI>When specifying array data, the "array" keyword is required. beres allows you to \
omit the array keyword and just put the data between braces, but that conflicts with \
our handling of user-defined types.</LI>
-
-<LI>Field names in message resources may only be string literals. beres allows \
identifiers but it converts them to string literals anyway. Just like normal data, \
you may cast the field's data to a different type, but not to a different type code. \
Specifying a non-standard type code is fine, but it goes in front of the type name. \
Just like beres, rc considers "array", "message", and "archive" to be valid data type \
names, but "message" and "archive" cannot be followed by a "what" code (beres ignores \
that anyway). When you cast an archive to a message, we don't strip the "class" field \
(in fact, we don't perform any conversion).</LI>
-
-<LI>We allow users to define their own types. The built-in types from beres (point, \
rect, and rgb_color) are re-implemented as such user-defined types. The syntax for \
these three built-ins should still be backwards compatible with old \
scripts.</LI>
-
-<LI>beres automatically adds names for resources that are specified as \
"resource(R_Symbol)", unless the "explicit names only" option is set. We do that the \
other way around: we don't automatically add names unless the user sets the "auto \
names" option.</LI>
-
-</UL>
-
-<H2>Differences with deres:</H2>
-
-<UL>
-
-<LI>We do not write the "generated at" time into the files.</LI>
-
-<LI>Type codes that cannot be represented as #'xxxx' are written as #num where num \
is a decimal number, not hexadecimal.</LI>
-
-<LI>Floats and doubles have a bunch of extra zeroes.</LI>
-
-<LI>Hex numbers are always uppercase.</LI>
-
-<LI>We may render string literals somewhat differently.</LI>
-
-<LI>We only write a header file if the "auto names" option is set.</LI>
-
-</UL>
-
-</BODY>
-</HTML>
diff --git a/src/bin/rc/docs/grammar.html b/src/bin/rc/docs/grammar.html
deleted file mode 100644
index b67c5292d3..0000000000
--- a/src/bin/rc/docs/grammar.html
+++ /dev/null
@@ -1,309 +0,0 @@
-<HTML>
-<HEAD>
-<TITLE>rdef grammar</TITLE>
-</HEAD>
-
-<BODY BGCOLOR="#FFFFFF">
-
-<H1>rdef grammar</H1>
-
-<P>Version 1.1</P>
-
-<P>This is the (somewhat boring) specification of the rdef file format as it is \
understood by librdef. It also describes to a certain extent how the compiler works. \
You don't need to read this unless you want to hack librdef. Knowledge of compiler \
theory and lex/yacc is assumed.</P>
-
-<H2>The lexer</H2>
-
-<P>Like any compiler, librdef contains a lexer (aka scanner) and a parser. The lexer \
reads the input file and chops it up into tokens. The lexer ignores single-line // \
comments and /* ... */ multi-line comments. It also ignores whitespace and \
newlines.</P>
-
-<P>The lexer recognizes the following tokens:</P>
-
-<BLOCKQUOTE><TABLE BORDER=1 SUMMARY="">
-
-<TR><TD WIDTH="20%">BOOL</TD><TD>true or false</TD></TR>
-
-<TR><TD>INTEGER</TD><TD>You can specify integers as decimal numbers, hexadecimal \
numbers (starting with 0x or 0X, alpha digits are case insensitive), octal numbers \
(starting with a leading 0), binary numbers (starting with 0b or 0B), or as a four \
character code ('CCCC'). Valid range is 64 bits. At this point, numbers are always \
unsigned. The minus sign is treated as a separate token, and is dealt with by the \
parser.</TD></TR>
-
-<TR><TD>FLOAT</TD><TD>A floating point literal. Must contain a decimal point, may \
contain a signed exponent. Stored internally as a double.</TD></TR>
-
-<TR><TD>STRING</TD><TD>UTF-8 compatible string literal, enclosed by double quotes. \
Can contain escape sequences (\b \f \n \r \t \v \" \\ \0), octal escapes (\000) and \
hex escapes (\0x00 or \x00). May not span more than one line, although you are \
allowed to specify multiple string literals in a row and the lexer will automatically \
concatenate them. There is no maximum length.</TR>
-
-<TR><TD>RAW</TD><TD>Hexadecimal representation of raw data, enclosed by double \
quotes, and prefixed by a dollar sign: $"12FFAB". Each byte is represented by two hex \
characters, so there must be an even number of characters between the quotes. The \
alpha digits are not case sensitive. Like STRING, a RAW token may not span more than \
one line, but multiple consecutive RAW tokens are automatically concatenated. No \
maximum length.</TD></TR>
-
-<TR><TD>IDENT</TD><TD>C/C++ identifier. First character is alphabetic or underscore. \
Other characters are alphanumeric or underscore.</TD></TR>
-
-<TR><TD>TYPECODE</TD><TD>A hash sign followed by a 32-bit unsigned decimal number, \
hex number, or four character code. Examples: #200, #0x00C8, \
#'MIMS'</TD></TR>
-
-</TABLE></BLOCKQUOTE>
-
-<P>The following are treated as keywords and special symbols:</P>
-
-<BLOCKQUOTE><CODE>enum resource array message archive type import { } ( ) , ; = - + \
* / % ^ | & ~</CODE></BLOCKQUOTE>
-
-<P>The lexer also deals with #include statements, which look like: #include \
"filename"\n. When you #include a file, the lexer expects it to contain valid rdef \
syntax. So even though the include file is probably a C/C++ header, it should not \
contain anything but the enum statement and/or comments. The lexer only looks for \
include files in the include search paths that you have specified, so if you want it \
to look in the current working directory you have to explicitly specify that. You may \
nest #includes.</P>
-
-<P>A note about UTF-8. Since the double quote (hex 0x22) is never part of the second \
or third byte of a UTF-8 character, the lexer can safely deal with UTF-8 characters \
inside string literals. That is also the reason that the decompiler does not escape \
characters that are not human-readable (except the ones in the 7-bit ASCII range), \
because they could be part of a UTF-8 encoding. The current version of librdef does \
not handle L"..." (wide char) strings, but nobody uses them \
anyway.</P>
-
-<H2>The parser</H2>
-
-<P>The parser takes the tokens from the lexer and matches them against the rules of \
the grammar. What follows is the grammar in a simplified variation of BNF, so the \
actual bison source file may look a little different. Legend:</P>
-
-<BLOCKQUOTE><TABLE BORDER=1 SUMMARY="">
-<TR><TD>[ a ]</TD><TD>match a 0 or 1 times</TD></TR>
-<TR><TD>{ b }</TD><TD>match b 0 or more times</TD></TR>
-<TR><TD>c | d</TD><TD>match either c or d</TD></TR>
-<TR><TD>( e f )</TD><TD>group e and f together</TD></TR>
-<TR><TD>lowercase</TD><TD>nonterminal</TD></TR>
-<TR><TD>UPPER</TD><TD>token from the lexer</TD></TR>
-<TR><TD>'c'</TD><TD>token from the lexer</TD></TR>
-</TABLE></BLOCKQUOTE>
-
-<P>The rdef grammar consists of the following rules:</P>
-
-<BLOCKQUOTE><TABLE BORDER=1 SUMMARY="">
-
-<TR><TD>script</TD><TD>{enum | typedef | resource}</TD></TR>
-
-<TR><TD>enum</TD><TD> ENUM '{' [symboldef {',' symboldef} [',']] '}' ';'</TD></TR>
-
-<TR><TD>symboldef</TD><TD>IDENT ['=' integer]</TD></TR>
-
-<TR><TD>typedef</TD><TD>TYPE [id] [TYPECODE] IDENT '{' fielddef {',' fielddef} '}' \
';'</TD></TR>
-
-<TR><TD>fielddef</TD><TD>datatype IDENT ['[' INTEGER ']'] ['=' expr]</TD></TR>
-
-<TR><TD>resource</TD><TD>RESOURCE [id] [typecode] expr ';'</TD></TR>
-
-<TR><TD>id</TD><TD>'(' [(integer | IDENT) [',' STRING] | STRING] ')'</TD></TR>
-
-<TR><TD>typecode</TD><TD>['('] TYPECODE [')']</TD></TR>
-
-<TR><TD>expr</TD><TD>expr BINARY_OPER expr | UNARY_OPER expr | data</TD></TR>
-
-<TR><TD>data</TD><TD>[typecast] (BOOL | integer | float | STRING | RAW | array | \
message | archive | type | define | '(' expr ')' )</TD></TR>
-
-<TR><TD>typecast</TD><TD>['(' datatype ')']</TD></TR>
-
-<TR><TD>datatype</TD><TD>ARRAY | MESSAGE | ARCHIVE IDENT | IDENT</TD></TR>
-
-<TR><TD>integer</TD><TD>['-'] INTEGER</TD></TR>
-
-<TR><TD>float</TD><TD>['-'] FLOAT</TD></TR>
-
-<TR><TD>array</TD><TD>ARRAY ['{' [expr {',' expr}] '}'] | [ARRAY] IMPORT \
STRING</TD></TR>
-
-<TR><TD>message</TD><TD>MESSAGE ['(' integer ')'] ['{' [msgfield {',' msgfield}] \
'}']</TD></TR>
-
-<TR><TD>msgfield</TD><TD>[TYPECODE] [datatype] STRING '=' expr</TD></TR>
-
-<TR><TD>archive</TD><TD>ARCHIVE [archiveid] IDENT '{' msgfield {',' msgfield} \
'}'</TD></TR>
-
-<TR><TD>archiveid</TD><TD>'(' [STRING] [',' integer] ')'</TD></TR>
-
-<TR><TD>type</TD><TD>IDENT [data | '{' [typefield {',' typefield}] '}']</TD></TR>
-
-<TR><TD>typefield</TD><TD>[IDENT '='] expr</TD></TR>
-
-<TR><TD>define</TD><TD>IDENT</TD></TR>
-
-</TABLE></BLOCKQUOTE>
-
-<H2>Semantics</H2>
-
-<H3>Resource names</H3>
-
-<P>There are several different ways to specify the ID and name of a new \
resource:</P>
-
-<BLOCKQUOTE><TABLE BORDER=1 SUMMARY="">
-
-<TR><TD WIDTH="25%">resource</TD><TD>The resource is assigned the default name and \
ID of its data type.</TD></TR>
-
-<TR><TD>resource()</TD><TD>The resource is assigned the default name and ID of its \
data type.</TD></TR>
-
-<TR><TD>resource(1)</TD><TD>The resource is assigned the numeric ID 1, and the \
default name of its data type.</TD></TR>
-
-<TR><TD>resource("xxx")</TD><TD>The resource is assigned the name "xxx" and the \
default ID of its data type.</TD></TR>
-
-<TR><TD>resource(1, "xxx")</TD><TD>The resource is assigned the numeric ID 1, and \
the name "xxx".</TD></TR>
-
-<TR><TD>resource(sss)</TD><TD>The resource is assigned the numeric ID that \
corresponds with the symbol sss, which should have been defined in an enum earlier. \
If the "auto names" option is passed to the compiler, the resource is also given the \
name "sss", otherwise the default name from its data type is \
used.</TD></TR>
-
-<TR><TD>resource(sss, "xxx")</TD><TD>The resource is assigned the numeric ID that \
corresponds with the symbol sss, and the name "xxx".</TD></TR>
-
-</TABLE></BLOCKQUOTE>
-
-<H3>Data types and type casts</H3>
-
-<P>Resources (and message fields) have a type code and a data type. The data type \
determines the format the data is stored in, while the type code tells the user how \
to interpret the data. Typically, there is some kind of relation between the two, \
otherwise the resource will be a little hard to read.</P>
-
-<P>The following table lists the compiler's built-in data types. (Users can also \
define their own types; this is described in a later section.)</P>
-
-<BLOCKQUOTE><TABLE BORDER=1 SUMMARY=""><TR><TD VALIGN="top">
-
-<TABLE BORDER=1 SUMMARY="">
-<TR><TD>bool</TD><TD>B_BOOL_TYPE</TD></TR>
-<TR><TD>int8</TD><TD>B_INT8_TYPE</TD></TR>
-<TR><TD>uint8</TD><TD>B_UINT8_TYPE</TD></TR>
-<TR><TD>int16</TD><TD>B_INT16_TYPE</TD></TR>
-<TR><TD>uint16</TD><TD>B_UINT16_TYPE</TD></TR>
-<TR><TD>int32</TD><TD>B_INT32_TYPE</TD></TR>
-<TR><TD>uint32</TD><TD>B_UINT32_TYPE</TD></TR>
-<TR><TD>int64</TD><TD>B_INT64_TYPE</TD></TR>
-<TR><TD>uint64</TD><TD>B_UINT64_TYPE</TD></TR>
-<TR><TD>size_t</TD><TD>B_SIZE_T_TYPE</TD></TR>
-<TR><TD>ssize_t</TD><TD>B_SSIZE_T_TYPE</TD></TR>
-</TABLE>
-
-</TD><TD VALIGN="top">
-
-<TABLE BORDER=1 SUMMARY="">
-<TR><TD>off_t</TD><TD>B_OFF_T_TYPE</TD></TR>
-<TR><TD>time_t</TD><TD>B_TIME_TYPE</TD></TR>
-<TR><TD>float</TD><TD>B_FLOAT_TYPE</TD></TR>
-<TR><TD>double</TD><TD>B_DOUBLE_TYPE</TD></TR>
-<TR><TD>string</TD><TD>B_STRING_TYPE</TD></TR>
-<TR><TD>raw</TD><TD>B_RAW_TYPE</TD></TR>
-<TR><TD>array</TD><TD>B_RAW_TYPE</TD></TR>
-<TR><TD>buffer</TD><TD>B_RAW_TYPE</TD></TR>
-<TR><TD>message</TD><TD>B_MESSAGE_TYPE</TD></TR>
-<TR><TD>archive</TD><TD>B_MESSAGE_TYPE</TD></TR>
-</TABLE>
-
-</TD></TR></TABLE></BLOCKQUOTE>
-
-<P>The type code has no effect on how the data is stored. For example, if you do \
this: "resource(x) #'LONG' true", then the data will not automatically be stored as a \
32-bit number! If you don't specify an explicit type code, the compiler uses the type \
of the data for that.</P>
-
-<P>You can change the data type with a type cast. The following casts are \
allowed:</P>
-
-<BLOCKQUOTE><TABLE BORDER=1 SUMMARY="">
-
-<TR><TD WIDTH="20%">bool</TD><TD>You cannot cast bool data.</TD></TR>
-
-<TR><TD>integer</TD><TD>You can cast to all numeric data types. Casts to smaller \
datatypes will truncate the number. Casting negative numbers to unsigned datatypes \
(and vice versa) will wrap them, i.e. (uint8) -1 becomes \
255.</TD></TR>
-
-<TR><TD>floating point</TD><TD>You can only cast to float or double.</TD></TR>
-
-<TR><TD>string</TD><TD>You cannot cast string data.</TD></TR>
-
-<TR><TD>raw, buffer, array</TD><TD>You can cast anything to raw, but not the other \
way around.</TD></TR>
-
-<TR><TD>message, archive</TD><TD>You cannot cast message data.</TD></TR>
-
-<TR><TD>type</TD><TD>You cannot cast user-defined types.</TD></TR>
-
-</TABLE></BLOCKQUOTE>
-
-<P>In addition to the "simple" built-in data types, the compiler also natively \
supports several data structures from the BeOS API (point, rect, rgb_color) and a few \
convenience types (app_signature, app_flags, etc). These types all follow the same \
rules as user-defined types.</P>
-
-<H3>Arrays</H3>
-
-<P>The following definitions are semantically equivalent:</P>
-
-<BLOCKQUOTE><PRE>resource(x) $"AABB";
-resource(x) array { $"AA" $"BB" };
-resource(x) array { $"AA", $"BB" };</PRE></BLOCKQUOTE>
-
-<P>The comma is optional and simply concatenates the two literals. When you \
decompile this code, it always looks like:</P>
-
-<BLOCKQUOTE><PRE>resource(x) $"AABB";</PRE></BLOCKQUOTE>
-
-<P>Strings behave differently. The following two definitions are equivalent, and \
concatenate the two literals into one string:</P>
-
-<BLOCKQUOTE><PRE>resource(x) "AA" "BB";
-resource(x) #'CSTR' array { "AA" "BB" };</PRE></BLOCKQUOTE>
-
-<P>However, if you put a comma between the the strings, the compiler will still glue \
them together but with a '\0' character in the middle. Now the resource contains \
<I>two</I> strings: "AA" and "BB". You can also specify the '\0' character \
yourself:</P>
-
-<BLOCKQUOTE><PRE>resource(x) "AA\0BB";
-resource(x) #'CSTR' array { "AA", "BB" };</PRE></BLOCKQUOTE>
-
-<P>The following is not proper grammar; use an array instead:</P>
-
-<BLOCKQUOTE><PRE>resource(x) "AA", "BB";
-resource(x) $"AA", $"BB";</PRE></BLOCKQUOTE>
-
-<P>Note that the data type of an array is always raw data, no matter how you specify \
its contents. Because raw literals may be empty ($""), so may \
arrays.</P>
-
-<H3>Messages and archives</H3>
-
-<P>A message resource is a flattened BMessage. By default it has the data type \
B_MESSAGE_TYPE and corresponding type code #'MSGG'. If you don't specify a "what" \
code for the message, it defaults to 0.</P>
-
-<P>Message fields assume the type of their data, unless you specify a different type \
in front of the field name. (Normal casting rules apply here.) You can also give the \
field a different type code, which tells the BMessage how to interpret the data, but \
not how it is stored in the message. This type code also goes in front of the field \
name. You can give the same name to multiple fields, provided that they all have the \
same type. (The data of these fields does not have to be the same size.) A message \
may be empty; it is still a valid BMessage, but it contains no \
fields.</P>
-
-<P>An archive is also a flattened BMessage, but one that was made by Archive()'ing a \
BArchivable class, such as BBitmap. The name of the archive, in this case BBitmap, is \
automatically added to the message in a field called "class". The "archive" keyword \
is optionally followed by a set of parentheses that enclose a string and/or an \
integer. The int is the "what" code, the string is stored in a field called "add_on" \
(used for dynamic loading of BArchivables). Other than that, archives and messages \
are identical. The compiler does not check whether the contents of the archive \
actually make sense, so if you don't structure the data properly you may be unable to \
unarchive the object later. Unlike a message, an archive may not be empty, because \
that is pointless.</P>
-
-<H3>User-defined types</H3>
-
-<P>We allow users to define their own types. A "type" is just a fancy array, because \
the data from the various fields is simply concatenated into one big block of bytes. \
The difference is that user-defined types are much easier to fill \
in.</P>
-
-<P>A user-defined type has a symbolic name, a type code, and a number of data \
fields. After all the fields have been concatenated, the type code is applied to the \
whole block. So, the data type of this resource is always the same as its type code \
(unlike arrays, which are always raw data). If no type code is specified, it defaults \
to B_RAW_TYPE.</P>
-
-<P>The data fields always have a default value. For simple fields this is typically \
0 (numeric types) or empty (string, raw, message). The default value of a \
user-defined type as a whole is the combination of the default values of its fields. \
Of course, the user can specify other defaults. (When a user creates a new resource \
that uses such a type, he is basically overriding the default values with his \
own.)</P>
-
-<P>The user may fill in the data fields by name, by order, or using a combination of \
both. Every time the compiler sees an unnamed data item, it stuffs it into the next \
available field. Named data items are simply assigned to the field with the same \
name, and may overwrite a value that was previously put there "by order". Any fields \
that are not filled in keep their default value. For example:</P>
-
-<BLOCKQUOTE><PRE>type vector { int32 x, int32 y, int32 z, int32 w = 4 };
-resource(1) vector { 1, 3, x = 2 };</PRE></BLOCKQUOTE>
-
-<P>Here, x is first set to 1, y is set to 3, x is now overwritten by the value 2, z \
is given the default value 0, and w defaults to 4.</P>
-
-<P>Note: if a user-defined type contains string, raw, or message fields, the size of \
the type depends on the data that the user puts into it, because these fields have a \
variable size. However, the user may specify a fixed size for a field (number of \
bytes, enclosed in square brackets following the field name). In this case, data that \
is too long will be truncated and data that is too short will be padded with zeroes. \
You can do this for all types, but it really only makes sense for strings and raw \
data. More about this in the manual.</P>
-
-<P>A type definition may also contain a default resource ID and name. The default ID \
of built-in types is usually 1 and the name is empty (NULL). For \
example:</P>
-
-<BLOCKQUOTE><PRE>type(10, "MyName") mytype { int32 a };
-resource mytype 123;</PRE></BLOCKQUOTE>
-
-<P>The resource is now called "MyName" and has ID 10. Obviously you can only do this \
once or you will receive a duplicate resource error. If this type is used inside an \
array or other compound type, the default ID and resource name are ignored. Note: \
this feature introduces a shift/reduce conflict in the compiler:</P>
-
-<BLOCKQUOTE><PRE>resource (int8) 123;</PRE></BLOCKQUOTE>
-
-<P>This probably doesn't do what you expect. The compiler now considers the "(int8)" \
to be the resource ID, not a typecast. If you did not declare "int8" in an enum \
(probably not), this gives a compiler error. Not a big problem, because it is \
unlikely that you will ever do this. Here is a workaround:</P>
-
-<BLOCKQUOTE><PRE>resource() (int8) 123;</PRE></BLOCKQUOTE>
-
-<H3>The grammar and Bison</H3>
-
-<P>Above I mentioned one of the shift/reduce conflicts from the grammar. There are \
several others. These are mostly the result of keeping the original grammar intact as \
much as possible, without having to introduce weird syntax rules for the new \
features. These issues aren't fatal but if you try to do something funky in your \
script, you may get an error message.</P>
-
-<P>The main culprit here is the "( expr )" rule from "data", which allows you to \
nest expressions with parens, e.g. "<CODE>(10 + 5) * 3</CODE>". This causes problems \
for Bison, because we already use parens all over the place. Specifically, this rule \
conflicts with the empty "MESSAGE" from the "message" rule, "ARRAY" from "array", and \
"IDENT" from "type". These rules have no other symbols following them, which makes \
them ambiguous with respect to the "datatype" rules. Still with me? The parser will \
typically pick the right one, though.</P>
-
-<P>The nested expressions rule also caused a reduce/reduce conflict. To get rid of \
that, I had to explicitly mention the names of the various types in the "typecast" \
rule, which introduces a little code duplication but it's not too bad. Just so you \
know, the original rule was simply:</P>
-
-<BLOCKQUOTE><PRE>typecast
- : '(' datatype ')' { $$ = $2; }
- ;</PRE></BLOCKQUOTE>
-
-<P>The new rule is a little more bulky:</P>
-
-<BLOCKQUOTE><PRE>typecast
- : '(' ARRAY ')' { ... }
- | '(' MESSAGE ')' { ... }
- ...<I>and so on for all the datatypes</I>...
- ;</PRE></BLOCKQUOTE>
-
-<P>The unary minus operator is not part of the "expr" (or "data") rules, but of \
"integer" and "float". This also causes a shift/reduce warning.</P>
-
-<P>And finally, "type" is a member of "data" which is called by "expr". One of the \
rules of "type" refers back to "expr". This introduces a recursive dependency and a \
whole bunch of shift/reduce conflicts. Fortunately, it seems to have no bad side \
effects. Yay!</P>
-
-<H3>Symbol table</H3>
-
-<P>The compiler uses two symbol tables: one for the enum symbols, and one with the \
data type definitions. We need those tables to find the numeric ID/type definition \
that corresponds with an identifier, and to make sure that there are no duplicate or \
missing identifiers. These two symbol tables are independent, so you may use the same \
identifier both as an enum symbol and a type name.</P>
-
-<P>The compiler does not need to keep a symbol table for the resources. Although the \
combination of a resource's ID and its type code must be unique, we can use the \
BResources class to check for this when we add a resource. There is no point in \
duplicating this functionality in the compiler. (However, if we are merging the new \
resources into an existing resource file, we will simply overwrite \
duplicates.)</P>
-
-<H3>Misc remarks</H3>
-
-<UL>
-
-<LI>As the grammar shows, the last field in an enum statement may be followed by a \
comma. This is valid C/C++ syntax, and since the enum will typically end up in a \
header file, we support that feature as well. For anything else between braces, the \
last item may not be followed by a comma.<BR> </LI>
-
-<LI>The type code that follows the "resource" keyword may be enclosed by parens for \
historical reasons. The preferred notation is without, just like in front of field \
names (where no parens are allowed).<BR> </LI>
-
-<LI>Even though "ARCHIVE IDENT" is a valid data type, we simply ignore the \
identifier for now. Maybe later we will support casting between different archives or \
whatever. For now, casting to an archive is the same as casting to a message, since \
an archive is really a message.<BR> </LI>
-
-<LI>User-defined types and defines have their own symbol tables. Due to the way the \
parser is structured, we can only distinguish between types and defines by matching \
the identifier against both symbol tables. Here types have priority, so you could \
'shadow' a define with a type name if you were really evil. Maybe it makes sense for \
rc to use one symbol table for all things in the future, especially since we're using \
yet another table for enums. We'll see.</LI>
-
-</UL>
-
-</BODY>
-</HTML>
diff --git a/src/bin/rc/docs/history.html b/src/bin/rc/docs/history.html
deleted file mode 100644
index 257a22b9e6..0000000000
--- a/src/bin/rc/docs/history.html
+++ /dev/null
@@ -1,36 +0,0 @@
-<HTML>
-<HEAD>
-<TITLE>History</TITLE>
-</HEAD>
-<BODY BGCOLOR="#FFFFFF">
-
-<H1>History</H1>
-
-<P>This is the change history of the rc resource compiler and librdef.</P>
-
-<P><I>Version 1.1 (December 22, 2003):</I></P>
-
-<UL>
-
-<LI>You can now import the contents of external files (such as pictures) into array \
resources or fields. This does away with the need to convert (large) binary files \
into text form.</LI>
-
-<LI>You can now give type fields a fixed size, which can be handy for certain kinds \
of string or raw data resources (for example, app_version).</LI>
-
-<LI>You can now use built-in symbolic constants such as B_SINGLE_LAUNCH for setting \
the app_flags and app_version resources. There is no facility for defining your own \
symbols yet. (In case you were wondering, no, you cannot use the enum statement for \
that.)</LI>
-
-<LI>Added limited support for numerical expressions. You can now do simple math like \
<CODE>(1 + 2) * 3</CODE>. Only a few operators are supported, you can only use \
integer operands, and the results are always cast to 32-bit integer as well. This \
should be more than enough for now; expressions can be made more powerful in the \
future should the need arise. You'll use this feature mostly for OR'ing and AND'ing \
symbolic constants (see above) together to make your scripts more \
readable.</LI>
-
-<LI>Line number counter was not reset properly when compiling multiple rdef files in \
one go.</LI>
-
-<LI>Bumped the API version number of librdef.so to 2.</LI>
-
-</UL>
-
-<P><I>Version 1.0 (February 16, 2003):</I></P>
-
-<UL>
-<LI>Initial release</LI>
-</UL>
-
-</BODY>
-</HTML>
diff --git a/src/bin/rc/docs/librdef.html b/src/bin/rc/docs/librdef.html
deleted file mode 100644
index bb54d3831f..0000000000
--- a/src/bin/rc/docs/librdef.html
+++ /dev/null
@@ -1,64 +0,0 @@
-<HTML>
-<HEAD>
-<TITLE>The librdef library</TITLE>
-</HEAD>
-<BODY BGCOLOR="#FFFFFF">
-
-<H1>The librdef library</H1>
-
-<P>Of course, it would be cool if other applications (such as GUI resource editors) \
could also import and export rdef files. That is why the bulk of rc's functionality \
is implemented in a separate shared library, librdef.so.</P>
-
-<P>Using the library in your own applications is very simple. Here are some quick \
instructions to get you started:</P>
-
-<OL>
-<LI><CODE>#include "rdef.h"</CODE> in your sources</LI>
-<LI>link your app to librdef.so</LI>
-</OL>
-
-<P>The API is rather bare-bones, but it gets the job done. The library uses files to \
transfer data to and from your application. This may seem odd, but it is actually a \
big advantage. After calling the API functions to compile an rdef file, you can use \
the standard BResources class to read the resources from the output file. Chances are \
high that your application already knows how to do this.</P>
-
-<P>To compile a resource file, the steps are typically this:</P>
-
-<OL>
-
-<LI>Call <CODE>rdef_add_include_dir()</CODE> one or more times to add include file \
search paths.</LI>
-
-<LI>Call <CODE>rdef_add_input_file()</CODE> one or more times to add the rdef files \
that you want to compile.</LI>
-
-<LI>Call <CODE>rdef_set_flags()</CODE> to toggle compiler options.</LI>
-
-<LI>Call <CODE>rdef_compile()</CODE> with the name of the output file. This performs \
the actual compilation.</LI>
-
-<LI>Call <CODE>rdef_free_input_files()</CODE> to clear the list of input files that \
you added earlier.</LI>
-
-<LI>Call <CODE>rdef_free_include_dirs()</CODE> to clear the list of include \
directories that you added earlier.</LI>
-
-</OL>
-
-<P>Decompiling is very similar, although include directories are not used here:</P>
-
-<OL>
-
-<LI>Call <CODE>rdef_add_input_file()</CODE> one or more times to add the resource \
files that you want to decompile.</LI>
-
-<LI>Call <CODE>rdef_set_flags()</CODE> to toggle compiler options.</LI>
-
-<LI>Call <CODE>rdef_decompile()</CODE> with the name of the output file. The name of \
the header file (if any) will be automatically constructed by appending ".h" to the \
output file name.</LI>
-
-<LI>Call <CODE>rdef_free_input_files()</CODE> to clear the list of input files that \
you added earlier.</LI>
-
-</OL>
-
-<P>If one of these functions returns something other than B_OK, an error occurred. \
You can look at the following variables to find out more about the error, and \
construct meaningul error messages:</P>
-
-<UL>
-<LI><CODE>rdef_err</CODE> The error code that was returned.</LI>
-<LI><CODE>rdef_err_line</CODE> The line number where compilation failed.</LI>
-<LI><CODE>rdef_err_file</CODE> The file where the error occurred.</LI>
-<LI><CODE>rdef_err_msg</CODE> The error message from the compiler.</LI>
-</UL>
-
-<P>For more information about using librdef, see "rdef.h", which explains the \
available functions and data structures in more depth. For a real-world example, take \
a look at "rc.cpp", which contains the complete implementation of the rc compiler. As \
you'll see, there really isn't much to it, because librdef already does all the \
work.</P>
-
-</BODY>
-</HTML>
diff --git a/src/bin/rc/docs/notes.html b/src/bin/rc/docs/notes.html
deleted file mode 100644
index a6fa19c23a..0000000000
--- a/src/bin/rc/docs/notes.html
+++ /dev/null
@@ -1,43 +0,0 @@
-<HTML>
-<HEAD>
-<TITLE>Work notes</TITLE>
-</HEAD>
-<BODY BGCOLOR="#FFFFFF">
-
-<H1>Work notes</H1>
-
-<P>These are my notes on the evolution of rc. I used to keep these in separate files \
on my development machine, but it makes more sense to include them here. Warning: \
geeky stuff ahead.</P>
-
-<UL>
-
-<LI>Unlike in most parsers, the unary minus operator is currently not part of the \
'data' rules, but of 'integer' and 'float'. When expression support is more complete, \
it may make more sense to put this in 'data'. However, 'integer' is used in other \
places as well and these places allow negative numbers too. Maybe we can replace the \
calls to 'integer' with 'data' and allow the data to the integer only (by always \
trying to cast it, perhaps). Then you can do stuff like 'resource(10 + 1) 123;' But \
maybe that goes too far.<BR> </LI>
-
-<LI>When filling in boolean fields of user-defined types or messages, you can do \
either "field = true" or "field = false". I thought it would be nice if you could \
also do just "field" and "!field". However, that introduced a reduce/reduce conflict \
in the parser. You see, the name of the field is an IDENT token, but we already have \
something like that in the 'type' rule of 'data'. The parser doesn't know what the \
IDENT is supposed to be: the name of the boolean field or the name of the type. Maybe \
there is a solution for this by shuffling around the parser rules a \
bit.<BR> </LI>
-
-<LI>Support for the built-in types point, rect, and rgb_color is currently hardcoded \
into the decompiler. The other built-in types -- app_flags, mini_icon, etc -- are not \
supported at all. It would be better to use the type symbol table for this as well. \
Then the decompiler can also support user-defined types (although these type \
definitions must be provided to the decompiler somehow). This is advanced stuff that \
probably no one will ever use.<BR> </LI>
-
-<LI>The builtin types are added to the symbol table "by hand". You can see this near \
the bottom of 'parser.y'. This is a bit cumbersome, so I have devised an alternative. \
We put the builtin type definitions in an rdef script and install this in a "standard \
include dir", for example: ~/config/include/rc. Before it compiles the user's rdef \
files, the compiler first loads all scripts from that standard folder. (This also \
allows us to use these rdef files for decompiling, and users can simply install their \
own. See above.)<BR> </LI>
-
-<LI>In "auto names" mode, the decompiler currently does not use the enum symbol \
table. So if two resources have the same name and that name is a valid C/C++ \
identifier, the decompiler will add two conflicting symbols to the enum statement. \
This can also happen when multiple input files have conflicting resource \
IDs.<BR> </LI>
-
-<LI>When you decompile certain apps (BeMail, Slayer) and then compile these rdef \
files again, the archive and message fields in the new .rsrc file are larger than the \
original's. I think this is because rc doesn't add the message fields as "fixedSize" \
(see the BMessage docs from the BeBook). This doesn't really hurt, though, since the \
BMessage will be properly unflattened regardless.<BR> </LI>
-
-<LI>Right now, archives are treated as messages. Maybe we should give them their own \
type, B_ARCHIVED_OBJECT (type code 'ARCV').<BR> </LI>
-
-<LI>New options, stolen from other resource compilers (rez and beres):
-
-<UL>
-<LI><B>-D --define symbol[=value]</B> set the value of symbol to value (or 1 if no \
value supplied)</LI>
-<LI><B>--no-names</B> do not write any names in resource file</LI>
-<LI><B>-h</B> write resource as C struct in a header file</LI>
-<LI><B>-d</B> dump resource to stdout</LI>
-</UL><BR></LI>
-
-<LI>Attributes. I would be nice to have a tool that can take text-based descriptions \
of attributes and write out an attribute file. Of course, rc is the ideal candidate \
for this, since it already does the same for resources. However, resources and \
attributes are not the same. Attributes are name/data pairs. The name should be \
unique. They don't have IDs. They do have a type code, but it isn't used to identify \
the attribute. It is probably best to add a new kind of definition: attribute(). \
Should this statement allow only simple data, or must attributes be able to handle \
flattened messages, arrays, etc too? A source file should either contain resource() \
statements or attribute() statements, not both.<BR> </LI>
-
-<LI>User-defined symbolic constants. To keep things simple, adding a #define keyword \
would suffice, although this always creates global symbols so there is a chance of \
name collisions. In addition (or instead) we can extend user-defined types to have \
their own (local) defines too. If we use the #define keyword, we should infer the \
type of the constant from the data (100 is integer, 10.5 is a float, etc). This is \
necessary because we don't have a separate preprocessor step like C/C++ does -- that \
is why our symbolic constants are typed.</LI>
-
-</UL>
-
-</BODY>
-</HTML>
diff --git a/src/bin/rc/docs/rc.html b/src/bin/rc/docs/rc.html
deleted file mode 100644
index 7add64c9dd..0000000000
--- a/src/bin/rc/docs/rc.html
+++ /dev/null
@@ -1,412 +0,0 @@
-<HTML>
-<HEAD>
-<TITLE>Resource Compiler</TITLE>
-</HEAD>
-<BODY BGCOLOR="#FFFFFF">
-
-<H1>The rc resource compiler</H1>
-
-<P>Version 1.1</P>
-
-<H2>Table of contents</H2>
-
-<UL>
-<LI><A HREF="#intro">Introduction</A></LI>
-<LI><A HREF="#install">How to install</A></LI>
-<LI><A HREF="#scripts">Writing resource scripts</A></LI>
-<LI><A HREF="#advanced">Big fat resources</A></LI>
-<LI><A HREF="#app">Application resources</A></LI>
-<LI><A HREF="#compile">Compiling</A></LI>
-<LI><A HREF="#decompile">Decompiling</A></LI>
-<LI><A HREF="#authors">Authors</A></LI>
-<LI><A HREF="#license">License</A></LI>
-</UL>
-
-<!-- *********************************************************************** -->
-
-<A NAME="intro"></A>
-
-<H2>Introduction</H2>
-
-<P>In the world of BeOS programming, a "resource" is data that is bundled with your \
application. Typical examples are the application's icons and its signature, but you \
can attach any data you want (bitmaps, text, cursors, etc). You stuff this data into \
a .rsrc file that will be linked to your application when it is \
compiled.</P>
-
-<P>Because .rsrc files have a binary file format, you need to use special tools to \
edit them, such as FileTypes, QuickRes, or Resourcer. Alternatively, you can use a \
"resource compiler". This is a command line tool that takes a text-based resource \
script and turns it into a .rsrc file.</P>
-
-<P>With a resource compiler, you express your resources as ASCII text using a \
special definition language, which makes the resource files much easier to edit and \
maintain. You no longer need separate GUI tools to build your .rsrc files, and you \
can even automate the whole process by calling the compiler from your Makefile or \
Jamfile. Resource scripts will also make your life easier if you use version control, \
because version control doesn't handle .rsrc files very well.</P>
-
-<P>BeOS R5 comes with an (experimental) resource compiler called "beres", and a \
corresponding decompiler called "deres". rc is an open source replacement (and \
enhancement) of these tools. It is (mostly) backwards compatible, so you should be \
able to compile your old .rdef files without any problems.</P>
-
-<!-- *********************************************************************** -->
-
-<A NAME="install"></A>
-
-<H2>How to install</H2>
-
-<OL>
-<LI>Copy <CODE>rc</CODE> into <CODE>/boot/home/config/bin</CODE></LI>
-<LI>Copy <CODE>librdef.so</CODE> into <CODE>/boot/home/config/lib</CODE></LI>
-<LI>Let's party!</LI>
-</OL>
-
-<!-- *********************************************************************** -->
-
-<A NAME="scripts"></A>
-
-<H2>Writing resource scripts</H2>
-
-<P>Writing resource scripts is not difficult, although the syntax may take some \
getting used to. A resource script is a plain text file with one or more resource \
definition statements. In addition, it may contain C or C++ style comments. By \
convention, resource script files have the extension ".rdef".</P>
-
-<P>Here is an example of a simple resource script:</P>
-
-<BLOCKQUOTE><PRE>resource(1) true; /* this is a comment */
-resource(2) 123; // and so is this
-resource(3) 3.14;
-resource(4) "hello world";
-resource(5) $"0123456789ABCDEF";</PRE></BLOCKQUOTE>
-
-<P>When compiled, this script produces a resource file with five resources. The \
above example also illustrates the types of data that resources are allowed to have: \
boolean, integer, floating point, character string (UTF-8), and raw data buffer \
(hexadecimal).</P>
-
-<P>By default, integer data is stored as a 32-bit int, and floating point data is \
stored as a 4-byte float. If you want to change the way the data is stored, you have \
to cast it:</P>
-
-<BLOCKQUOTE><PRE>resource(6) (int8) 123;
-resource(7) (double) 3.14;</PRE></BLOCKQUOTE>
-
-<P>You can cast integer data to the following types: int8, uint8, int16, uint16, \
int32, uint32, int64, uint64, ssize_t, size_t, off_t, time_t, float, double, raw. You \
can cast floating point data to: float, double, raw. You are not allowed to cast \
boolean, string, or raw data to other types.</P>
-
-<P>In addition to casting, you can also change the resource's type code. This does \
not change the way the data is stored, only what it is called. To change the type \
code of a resource:</P>
-
-<BLOCKQUOTE><PRE>resource(8) #'dude' 123;</PRE></BLOCKQUOTE>
-
-<P>This changes the type of resource 8 to the four-character-code 'dude'. If you did \
not change it, it would be 'LONG', which stands for 32-bit integer. By changing the \
type code, you assign a new meaning to the resource. You can also specify type codes \
as decimal or hexadecimal numbers:</P>
-
-<BLOCKQUOTE><PRE>resource(9) #200 123;
-resource(10) #0xC8 123;</PRE></BLOCKQUOTE>
-
-<P>For historical reasons, you may also enclose the type code in parens, but that is \
not the preferred notation. Type casts and type codes can be \
combined:</P>
-
-<BLOCKQUOTE><PRE>resource(11) #'dude' (int8) 123;
-resource(11) (#'dude') (int8) 123;</PRE></BLOCKQUOTE>
-
-<P>In the above examples, we have given the resources numeric IDs. The combination \
of ID and type code must be unique in the resource file; you cannot have two int32 \
resources with ID 1, for example. However, it is perfectly fine (but not necessarily \
a good idea) to do the following, because the data types are \
different:</P>
-
-<BLOCKQUOTE><PRE>resource(12) 123;
-resource(12) "w00t!";</PRE></BLOCKQUOTE>
-
-<P>For your own convenience, you can also name resources. Unlike the ID/type code \
combination, names do not have to be unique. </P>
-
-<BLOCKQUOTE><PRE>resource(13, "Friday") "Bad Luck";</PRE></BLOCKQUOTE>
-
-<P>You can also do simple maths. The emphasis here is on simple because the number \
of operators is limited, they only work on integer data (or anything that can be cast \
to integer), and the result is always 32-bit integer as well. Still, the lazy amongst \
you may find it handy:</P>
-
-<BLOCKQUOTE><PRE>resource(14) 2 * (4 + 3);</PRE></BLOCKQUOTE>
-
-<P>Since it is likely that you will be using these resources from a C/C++ program, \
it may be convenient to refer to them by symbolic names instead of hardcoded numeric \
ID's. The rdef format allows you to do this:</P>
-
-<BLOCKQUOTE><PRE>enum
-{
- R_AppName = 1,
- R_SomeOtherThing = 2
-};
-
-resource(R_AppName) "MyKillerApp";</PRE></BLOCKQUOTE>
-
-<P>The compiler will automatically substitute the symbol R_AppName with the number \
1. (You don't have to start these symbol names with the prefix R_, but it is somewhat \
of a convention.)</P>
-
-<P>Now how do you tell your C/C++ app about these symbolic names? You simply put the \
enum into a header file that you include both from your application's source code and \
your rdef file. The header file, which we'll call "myresources.h", now looks like \
this:</P>
-
-<BLOCKQUOTE><PRE>enum
-{
- R_AppName = 1,
- R_SomeOtherThing = 2
-};</PRE></BLOCKQUOTE>
-
-<P>And the rdef file becomes this:</P>
-
-<BLOCKQUOTE><PRE>#include "myresources.h"
-
-resource(R_AppName) "MyKillerApp";</PRE></BLOCKQUOTE>
-
-<P>Don't let the .h suffix fool you: the header file is still considered to be an \
rdef file, and must contain valid rdef syntax. If you add any other C/C++ code, your \
resource script will fail to compile. Of course, you shouldn't add any other rdef \
syntax to the header either (unless you want your C++ compiler to start complaining). \
Besides comments, the only safe thing to put in that header file is the enum \
statement, because both rdef and C/C++ understand it.</P>
-
-<P>Just like IDs, symbolic identifiers can be combined with a name:</P>
-
-<BLOCKQUOTE><PRE>resource(R_AppName, "AppName") "MyKillerApp";</PRE></BLOCKQUOTE>
-
-<P>If you don't specify a name, and invoke the compiler with the \
<CODE>--auto-names</CODE> option, it automatically uses the symbolic ID for the name \
as well. So the ID of the following resource is 1 (because that is what R_AppName \
corresponds to) and its name becomes "R_AppName":</P>
-
-<BLOCKQUOTE><PRE>resource(R_AppName) "MyKillerApp";</PRE></BLOCKQUOTE>
-
-<!-- *********************************************************************** -->
-
-<A NAME="advanced"></A>
-
-<H2>Big fat resources</H2>
-
-<P>The resources we have made so far consisted of a single data item, but you can \
also supply a collection of data values. The simplest of these compound data \
structures is the array:</P>
-
-<BLOCKQUOTE><PRE>resource(20) array { 1234, 5678 };</PRE></BLOCKQUOTE>
-
-<P>An array is nothing more than a raw buffer. The above statement takes the two \
32-bit integers 1234 and 5678 and stuffs them into a new 64-bit buffer. You can put \
any kind of data into an array, even other arrays:</P>
-
-<BLOCKQUOTE><PRE>resource(21) array
-{
- "hello",
- 3.14,
- true,
- array { "a", "nested", "array" },
- $"AABB"
-};</PRE></BLOCKQUOTE>
-
-<P>It is up to you to remember the structure of this array, because array resources \
don't keep track of what kind of values you put into them and where you put these \
values. For that, we have messages. A message resource is a flattened \
BMessage:</P>
-
-<BLOCKQUOTE><PRE>resource(22) message('blah')
-{
- "Name" = "Santa Claus",
- "Number" = 3.14,
- "Array" = array { "a", "nested", "array" },
- "Other Msg" = message { "field" = "value" }
-};</PRE></BLOCKQUOTE>
-
-<P>A message has an optional "what" code, in this case 'blah', and one or more \
fields. A field has a name (between double quotes), a value, and a data type. By \
default, the field assumes the type of its data, but you can also specify an explicit \
data type and type code in front of the field name:</P>
-
-<BLOCKQUOTE><PRE>resource(23) message('bla2')
-{
- "integer1" = (int8) 123, // use cast to change data type
- int16 "integer2" = 12345, // specify data type
- #'dude' "buffer1" = $"aabbccdd", // specify a new type code
- #'dude' raw "buffer2" = $"aabbccdd" // you can also combine them
-};</PRE></BLOCKQUOTE>
-
-<P>A special type of message is the "archive". The BeOS API allows you to take a \
BArchivable class and flatten it into a BMessage. You can also add such archives to \
your resource scripts:</P>
-
-<BLOCKQUOTE><PRE>resource(24) #'BBMP' archive BBitmap
-{
- "_frame" = rect { 0.0, 0.0, 63.0, 31.0 },
- "_cspace" = 8200,
- "_bmflags" = 1,
- "_rowbytes" = 256,
- "_data" = array
- {
- ... /* here goes the bitmap data */ ...
- }
-};</PRE></BLOCKQUOTE>
-
-<P>So what's this "rect" thing in the "_frame" field? Besides arrays and messages, \
the compiler also supports a number of other data structures from the \
BeAPI:</P>
-
-<BLOCKQUOTE><TABLE BORDER=1 SUMMARY="">
-<TR><TH>type</TH><TH>corresponds to</TH><TH>fields</TH></TR>
-<TR><TD>point</TD><TD>BPoint, B_POINT_TYPE</TD><TD>float x, y</TD></TR>
-<TR><TD>rect</TD><TD>BRect, B_RECT_TYPE</TD><TD>float left, top, right, \
bottom</TD></TR>
-<TR><TD>rgb_color</TD><TD>rgb_color, B_RGB_COLOR_TYPE</TD><TD>uint8 red, green, \
blue, alpha</TD></TR>
-</TABLE></BLOCKQUOTE>
-
-<P>To add a color resource to your script, you can do:</P>
-
-<BLOCKQUOTE><PRE>resource(25) rgb_color { 255, 128, 0, 0 };</PRE></BLOCKQUOTE>
-
-<P>Or you can use the field names, in which case the order of the fields does not \
matter:</P>
-
-<BLOCKQUOTE><PRE>resource(26) rgb_color
-{
- blue = 0, green = 128, alpha = 0, red = 255
-};</PRE></BLOCKQUOTE>
-
-<P>You can also make your own data structures, or as we refer to them, "user-defined \
types". Suppose that your application wants to store its GUI elements in the \
resources:</P>
-
-<BLOCKQUOTE><PRE>type #'menu' menu
-{
- string name,
- int32 count, // how many items
- array items // the menu items
-};
-
-type #'item' menuitem
-{
- string name,
- message msg,
- bool enabled = true // default value is "true"
-};</PRE></BLOCKQUOTE>
-
-<P>A type has a name, an optional type code, and one or more fields. You are advised \
not to pick a type code that already belongs to one of the built-in types, to avoid \
any confusion. Each field has a data type, a name, and a default value. If you don't \
specify a default, it is typically 0 or empty. To create a new menu resource using \
the types from the above example, you might do:</P>
-
-<BLOCKQUOTE><PRE>resource(27) menu
-{
- name = "File",
- count = 3,
- items = array
- {
- menuitem { "New...", message('fnew') },
- menuitem { "Print...", message('fprt'), false },
- menuitem { "Exit", message('_QRQ') }
- }
-};</PRE></BLOCKQUOTE>
-
-<P>Like an array, a type resource doesn't remember its internal structure. You can \
regard types as fancy arrays that are easier to fill in, a template if you will. \
User-defined types work under the same rules as the built-in types point, rect, and \
rgb_color, so you can specify the fields in order or by their names. If you don't \
specify a field, its default value will be used.</P>
-
-<P>Types can also have a default resource ID and/or name. If you omit to give the \
resource an ID or a name, it uses the defaults from its data type. For example, \
this:</P>
-
-<BLOCKQUOTE><PRE>type myint { int32 i };
-resource(10, "MyName") myint { 123 };</PRE></BLOCKQUOTE>
-
-<P>Is equivalent to this:</P>
-
-<BLOCKQUOTE><PRE>type(10, "MyName") myint { int32 i };
-resource myint { 123 };</PRE></BLOCKQUOTE>
-
-<P>And to save you even more typing, simple types that have only one field can also \
be specified as:</P>
-
-<BLOCKQUOTE><PRE>resource myint 123;</PRE></BLOCKQUOTE>
-
-<P>Most data types have a fixed size; a uint16 is always 2 bytes long, a float \
always comprises 4 bytes, and so on. But the sizes of string and raw data resources \
depend on what you put in them. Sometimes you may want to force these kinds of \
resources to have a fixed size as well. You can do this as \
follows:</P>
-
-<BLOCKQUOTE><PRE>type fixed { string s[64] };</PRE></BLOCKQUOTE>
-
-<P>Any resources with type "fixed" will always contain a 64-byte string, no matter \
how many characters you actually specify. Too much data will be truncated; too little \
data will be padded with zeroes. Note that string resources are always terminated \
with a null character, so string "s" in the above type only allows for 63 real \
characters. The number between the square brackets always indicates bytes (unlike \
C/C++ arrays which use a similar notation).</P>
-
-<P>If you have (large) binary files that you want to include in the resources, such \
as pictures of Buffy, you don't need to convert the binary data to text form first. \
You can simply "import" the file:</P>
-
-<BLOCKQUOTE><PRE>resource(22) #'PNG ' import "buffy.png";</PRE></BLOCKQUOTE>
-
-<P>Imported resources are always arrays (raw data), and you can specify the import \
statement everywhere that array data is valid.</P>
-
-<!-- *********************************************************************** -->
-
-<A NAME="app"></A>
-
-<H2>Application resources</H2>
-
-<P>All BeOS applications (except command line apps) have a basic set of resources, \
such as a MIME signature, launch flags, icons, and a few others. Adding these kinds \
of resources is easy, because rc also has a number of built-in types \
for that:</P>
-
-<BLOCKQUOTE><TABLE BORDER=1 SUMMARY="">
-<TR><TH>type</TH><TH>corresponds to</TH><TH>fields</TH></TR>
-
-<TR><TD>app_signature</TD><TD>the app's MIME signature</TD><TD>string
-signature</TD></TR>
-
-<TR><TD>app_flags</TD><TD>application launch flags</TD><TD>uint32
-flags</TD></TR>
-
-<TR><TD>app_version</TD><TD>version information</TD><TD>uint32 major, middle,
-minor, variety, internal<BR>string short_info, long_info</TD></TR>
-
-<TR><TD>large_icon</TD><TD>32x32 icon</TD><TD>array of 1024 bytes</TD></TR>
-
-<TR><TD>mini_icon</TD><TD>16x16 icon</TD><TD>array of 256 bytes</TD></TR>
-
-<TR><TD>file_types</TD><TD>supported file types</TD><TD>message</TD></TR>
-
-</TABLE></BLOCKQUOTE>
-
-<P>Here are some examples on how to use these resources. These things are also \
documented in the Storage Kit section of the BeBook, so refer to that for more \
information.</P>
-
-<P>The signature:</P>
-
-<BLOCKQUOTE><PRE>resource app_signature \
"application/x-vnd.YourName.YourApp";</PRE></BLOCKQUOTE>
-
-<P>The application flags determine how your application is launched. You must 'OR' \
together a combination of the following symbols:</P>
-
-<UL>
-<LI><CODE>B_SINGLE_LAUNCH</CODE></LI>
-<LI><CODE>B_MULTIPLE_LAUNCH</CODE></LI>
-<LI><CODE>B_EXCLUSIVE_LAUNCH</CODE></LI>
-<LI><CODE>B_BACKGROUND_APP</CODE></LI>
-<LI><CODE>B_ARGV_ONLY</CODE></LI>
-</UL>
-
-<P>For example:</P>
-
-<BLOCKQUOTE><PRE>resource app_flags B_SINGLE_LAUNCH | \
B_BACKGROUND_APP;</PRE></BLOCKQUOTE>
-
-<P>The version information resource contains a number of fields for you to fill in. \
Most are pretty obvious, except maybe for the "variety" field. It can take one of the \
following values:</P>
-
-<UL>
-<LI><CODE>B_APPV_DEVELOPMENT</CODE> - development version</LI>
-<LI><CODE>B_APPV_ALPHA</CODE> - alpha version</LI>
-<LI><CODE>B_APPV_BETA</CODE> - beta version</LI>
-<LI><CODE>B_APPV_GAMMA</CODE> - gamma version</LI>
-<LI><CODE>B_APPV_GOLDEN_MASTER</CODE> - golden master</LI>
-<LI><CODE>B_APPV_FINAL</CODE> - release version</LI>
-</UL>
-
-<P>For example:</P>
-
-<BLOCKQUOTE><PRE>resource app_version
-{
- major = 1,
- middle = 0,
- minor = 0,
- variety = B_APPV_BETA,
- internal = 0,
- short_info = "My Cool Program",
- long_info = "My Cool Program - Copyright Me"
-};</PRE></BLOCKQUOTE>
-
-<P>The supported file types resource contains a list of MIME types, not unlike \
this:</P>
-
-<BLOCKQUOTE><PRE>resource file_types message
-{
- "types" = "text/plain",
- "types" = "text"
-};</PRE></BLOCKQUOTE>
-
-<!-- *********************************************************************** -->
-
-<A NAME="compile"></A>
-
-<H2>Compiling</H2>
-
-<P>rc is a command line tool, which means you must run it from a Terminal window. \
Typical usage example:</P>
-
-<BLOCKQUOTE><PRE>rc -o things.rsrc things.rdef</PRE></BLOCKQUOTE>
-
-<P>This tells rc that you wish to compile the script "things.rdef" to the resource \
file "things.rsrc". The default name for the output file is "out.rsrc", but you can \
change that with the <CODE>-o</CODE> or <CODE>--output</CODE> switch, just like we \
did here.</P>
-
-<P>You can specify multiple rdef files if you wish, and they will all be compiled \
into one big resource file. If your rdef files #include files that are not in the \
current working directory, you can add include paths with the <CODE>-I</CODE> or \
<CODE>--include</CODE> option. For a complete list of options, type <CODE>rc \
--help</CODE>.</P>
-
-<P>If your project uses a Makefile, you can have rc automatically generate the \
resource file for you:</P>
-
-<BLOCKQUOTE><PRE>things.rsrc: things.rdef
- rc -o $@ $^</PRE></BLOCKQUOTE>
-
-<!-- also: how to integrate rc in jamfiles -->
-
-<!-- *********************************************************************** -->
-
-<A NAME="decompile"></A>
-
-<H2>Decompiling</H2>
-
-<P>Of course you can write the resource scripts by hand, but if you already have a \
.rsrc file you can tell rc to decompile it. This will produce a ready-to-go rdef \
script, and save you some trouble. (Although in some cases it may be necessary to \
edit the script a little to suit your needs.) Note that rc isn't limited to just \
.rsrc files; you can decompile any file that has resources, including \
applications.</P>
-
-<P>For example, to decompile the file "things.rsrc" into "things.rdef", do:</P>
-
-<BLOCKQUOTE><PRE>rc --decompile -o things.rdef things.rsrc</PRE></BLOCKQUOTE>
-
-<P>The decompiler produces an rdef resource script with the name "out.rdef", but you \
can change that name with the <CODE>-o</CODE> or <CODE>--output</CODE> switches. If \
you specify the <CODE>--auto-names</CODE> option, rc will also write a C/C++ header \
file. Any resources whose name is a valid C/C++ identifier will be added to the \
header file. Now your program can access the resource using this \
symbolic name.</P>
-
-<P>Note: Even though rc can decompile multiple .rsrc files into one script, it does \
not detect conflicts in resource names or IDs. In such cases, the resulting .rdef \
and/or .h files may give errors when you try to compile them.</P>
-
-<!-- *********************************************************************** -->
-
-<A NAME="authors"></A>
-
-<H2>Authors</H2>
-
-<P>The rc resource compiler and its companion library librdef were written by <A \
HREF="mailto:mahlzeit@users.sourceforge.net">Matthijs Hollemans</A> for the <A \
HREF="http://www.haiku-os.org">Haiku</A> project. Thanks to Ingo Weinhold for the \
Jamfile and the Jam rules. Comments, bug reports, suggestions, and patches are \
welcome!</P>
-
-<!-- *********************************************************************** -->
-
-<A NAME="license"></A>
-
-<H2>License</H2>
-
-<P>Copyright (c) 2003 Matthijs Hollemans</P>
-
-<P>Permission is hereby granted, free of charge, to any person obtaining a copy of \
this software and associated documentation files (the "Software"), to deal in the \
Software without restriction, including without limitation the rights to use, copy, \
modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, \
and to permit persons to whom the Software is furnished to do so, subject to the \
following conditions:</P>
-
-<P>The above copyright notice and this permission notice shall be included in all \
copies or substantial portions of the Software.</P>
-
-<P>THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR \
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR \
A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT \
HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF \
CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE \
OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.</P>
-
-</BODY>
-</HTML>
diff --git a/src/bin/rc/docs/todo.html b/src/bin/rc/docs/todo.html
deleted file mode 100644
index 8e70f41a7c..0000000000
--- a/src/bin/rc/docs/todo.html
+++ /dev/null
@@ -1,22 +0,0 @@
-<HTML>
-<HEAD>
-<TITLE>Ye Olde To Do List</TITLE>
-</HEAD>
-<BODY BGCOLOR="#FFFFFF">
-
-<H1>Ye Olde To Do List</H1>
-
-<P>What will future versions of rc bring? Here are some ideas.</P>
-
-<UL>
-
-<LI>Attributes, so you can also use rdef scripts to add attributes to your files \
instead of (or in addition to) resources.<BR> </LI>
-
-<LI>Expand the expressions to handle other data types besides integer data. This \
would include floating point (+ - * /), string (+), raw (+), and booleans (! \
&& ||).<BR> </LI>
-
-<LI>Allow users to create their own symbolic constants.</LI>
-
-</UL>
-
-</BODY>
-</HTML>
[prev in list] [next in list] [prev in thread] [next in thread]
Configure |
About |
News |
Add a list |
Sponsored by KoreLogic