Last update Sat Apr 8 23:54:06 2006

Compiling
• Compiling Code
• C Implementation
• C++ Implementation
• Language Extensions
• Mixing Languages
• Assembly Language
• Inline Assembler
• Optimizing Code
• Numerics Programming
• Regular Expressions
• Acrtused
• Pragmas
• Precompiled Headers
• Predefined Macros
• Warning Messages
• Error Messages
• Runtime Messages

Linking
• Optlink
• Switches
• Module Definition Files
• Operation and Design
• Error Messages

Win32 Programming
• Win32 Programming

DOS and Win16
Programming
• Memory Models
• 16 Bit Pointer Types
and Type Modifiers
• Handle Pointers
• DOS
• DOS 32 (DOSX)
• Win16
• Win16 DLLs
• Win16 Prolog/Epilog

C/C++ Extensions
• Contract Programming
• __debug statement
• __debug declaration
• Dynamic Profiling
• Embedding C in HTML

Tools
• BCC
• CHMOD
• CL
• COFF2OMF
• COFFIMPLIB
• DMC
• DIFF
• DIFFDIR
• DUMP
• DUMPOBJ
• DUMPEXE
• EXE2BIN
• FLPYIMG
• GREP
• HC
• IMPLIB
• LIB
• LIBUNRES
• MAKE
• MAKEDEP
• ME
• OBJ2ASM
• PATCHOBJ
• RC
• RCC
• SC
• SHELL
• SMAKE
• TOUCH
• UNMANGLE
• WHEREIS

Porting to DMC++
• Switching to DMC++
• from Microsoft
• from Borland
• Porting Guide

Compiling Resources with RC

This chapter describes the Microsoft Resource Compiler (RC) - a tool that compiles resources such as icons, cursors, menus, and dialog boxes, that your application uses. You add the resulting binary resource file to the application's binary file to produce an executable Windows 3.x application.

Note: When building a program with the IDDE, it calls Digital Mars' RCC resource compiler to compile the program's resources (the Symantec linker actually binds the resources to the executable). In contrast, RC both compiles the resources and binds them to the executable.

What's in This Chapter

How to include resources in an application.
How to create resource scripts.
RC command line syntax and options.

Including Resources in an Application

To include resources in a Windows 3.x application, follow these steps:

Create individual resource files for cursors, icons, bitmaps, dialogs, and fonts, using the appropriate resource editors.
Create a resource script (.rc) file that defines each application resource by specifying its name and description. If the resource is in a separate file, this description includes that file's name. For example, the .rc file might define a cursor resource by naming it SampleCursor, describing it as a resource of type Cursor, and defining it as the cursor contained in the file sample.cur.
Compile the resource script file using RC. The result will be a compiled resource file with the file extension .res.
Add the compiled resources to the application's compiled executable (.exe) file using RC. You can perform this step and the preceding step with a single RC command.

Creating a Resource Script File

After creating individual resource files for the application's icon, cursor, bitmap, font, and dialog resources, create a resource script file. The resource script file always has the .rc extension and is often referred to simply as the .rc file.

The resource script file lists every resource in the application and describes some types of resources in detail:

For resources that exist in a separate file, such as icons and cursors, the resource script file simply names the resource and the file that contains it.
For some types of resources, such as menus, the entire definition of the resource exists within the resource script file.

Create a resource script file using any ASCII text editor. The file can contain resource statements and directives. Resource statements name and describe each resource. Directives are a special type of statement that define an action you want RC to perform on the resource script file before actually compiling it. You can use directives to assign values to names, include the contents of files, and control compilation of the script file. You use directives in a resource script file the same way you use the corresponding C language directives.

Note: A line in the resource script file cannot exceed 256 characters.

Using RC

RC does the following:

Compiles the resource script file and the resource files, such as icon and cursor files, into a binary resource (.res) file.
Combines the compiled resource file with the executable (.exe) file created by the linker. The result is an executable Win16 application.
Marks all Win16 applications (even if they have no resources) with a Windows version stamp.

