The mwbres Tool



mwbres is a tool that lets you declare resources in a text file (which we'll call a restext file).  The tool converts the restext file into binary resource data and writes it out as a resource file.  The tool can also merge the converted data into an existing resource file; this is particularly handy when you're adding resources to an existing application (keep in mind that an application executable is a resource file).


Declaring a Resource

A restext file can declare any number of resources.  Each resource is listed in its own resource() declaration:

    resource( type, id, name )
    {
       data1,
       data2,
       data3,
       ...
    }

The declaration's arguments are identifiers that are assigned to the resource that you're creating:

  • type is a four-byte type code (e.g. 'ICON').

  • id is an integer ID.  The combination of the type and the id must uniquely identify the resource within the resource file.

  • name is a string name that needn't be unique.  Use an empty string ("") if you don't want a name.

The body of the resource() declaration contains one or more data entries, separated by commas.  (Typically, a resource contains only one data entry.)  A data entry can be a string or integer value, or it can be a read() or import() statement (described in the next section).  The declaration below shows all four data entry types:

    resource('DATA', 1, "Some Resource")
    {
       23,
       "level 1",
       read("somefile"),
       import("otherfile.rsrc", 'TYPE', 12)
    }
The data for a given resource is a concatenation of all the data entries in the resource() declaration. 


read() and import()

    read( pathname )            
    import( pathname, type, id|name )
The read() statement reads data from the named file (it reads the entire file). 

import() copies resource data from an existing resource file.  The resource file is identified by pathname, and the resource within the file is identified by a combination of (a) the four-byte type and (b) the integer id or string name.

For both statements, pathname can be an absolute or relative path, and can contain the parent directory symbol "..".


Data Alignment

You can align data by combining an entry with a pad() statement.  pad() takes a single integer argument that gives the boundary (in bytes) that you want the data aligned to.  If the length of the data isn't a multiple of the pad length, the data is padded with trailing zeros.

To combine an entry with a pad() statement, you enclose both statements in curly brackets ("{}").  For example, here we align a series of strings to four-byte boundaries:

    resource('DATA', 1, "Some Resource")
    {
       { "level 1", pad(4) },
       { "level 2", pad(4) },
       { "level 3", pad(4) }
    }


Running mwbres

mwbres can be invoked from the command line, or it can be invoked automatically from the BeIDE (as explained in Using MWBResPlugin).

Run from the command line, the command has this syntax:

    usage: mwbres [-merge] [-o filename.rsrc] source.r

  • source.r is the input restext file.  The ".r" extension is a convention; it isn't mandatory. 

  • You can specify the output resource file thorugh the argument to the -o switch.  Again, the ".rsrc" extension is merely a convention.  If you don't specify a file, the resource data is written to output.rsrc.

  • If you want to merge the new resource data into an existing resource file, include the -merge option.

mwbres only overwrites the resource section of the file.  For example, if you write new resources to an application without merging, the application code is preserved, but the resources are completely replaced.

The resource data that's generated by mwbres is in the native endianess of the machine that the program is run on (i.e. big-endian for PPC, little-endian for Intel).




BeOS Release 4.5




Copyright © 1999 Be, Inc.  All rights reserved.