[Next] [Prev] [TOC]

Chapter 5

Developing Be Applications

You have a number of choices for how you develop applications for the BeOS:

You also have some choices for how you debug applications:

Other applications you use when developing applications are:

In addition to this guide, you'll want to refer to:

Caution: The development environment won't work as described in this chapter unless you carefully follow the directions in Installing the BeOS, the document that accompanies this user's guide.

Developing Applications in the BeOS

The BeOS comes with a copy of the Metrowerks development environment for the BeOS. You can use this environment to develop applications in two ways: By using BeIDE, the CodeWarrior Integrated Development Environment for the BeOS, or by using the compiler and linker (mwcc, mwld) and the make command in a Terminal window.

About the Development Environment for the BeOS

BeIDE, the folders for the headers, libraries, tools, some sample projects, and other parts of the Be development environment are in the /develop folder. The folders in the /develop folder include:

/system/lib contains an additional Be library: libbe.so, the shared library that includes the Be kits and the standard C library.

Using BeIDE

BeIDE is based on the CodeWarrior IDE for the Macintosh; they work in much the same way. BeIDE is documented in the HTML edition of CodeWarrior Documents for Be, which you can read with NetPositive. To start, drag /documentation/metrowerks/HTMLDocs/index.html onto NetPositive's application icon.

To create your own application or other project using BeIDE, it's easiest to copy the sample project folder (in /develop/projects) that most closely matches the kind of project you want to create. Rename the project file (it has a ".proj" extension) to match the name of your project (keeping the .proj extension), and replace the existing source files with your own.

Double-click the project file you just renamed to start BeIDE and to open a project window. In the project window, select the source files for the project you copied and choose Remove Files from the project window's Project menu. Then use the Project menu's Add Files command to add the source files for your project.

Choose Settings from BeIDE's main menu to open the Settings window. Under Project, click PPC Project and replace the file name of the project you copied with the file name of your project, and type your application's signature in the Creator field (for more information on application signatures, see "Creating an Application-Information Resource"). Click Access Paths and make sure the Project and System paths include all the headers and libraries you rely on in your code. Refer to the CodeWarrior Documents for Be to learn more about these and other settings. When you're done, click the Save button and then close the Settings window.

Now you're ready to build your application: Choose Make from the project window's Project menu. BeIDE compiles and links your project. The compiled application is saved in the project folder, along with an ".xMAP" file for debugging (see "Using the Be Debugger").

If you're creating an application, you'll probably want to give it an icon and other resources. To learn how, see "Creating Resources for a Be Application".

Using the Tools from the Command Line

You can use the Metrowerks tools, mwcc and mwld, to build applications from the command line in the Terminal application. These tools and the disassembler, mwdis, are documented in CodeWarrior Documentation for Be. This approach is steeped in tradition: To build an application, you edit "make" files and invoke command-line driven tools.

Preparing the Makefile

The easiest way to build an application is to copy the sample project (in /develop/projects) that most closely matches the type of project you want to build, remove the example sources, and add your own.

Edit the project-building instructions, that are contained in the makefile file in the project folder. The essential steps are these (using the makefile from HelloWorld as an example):


After you've edited the makefile, you're ready to build your application.

Building the Application

To build an application, you start the Terminal application, cd to the folder where your application lives, and enter make:

The make program reads the makefile, then invokes the compiler (mwcc) and linker (mwld) according to the instructions that it finds there.

To start from scratch, type:

This removes the executable file and all previously compiled object files.

If you're creating an application, you'll probably want to give it an icon and other resources. Each time you compile your application, you need to add the resources to the application file. To learn how, see "Creating Resources for a Be Application".

Developing BeOS Applications on a Macintosh

You can use CodeWarrior on a Macintosh to develop applications for the BeOS. To do this, you first need to install the Macintosh version of the Be headers and libraries, as described in Installing the BeOS.

Using the CodeWarrior IDE

The CodeWarrior IDE is documented in Inside CodeWarrior, which is available from Metrowerks. However, stepping through the simple process of building the sample HelloWorld application is a good way to familiarize yourself with using CodeWarrior to build a Be application.