To start RC, use the RC command. What you specify on the command line will depend on whether you are compiling resources, adding compiled resources to an executable file, or both. For more information, see the section "Different Ways to Use the RC Command" later in this chapter.

RC command syntax

RC commands have the following form:

	RC [options] [resource-file] [executable-file]

The options are command line options. The resource-file is the name of the resource file, and executable-file is the name of the executable with which you want to combine resource-file. These command parameters are described below.

The "options" parameter

RC options are not case-sensitive. For example, -r and -R are equivalent. You can combine single-letter options if they do not require any additional parameters. For example, the command:

	RC -R -E -V SAMPLE.RC

is equivalent to the command:

	RC -REV SAMPLE.RC

The options parameter can include one or more of the RC options described in the section below.

Resource-file parameter

The resource-file parameter specifies the name of the script file that contains the names, types, filenames, and descriptions of the resources you want to add to the executable file. It can also specify the name of a compiled resource file in which case RC adds the compiled resources to the executable file.

Executable-file parameter

The executable-file parameter specifies the name of the executable file to which the resources should be added. If you do not specify an executable file, RC uses the executable file with the same name as the script file.

RC Options

This section describes the options you can use with RC.

-D

Defines a symbol for the preprocessor that you can test with the #ifdef directive.

You can specify conditional branching in a resource script file based on whether or not a term is defined on the RC command line using the -D option. For example, suppose your application has a pop-up menu, the Debug menu, which you want to appear only during debugging. When you compile the application for normal use, the Debug menu is not included. Your resource script file contains the following statements to define the Debug menu:

	MainMenu MENU
	BEGIN 
	...
	#ifdef DEBUG 
	POPUP &Debug
	    BEGIN 
	    MENUITEM &Memory usage, ID_MEMORY
	    MENUITEM &Walk data heap, ID_WALK_HEAP 
	    END
	#endif 
	END

When compiling resources for a debugging version of the application, you include the Debug menu by using the following command:

	RC -R -D DEBUG MYAPP.RC

To compile resources for a version of the application that does not include the Debug menu, you would use the following command:

	RC -R MYAPP.RC

Naming files

These switches let you control how RC names the executable and resource files it creates.

-FE

Names the executable file.

-FO

Renames the resource file.

Normally, RC names the compiled resource file after the resource script file and places it in the same directory as the script file. For example, when compiling myapp.rc, you would normally type:

	RC -R MYAPP.RC

RC would then create a compiled resource file named myapp.res in the same directory as myapp.rc.

This option lets you give the resulting resource file a name that differs from the corresponding resource script file. For example, to name the resulting resource file newfile.res, you could type:

	RC -R -FO NEWFILE.RES MYAPP.RC

You can also use this option to place the resource file in a different directory. For example, the following command places the compiled resource file myapp.res in the directory C:\RESOURCE:

	RC -R -FO C:\SOURCE\RESOURCE\MYAPP.RES MYAPP.RC

Choosing the directories that RC searches

Normally, RC searches for include files and resource files, such as icon and cursor files, first in the current directory and then in the directories specified by the INCLUDE environment variable. (The PATH environment variable has no effect on the directories RC searches.)

-I

Searches the specified directory before searching the directories specified by the INCLUDE environment variable.

If you use this option, the compiler searches directories in the following order:

The current directory
The directory or directories you specify by using the -I option, in the order in which they appear on the command line
The list of directories specified by the INCLUDE environment variable, in the order in which the variable lists them, unless you specify the -X option

The following example compiles the resource script file myapp.rc and adds the compiled resources to myapp. exe:

	RC -I C:\SOURCE\STUFF -I D:\RESOURCES MYAPP.RC MYAPP.EXE

When compiling the script file, RC searches for include files and resource files first in the current directory, then in C:\SOURCE\STUFF and D:\RESOURCES, and lastly in the directories specified by the INCLUDE environment variable.

-X

Prevents RC from checking the INCLUDE environment variable when searching for include files or resource files.

