http://www.be.com/documentation/BeOSUsersGuide/6_DevelopingApps/devapps.htm (Amiga Plus Extra No. 5/97, 05/1997)
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.
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.
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.
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".
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.
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):
app = HelloWorld
app = MyApplication
where MyApplication is, of course, the name of your application. (Notwithstanding the example set by HelloWorld, the name of the folder in which your code lives needn't match the name of your application.)
CPPOBJS = \
$(OBJ)/HelloView.o \
$(OBJ)/HelloWindow.o \
$(OBJ)/HelloWorld.o
Pay particular attention to the backslash characters. Neighboring lines must be separated by a backslash that immediately precedes the carriage return; the last line mustn't have a backslash:
CPPOBJS = \ $(OBJ)/MyApp.o \ $(OBJ)/MyWindow.o \ $(OBJ)/MyView.o \ $(OBJ)/MyOtherView.o \ $(OBJ)/MyMisc.o
$(OBJ)/HelloView.o: HelloView.cpp HelloView.h
$(CC) $(INCLUDES) $(CFLAGS) -o $@ -c HelloView.cpp
In general, you create an instruction of this form for each file that you place in the CPPOBJS section, substituting your file names for HelloWorld's. The first line lists the file's "dependencies": The file to the left of the colon depends on the files that are listed (on that same line) to the right of the colon. For example, if HelloView.h changes, HelloView.o will be automatically regenerated the next time you build the application.
You can list any number of dependencies. You don't need to match the object file's name. For example, let's say you have a header file (we'll call it misc.h) that all of the source files in your application look at. You would add the file to the list of dependencies for each of the source file entries:
$(OBJ)/MyApp.o: MyApp.cpp MyApp.h misc.h $(CC) $(INCLUDES) $(CFLAGS) -o $@ -c MyApp.cpp
The second line in the entry is (usually) a list of compiler instructions.
After you've edited the makefile, you're ready to build your application.
To build an application, you start the Terminal application, cd to the folder where your application lives, and enter make:
cd MyAppDir make -map MyApp.xMAP
The make program reads the makefile, then invokes the compiler (mwcc) and linker (mwld) according to the instructions that it finds there.
make clean
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".
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.
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).
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.
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.
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.
Once you've set up the nub in the BeOS, you can set up the cross-debugger on the Macintosh.
The cross-debugger is in the same folder as the IDE, if you followed the instructions in Installing the BeOS.
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.
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.
Creating resources and resource files is described in "Creating Resources for a Be Application".
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.
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.
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."
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.
The cross-debugger starts the application in the BeOS, and the message in the MetroNub window changes from "Connected" to "Debugging."
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.
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".
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.
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:
To make sure the signature is unique, contact the Be Developer Support group (DevSupport@be.com). You will soon be able to register your resources on the Be Web site: http://www.be.com.
For documentation on launch behaviors and the other flags, refer to "Application Information" in the "Application Kit" chapter of The Be Book.
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.
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.
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.
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.
You add resources to an application in one of three ways:
copyres resourcefile application
to copy the resources in resourcefile into the application file (replacing any existing resources).
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.
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.
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.
There are two ways to enter the debugger: You can fall into it, or force your way in.
$ db MyApp
If MyApp is already running (and is a single-launch-only application), the debugger will "attach to" the running application. Otherwise, db causes a new image of the application to be launched and then takes over.
The argument to db can also be a thread identifier. For example, let's say MyApp is running and the ID of its main thread is 87 (information that you got from running ps). To attach to the thread, we invoke db thus:
$ db 87
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.
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:
MyApp:
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:):
db: pc = 800003b0
db: `abc
finds the symbol abc, not the number 0xabc.
db: il 80000248 #4 ... db: il . #8 ... db: il . #16 ...
displays, successively, four, eight, and sixteen instructions starting at address 0x80000248.
The output of commands that display instructions follows this format:
function: +offset: hexDump op arg1, arg2, ..., argN
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).
Displaying and Setting Memory, Registers, and Symbols
Displaying Frames and Instructions
Accessing Other Threads in the Team
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.