Create a folder on the Macintosh where you will keep your Be project files. Then transfer the six source files (the three files that end in ".cpp" and the three that end in ".h") from the /develop/projects/HelloWorld folder in the BeOS to the new folder on the Macintosh, using a file transfer utility, such as ftp or tar (see Appendix B, "Transferring Files to and from the BeOS,"for more information). Make sure you transfer the files as text files, or use a file-typing utility on the Macintosh (such as ResEdit or FileTyper) to set their file types as TEXT, so CodeWarrior will be able to open them.

Double-click the CodeWarrior IDE to start it and choose New Project from the File menu. In the dialog box that prompts you to name your project, select Be Application from the pop-up list, type a name for your project (typically the same name as your application, but with a "." extension—in this case, HelloWorld.), and save the new project in the folder where you transferred the HelloWorld source files. A project window opens for your new project.

Choose Add Files from the Project menu and in the dialog box that appears, double-click each of the ".cpp" files and then click Done. This adds the HelloWorld sources to the project window. Note that the stationery includes BeHeaders.pch, the source file for the precompiled headers, so you will generate the precompiled header file (BeHeaders) when you build the project.

Choose Preferences from the Edit menu. In the dialog box that appears, click PPC Project and replace "BeApp" in the File Name field with the name of your application, HelloWorld in this example. Then click OK.

Now you can build your application: Choose Make from the Project menu. The IDE precompiles the Be headers first. Then it compiles and links HelloWorld.

The compiled application and two symbol files are saved in the same folder as the project file and sources. You use the symbol file with the ".xMAP" extension to debug the application in the BeOS (as described in "Using the Be Debugger"), or the symbol file with the ".xSYM" extension to debug your application with the cross-debugger on the Macintosh (as described in the next section, "Using the Cross-Debugger").