If you use this option, the compiler searches for files in the current directory and in any directories you specify using the -I option. The following example compiles the resource script file myapp.rc and adds the compiled resources to myapp. exe:

	RC -X -I C:\SOURCE\STUFF MYAPP.RC MYAPP.EXE

When compiling the script file, RC searches for include files and resource files first in the current directory and then in C:\SOURCE\STUFF.

Memory utilization

These options let you specify how your application uses memory.

Note: The Memory options have no effect on applications written for Windows 3.1 or later.

-E

For a DLL, changes the default location of global memory from below the EMS bank line to above it.

-L

Tells Windows that the application uses expanded memory directly, according to the Lotus-Intel-Microsoft Expanded Memory Specification (EMS), version 2.2.

This switch can also be specified as -LIM32.

-M

Assigns each instance of the application task to a distinct EMS bank, when Windows is running with the EMS 4.0 memory configuration. By default, all instances of a task share the same EMS bank.

This option can also be specified as -MULTINST.

-P

Creates a private DLL that is called by only one application. This allows Windows to use memory more efficiently because only one application (or multiple instances of the same application) will be calling into the DLL. For example, in the large-frame EMS memory model, the DLL is loaded above the EMS bank line, freeing memory below the bank line.

-T

Creates an application that runs only with Windows in protected (standard or 386 enhanced) mode. If the user attempts to run the application in real mode, Windows displays a message box telling the user that the application cannot run in real mode.

Optimizing

This option lets you choose whether RC optimizes your resources for preloading.

-K

Disables RC's load-optimization feature. If this option is not specified, the compiler arranges segments and resources in the executable file so that all preloaded information is contiguous. This feature allows Windows to load the application much more quickly.

Without the -K option, all data segments, nondiscardable code segments, and the entry-point code segment will be preloaded, unless any segment and its relocation information exceed 64KB. If the PRELOAD attribute is not assigned to these segments in the module-definition (. def) file when you link your application, the compiler will add the preload attribute and display a warning. Resources and segments will have the same segment alignment. This alignment should be as small as possible to prevent the final executable file from growing unnecessarily large. You can set the alignment using the linker's /alignment option.

Compiling resources separately

This option lets you choose where to place the resources: in a resource file or an executable file.

-R

Creates a resource file from a resource script file.

By default, RC adds the compiled resources to the specified executable file. Sometimes you might want to compile the resources first and then add them to the executable file in separate steps. This can be useful if the contents of a resource file will be stable after initial development. You can save time by compiling resources separately, then adding the compiled resource file to your executable file each time you recompile the executable.

You can use the -R option to compile the resources separately, without adding them to the executable file. When you use this option, RC compiles the resource script file and creates a compiled resource file. For example, this command reads the resource script file sample.rc and creates the compiled resource file sample.res:

	RC -R SAMPLE.RC

The command does not add sample.res to the executable file.

Displaying progress messages

-V

Normally, RC does not display messages that report on its progress as it compiles. You can, however, tell the compiler to display these messages with this option. The following example causes the compiler to report on its progress as it compiles the script file sample.rc, creates the compiled resource file sample.res, and adds the resource file to the executable file sample. exe:

	RC -V SAMPLE.RC

On-line help

This option displays on-line help for RC.

-H, -?

Displays a list of the RC command line options.

Different Ways to Use the RC Command

This section describes the various ways you can use the RC command.

Compiling a resource script file

To compile resources separately, use the RC command in the following form:

	RC -R options script-file

When you use this form, RC ignores the executable file if you specify one.

Compiling and adding to an executable

To compile a resource script file and add the resulting resource file to the executable file, use the RC command in the following form:

	RC options script-file executable-file

Creating a DLL without resources

To compile a DLL that does not have a resource file, use the RC command in the following form:

	RC options dll-file

When you use this form, the DLL filename must explicitly have an .exe, .drv, or .dll extension.

Adding resources to an executable

To add a compiled resource (.res) file to an executable file, use the RC command in the following form:

	RC options res-file.RES executable-file