Once you've built an application, you can transfer it to the BeOS, as described in Appendix B, "Transferring Files to and from the BeOS," or by using the Metrowerks cross-debugger (as described in the next section). When you transfer the application to the BeOS, don't forget to include the symbol file for debugging (it's the file with the ".xMAP" extension).

Using the Cross-Debugger

There is a preliminary version of the Metrowerks symbolic debugger for the BeOS in the /develop/metrowerks/debugger folder. However, you may find it more convenient to use the cross-debugger on the Macintosh. The Macintosh cross-debugger works with a "nub application" in the BeOS to transfer the application you developed on the Macintosh to the BeOS, either across an Ethernet network or across a direct serial connection. Then you can use the commands and other tools in the cross-debugger on the Macintosh to run, stop, and debug the application in the BeOS.

If you're planning to communicate between the Macintosh and the BeOS across an Ethernet network, test the connection with ftp or another utility to make sure you can transfer files successfully before you try to set up the cross-debugger and the nub. (For more information, see "Using ftp".)

Caution: The connection between the cross-debugger and the Nub is fragile. Follow the instructions in this section carefully or you will likely crash both the Macintosh and the BeOS when you try to use the cross-debugger.

Setting Up the Nub in the BeOS

  1. Double-click the nub: It's named Nub.
  2. The nub is in the /develop folder, if you copied it from the /optional/macintosh/Cross-Debugger folder on the BeOS CD-ROM when you installed the BeOS, as described in Installing the BeOS.

  3. Choose Settings from the File menu in the MetroNub window.
  4. Click the Misc. tab in the NubSettings window and click TCP/IP, if you're using an Ethernet network, or Serial, if you've connected the MacOS computer and BeOS computer directly by their serial ports.
  5. If you're using a serial connection, click the Serial tab and replace the "3" in "serial3" with the number of the serial port you're using on the BeOS computer to connect to the Macintosh.
  6. If you're using an Ethernet network, it's best to leave the TCP/IP Port Number in the TCP/IP tab at its default setting: 4712. This matches the default setting on the Macintosh cross-debugger.
  7. Leave the Files tab alone for the moment.
  8. Close the NubSettings window.

The nub stores your settings in the Be database. If its settings seem to get scrambled, or if the nub stops working, you can remove all the nub settings from the Be database using the Terminal application: cd to the folder that contains the nub and enter Nub -reset

Caution: If you quit the Nub application, you must restart the BeOS before you can start it again and establish a connection with the Macintosh cross-debugger.

Setting Up the Cross-Debugger on the Macintosh

Once you've set up the nub in the BeOS, you can set up the cross-debugger on the Macintosh.

  1. Double-click the cross-debugger. It's named MW Debug XPPC-1.4.3d1.
  2. The cross-debugger is in the same folder as the IDE, if you followed the instructions in Installing the BeOS.

  3. In the dialog box that asks you to select a SYM file, click Cancel.
  4. Choose Target Preferences from the Edit menu and uncheck the "Automatically launch applications when SYM file opened" and "QC-aware" options. Then click OK.
  5. Choose Cross-PPC Preferences from the Edit menu. If you're using an Ethernet network, click TCP/IP and type the IP address of the BeOS computer in the Address field and leave the "Port no" field set to 4712—unless you had to change the port in the Be nub. If you're using a direct serial connection, click Serial and click the button that matches the port the serial cable is connected to: Modem Port or Printer Port. Then click OK.

The cross-debugger is set up. You can leave it running, or quit it and restart it later, when you're ready to debug an application.

Debugging Applications

Using the CodeWarrior symbolic debugger is explained in Inside CodeWarrior, the documentation available from Metrowerks. But in outline, the process of debugging a Be application is fairly simple.

  1. Make sure you've set up the cross-debugger on the Macintosh and the nub in the BeOS, as described above.
  2. Create a folder for your application in the BeOS. Put a copy of the resource file for the application in the same folder (if you've already created one) and give the resource file the same name as the application, but add the ".rsrc" extension.
  3. Creating resources and resource files is described in "Creating Resources for a Be Application".

  4. Start the nub in the BeOS (if it's not already running), choose Settings from the MetroNub window, click the Files tab in the NubSettings window, and click Add. In the Add Program window that opens, type the name of your application and "Save" it in the folder you created in the previous step. Then close the NubSettings window.
  5. Note: You must click in the Save panel's file name field to save a file in an empty folder.

    Though no file is saved in the folder yet, "saving" in this way tells the nub where to save the file it receives from the cross-debugger on the Macintosh.

  6. Compile your application using the CodeWarrior IDE on the Macintosh.
  7. On the Macintosh, drag your application's symbol file onto the cross-debugger icon.
  8. The application's symbol file has the same name as the application, but with an ".xSYM" extension. The code for your application is displayed in the cross-debugger windows.

  9. Choose Run.
  10. If there isn't a copy of your application in the folder in the BeOS you specified in the nub, the cross-debugger transfers a copy to the BeOS and starts to execute the program, stopping at the main() function. When the connection is established between the cross-debugger and the nub, the message in the MetroNub window in the BeOS changes from "Waiting" to "Connected."

  11. Set breakpoints if you want them.
  12. Places in your code where you can set breakpoints are indicated by a small dash in the column to the left of the code. Click a dash to set a breakpoint there—the dash turns to a red dot.

  13. Choose Run again.
  14. The cross-debugger starts the application in the BeOS, and the message in the MetroNub window changes from "Connected" to "Debugging."

  15. When you're done debugging your application, choose your application's Quit command in the BeOS to quit it.
  16. Caution: If you quit the nub while it's connected to the cross-debugger, you will crash the nub. Always quit the cross-debugger on the Macintosh before you quit the nub.

Creating Resources for a Be Application

Once you have your application in the BeOS, you need to provide it a number of resources, including:

An application's resources are stored at the end of the executable portion of the application file. You can also store resources as separate files—with no required extension, though it's convenient to give them ".rsrc" extensions—so you can add them to an application when you need them. (Be application resources must be set up in the BeOS; you can't do it on a Macintosh. Be resources are not the same as a Macintosh resource fork.)

However, you don't have to recreate an application's resources each time you recompile the application. You can set them up once in a stand-alone file and leave them in the BeOS. When you recompile your application, you copy them into the new version of the recompiled application file (as described in "Adding Resources to Applications").

You create and edit resources in either format-as parts of application files or as separate resource files-with the IconWorld application, as described in the next section. You also use three of the tools in /bin to list the resources in a file, remove the resources from a file, or copy the resources from one file to another, as described in "Adding Resources to Applications".

Using IconWorld

You create or open an application or resource file in IconWorld in a number of ways:

If you open an application file in IconWorld, the icons and other resources you create are added to the end of the file when you choose Save, so the resources are assigned to that application. If you open a stand-alone resource file, the resources are simply stored in the file when you choose Save: They aren't assigned to an application until you add them to one. IconWorld's Save As command always creates a stand-alone resource file, even if you started by opening an application.

IconWorld can deal with only one application or resource file at a time; each time it opens an application or resource file, it closes the one it previously had open.

Creating an Application-Information Resource

IconWorld has an App Info menu, which you can use to set up an application-information resource for an application. This resource is of type 'APPI' (for "application information"), hence the name of the first item in the menu—Create APPI. To create or edit resources for a new or existing application or resource file, make sure this item is checked in the menu (by choosing it if it isn't checked). None of the other items in the App Info menu have any effect unless Create APPI is checked.

After Create APPI, the menu has three sections:

For documentation on launch behaviors and the other flags, refer to "Application Information" in the "Application Kit" chapter of The Be Book.

Creating Icons

There are two ways to create icon resources using IconWorld. You can draw the icon in IconWorld, either from scratch or by modifying another icon, or you can import a raw bitmap file that was created elsewhere. The raw bitmap must be fully specified 24-bit color data.

Every icon must have both a large 32 pixel x 32 pixel version and a small 16 pixel x 16 pixel variant. The Browser lets users choose whether to view the larger icon or the smaller mini icon. It displays the larger one by default, but always uses the smaller one in list views in Browser windows and in Open and Save panels.

IconWorld assumes the drawing model discussed in "The Interface Kit" chapter of The Be Book. It would help to know something about that model—including high and low colors, patterns, and transparent pixels—before proceeding.

Drawing Icons

The main IconWorld window has areas where you can draw both a large icon and its smaller counterpart. The icon pair is treated as a unit and share a single file type, as discussed below.

Along its right edge, the IconWorld window lists the icons and their file types. Only the larger icon of the pair is shown. When an icon in this list is selected, its large and small variants are displayed in the drawing areas. The list marks the current item by highlighting its border. (To start, before an application or resource file has any resources, an empty square is marked.)

Towards the bottom, the window displays the current icons, both large and small, in their actual sizes. It shows the icons as they are drawn and also as they will be highlighted by the Browser. Highlighting is accomplished by systematically darkening selected colors.

IconWorld displays three palettes you can use for drawing icons—one of colors, one of tools, and one of patterns.

IconWorld gives you a transparent background to draw on. Transparency doesn't have a hue, so it's displayed on screen as white (you can think of it as a clear sheet of plastic laid over a white surface). In the Colors palette, the transparent color is the white square located at the right bottom corner.

As you draw an icon, keep an eye on how it will be highlighted. You'll notice that pixels that are truly white (opaquely white) become darker when highlighted, just like other colors, but transparent pixels remain transparent (they stay white).

In general, you'll want the pixels around the outside boundary of the image to be transparent, and pixels inside—including those that are white—to be opaque (to have a true color). In this way, only the image will appear to be highlighted, not the background. If white portions inside the image don't darken when the image is highlighted, they'll appear to be transparent and not part of the image at all.

You can think of icons as being imaged in OP_OVER mode and placed over a white background, so that transparency always lets that white color show through.

Importing Icons

You can also import images into IconWorld as 24-bit color bitmaps. Drag a raw data file into IconWorld's main window.

An easy way to create a raw 24-bit color bitmap is to use ResEdit or your favorite paint application on the Macintosh. After the icon is drawn, you need to paste it into a 32 x 32 or a 16 x 16 document in Adobe Photoshop, or any other program that can export 24-bit raw bitmap data.

When creating a new file in Photoshop, set both the width and height to 32 pixels for the larger icon or 16 pixels for the smaller, set the resolution to 72 pixels/inch, and select RGB Color mode.

Once the icon is in a correctly sized Photoshop document, choose Save As from the File menu, name your icon, choose Raw from the pop-up list, and click Save. Then in the dialog box that appears, type 0 in the Header box, click the Interleaved Order option, and click Save (the other options don't matter).

Repeat this process so you have one raw file for the 32 x 32 bitmap and another for the 16 x 16 bitmap.

After you transport the files to the BeOS, simply drag the files into the IconWorld window.

Although their colors will be adapted to the Be color map, IconWorld should display the images as you drew them. However, it interprets all white pixels as being transparent. Look at the way the image will be highlighted; everything that's white stays white. White areas inside the image will appear to be part of the background, as holes you can see through. If there are truly white areas inside the image, you'll need to repaint them with a shade of opaque white chosen from the Colors palette.

Setting File Types

When you save an application or resource file, IconWorld installs both the large and small icons in resources (of type 'ICON' for the large icon and 'MICN' for the mini icon).

If the icon represents the application itself (if it should be displayed for the executable file), its type should be 'BAPP'. If the icon represents a kind of document or other file that the application creates, its type should be identical to the type the application assigns to those files. Types and application signatures are assigned to files by calling BFile's SetTypeAndApp() function. See the BFile class in "The Storage Kit" chapter of The Be Book for details.

Each saved icon needs to be associated with a file type (not to be confused with the 'ICON' and 'MICN' resource types). The Browser uses the icon to represent files of that type. The file type is a multicharacter constant that, along with the application's signature, uniquely identifies files belonging to the application. The constant is formed from four concatenated characters; you can type these characters in the space beneath the icon in the list along the right side of main window.

For example, the document type for the Edit application is 'TEXT'. The Midi application associates its files with the 'MIDI' type. These types are local to the application-they have meaning only within the scope of the application's signature. Only the signature needs to be unique between applications.

Adding Resources to Applications

You add resources to an application in one of three ways:

You can use copyres to copy resources from any application or resource file into any other application or resource file. Simply type copyres file1 file2, where file1 contains the resources you want to copy and file2 is the file to which you want to add the resources. If file2 already has resources, they're replaced. If file2 doesn't exist, copyres creates a resource file with that name. If you use the -a flag with copyres, a copy of the resources in file1 are appended to the existing resources in file2, only replacing file2 resources if the same resources are in file1.

Two other applications in /bin are useful when working with resources: listres and stripres. In a Terminal window, type listres filename to view a table of the resources in filename. Type stripres filename to remove all resources from filename and store them in a stand-alone resource file named filename.rsrc.

Getting the Icons to Be Recognized

When you add resources to an application, the Browser should immediately display your application with its new icons. However, a known bug sometimes prevents it from doing this. To force the Browser to display the new icon, open a Terminal window, cd to the folder that contains the application, and enter setfile followed by the name of the application.

Using the Be Debugger

The Be debugger lets you examine and alter the state of a running (or crashed) application. The Be debugger displays assembly language instructions. See "Using the Cross-Debugger" for information on the Metrowerks symbolic debugger.

In order to be debugged, an application must be accompanied by a symbol file. Symbol files, which are distinguished by their ".xMAP" extensions, are created automatically when you compile your applications (they're created by the mwld program). When you copy your application into a folder in the BeOS, be sure you copy the application's symbol file into the same folder.

Entering the Debugger

There are two ways to enter the debugger: You can fall into it, or force your way in.

Debugger Windows

When you enter the debugger, a new Terminal-like window appears. The title of the window will look something like this:

Team 40 signifies that the team that's being debugged is team 40. A team is the group of threads that belong to the same application (see the thread documentation in the Kernel Kit chapter of The Be Book if you need a more detailed description of teams). Debug 2 is simply an identifier for the window.

The team designation implies that the scope of the debugging process is teamwide. And so it is: Even though you may have invoked the debugger by telling it to attack a specific thread, the debug process that's running in a particular window has access to all the threads that belong to the designated team. You can switch between the threads in the team through debugger commands, as explained in a later section.

Each team that you debug is presented in its own window, and in only one window. If you separately invoke db on each of two threads that belong to the same team, the second invocation will "appear" in the window that was produced by the first invocation.

Using the Debugger

A debugger window displays, initially, the assembly code instruction to which the debugger is currently "pointing." The pointed-to instruction will not yet have been executed. (The format of the instruction display is described in the section "Instruction Display".)

Immediately below the instruction display is the debugger prompt. The prompt displays the name of the thread that you're debugging, followed by a colon. For example, if you're debugging MyApp's main thread, the prompt would look like this:

To this prompt you type commands that let you examine and manipulate your application. The section "The Commands" lists and describes all the debugger commands that are currently implemented.


Some debugger commands take arguments; typically, these arguments are address or data values. The following rules apply to the interpretation of the values that you pass to the debugger (in the following examples, the debugger prompt is shown as db:):

sets the program counter to the instruction located at the absolute address 0x800003b0.

Instruction Display

The output of commands that display instructions follows this format:

The ingredients are:

If the instruction's location isn't within 64 K of a recognizable symbol, the function: line is omitted, and the instruction's absolute address is given (in place of the +offset value).

The Commands

General Commands

Command Meaning
h Help; display the list of db commands.
cv value Convert value from decimal to hex, or from hex to decimal (as value does or doesn't have a prepended #).
a Repeat the previous command verbatim.
<Enter> Continue the previous command. (Exactly what "continuing" means depends on the command.)
es Exit to Shell; attempts to exit the current application (which can be perilous).
exit A synonym for es.

Displaying and Setting Memory, Registers, and Symbols

Command Meaning
dm address count Display count bytes of data starting at the given address.
sm address value Set the data at the given address to value.
db | dh | dw address Display address as a byte, half-word, or full-word.
sb | sh | sw address value Set address as the byte, half-word, or full-word given by value.
wh address Tell where address is (as an offset into a function or a portion of memory, for example).
regs Display the contents of the CPU registers.
set symbol value Set the value of symbol. You can use this command to create new symbols.
sd prefix Symbol dump; display the symbols whose names start with prefix (case insensitive).
svd Display all symbols, but in order of their values.
smd prefix Symbol method dump; display the symbols whose method names start with prefix.

Displaying Frames and Instructions

Command Meaning
sc Stack crawl; list the frames on the stack.
il address [ count ] List count instructions starting at address; count defaults to 5.
ip [ address ] List a page of instructions starting at address; the argument defaults to pc - 20.

Stepping and Breaking

Command Meaning
s Step one instruction.
so Step one instruction without entering a function call.
t Same as so.
g Go; continue without stopping until the program hits a breakpoint (or exits).
gt address Go to; continue until the instruction at address is met. (This creates a one-shot breakpoint.)
mr "Magic Return"; runs until returned from the saved return address in the current frame (usually the current function, unless it is a "leaf" routine with no stack frame).
br [ address ] Set a breakpoint at address. Without the argument, this displays all breakpoints.
cb address Clear the breakpoint at address.
cab Clear all breakpoints.

Accessing Other Threads in the Team

Command Meaning
ps Display information about the threads in this team.
nx Switch to the "next" suspended thread in the team.
stch Toggle the "stop-child" state. If child stopping is on, threads that are (subsequently) spawned by this thread are suspended at their first instruction. A spawned thread assumes the stop-child state of its parent.

[Next] [Prev] [TOC]

BeOS User's Guide, DR8.2 for Power Mac Edition, 1/16/97.

Copyright © 1997, Be, Inc. All rights reserved.

Please send corrections, suggestions, and comments to userdocs@be.com.