Issue 1-15, March 20, 1996

Be Engineering Insights: craw, shex, and script: Excuse Me?

By Steve Horowitz

On the BeBox, as on other platforms, developers are always looking for little tools that make their work easier or help to automate repetitive processes. craw, shex, and script are just these kinds of tools. They're not very complicated, they don't write your application for you, but they do help in small ways to make the application development process a little easier. A number of people have been asking about these tools, so this article explains what they are and how to use them.

craw, shex, and script live in the /bin folder on the BeBox. You can use them in the Terminal application, which provides the command line for the Be shell, bash. You can also use craw, shex, and script in shell scripts. Each of these tools has a completely different purpose, but when you combine them with each other or with other shell tools, they can be remarkably useful.

The craw tool converts 24-bit image files created on other systems to formats that are useful in Be applications. The shex tool is pretty simple: It's just an application that allows you to run a script file by double-clicking it. The script tool sends simple commands to Be applications, such as telling them to quit.

The Raw Image Converter: craw

The craw tool makes it easy to include images from other systems in your Be applications. It converts raw, 24-bit, RGB images to the 8-bit or 24-bit color formats Be applications can use.

Release 1.1d6 of the Be OS only supports 8-bit graphics (that is, images that include 8 bits of color information for each pixel, allowing up to 256 colors on the screen at one time). Release 1.1d7 will support both 8-bit and 24-bit graphics at multiple resolutions. In release 1.1d7, you set the bit depth you want with the Screen preferences application. (In fact, release 1.1d7 supports 32-bit graphics—24 bits of color information for each pixel, allowing millions of colors on the screen at one time, plus 8 bits of "transparency" information per pixel. However, working with transparency is beyond the scope of this article—and the current version of craw.)

If you're using release 1.1d6, craw only converts raw files to 8-bit format. But if you're using release 1.1d7, craw converts raw files to the same bit depth as the screen—8 or 24 bits per pixel, as set with the Screen application. You can use craw to save converted images as resources or as byte arrays. In either case, you can use the data in a call to BBitmap::SetBits() to create the image inside your Be application and to render it in a view.

To use craw you need a raw image in 24-bit, RGB, interleaved format. You can use the Macintosh version of Photoshop to save image files in this format. First, use Photoshop's Image Size command to make sure the width of the image, in pixels, is a multiple of 4. Then choose Save As, select the Raw format, name the file, and click OK. Finally, in the Raw Options dialog box, make sure the Interleaved Order option is checked and click OK again.

After transferring the image file to the BeBox (using ftp or tar), use the Screen application to make sure the screen is set to the bit depth you want craw to convert your image to (remember, the bit depth option in the Screen application is only available in release 1.1d7). Then start up the Terminal application and to convert, for example, an image file named MyImage that's 64 pixels wide by 40 pixels high, simply enter "craw 64 40 MyImage". craw creates a file named iconfile, which is a text file that contains an array of unsigned chars named after the file you converted. You can copy this array into your source code and use it as the source buffer when calling BBitmap::SetBits(). The call to SetBits() should use the char array as the source buffer followed by the size in bytes of the buffer. You can compute the size parameter by multiplying the width of your image (64 in our example) by the number of BYTES per pixel (1 BYTE for 8-bit color, 3 BYTES for 24-bit color) and multiplying the result by the height of the image (40 in our example). You then pass 0 as the offset parameter and set the color_space parameter according to the bit depth of the screen at the time the image was converted. The resulting bitmap can then be drawn in any BView.

Another option when using craw is to add the word "res" at the end when you invoke the tool (for example, "craw 64 40 MyImage res"). This creates a resource file named icon_res instead of the iconfile text file. You can use the listres tool to view the contents of this resource file, where you will find either PICT, ICON, or MICN resources. craw creates these three different types of resources simply based on the size of the raw image: ICON resources are created for images that are 32-by-32 pixels, MICN for images that are 16-by-16 pixels, and PICT for images that are any other size. You can then use the resource file API to read in these resources and set up bits in bitmaps just like the byte arrays. (Note that in release 1.1d6 of the Be OS, you can add only 1 resource of each type to the icon_res file. If you try to add more, craw reports an error. In release 1.1d7 you can add as many as you like. The text-based technique allows as many images as you like in both releases.)

I hope you'll find it's easy to use craw to dress up your Be applications.

The Shell Script Executer: shex

This tool is actually pretty simple and doesn't require any special knowledge. In fact it will probably go away in future releases of the Be OS when our shell (bash) incorporates its functionality. But for now this is the tool that becomes the "owner" of text files you create when you use the Edit application's "Convert to Script File" command. Once shex owns a script text file, you can simply double-click the script file to invoke bash and run the script. When you double-click a script file, shex also opens a status window that tells you the name of the shell script it's currently running. When you combine shex with the script tool, you can automate some of the more common and repetitive build procedures. I'll give you an example a little later.

The Script Command Sender: script

The script tool is a handy utility for sending script commands, in the form of BMessages, to running Be applications. For example, from the shell you can send a B_QUIT_REQUESTED message to a running application to tell the application to quit.

To control an application with the script tool, you create a text file in the /system/script folder that contains the commands you want to use to control that application. The text file must have the same name as the signature of the application you want to control. For example, to create a text file that contains commands for controlling the Magnify application, you'd name the file "MAGN". You can include any command in the file that the application will respond to, including standard system messages. The format of each command of the file is basically the typeable name of the command you want to send (such as "cmdQUIT"), followed by a single-quoted, four-character command constant (such as '_QRQ' for the B_QUIT_REQUESTED message). If you used the preceding example, you could make the Magnify application quit by simply typing "script MAGN cmdQUIT" in a Terminal window.

A sample file (in the /system/script folder) to control an application might contain the following commands:

cmdQUIT                 '_QRQ'
cmdSHOW_ABOUT_BOX       '_ABR'
cmdOPEN_UNTITLED        'ount'

Each of these commands can be sent directly to the BApplication object inside your application in the form of a BMessage, so any commands your application understands can be included in this scripting definition file. Note that the script tool is not a replacement for a full, powerful scripting system on the BeBox. It's just a simple tool for controlling applications in basic ways.

You can combine the script tool with double-clickable scripts to do some pretty handy things. For example, if you're using a Macintosh to develop a Be application, you can create a single double-clickable script file that quits your running application, uses ftp to get a new copy, and starts up the new copy. Here's how to make a script that does just that:

Assume your application's signature is 'asig' and assume your Macintosh has an IP address of XXX.XX.X.X. Your Macintosh must be running an ftp server, such as FTPd. Also assume your application is called "MyApp" and that it lives at the root of your BeBox's boot disk. Use Edit to create a text file that contains the following four lines, but don't include the comments—the ##s and the text that follows them in each line—and only include the chmod line if you're using release 1.1d7:

script asig cmdQUIT          ## quit your app
ftp XXX.XX.X.X  from_mac     ## get a new copy
chmod +x MyApp               ## make it executable in 1.1d7
/boot/MyApp &                ## run your app

Use Edit's "Convert to Script File" command to make the file a double-clickable script. In order for this script to work, of course, you have to have created your scripting control file, named "asig" in the /system/script folder, to control your app. The other thing this script relies on is a text file to feed ftp to make the transfer happen. This text file should be named "from_mac" and contain the following lines (again, don't include the comments):

Steve                     ## your ftp login name
password                  ## your password
cd "/HardDisk/folder"     ## the path to your app
lcd /                     ## put app at the BeBox root
bin                       ## use binary transfer mode
get MyApp                 ## get your app
get MyApp._rsc            ## necessary in 1.1d6 ONLY
get MyApp.xMAP            ## get it's debugging symbols
quit

Put this ftp helper file in the same folder as your double-clickable script file.

Once all these things are in place, you can simply double-click your script file to quit your application, bring over a new copy from the Macintosh, and start up the new copy.

This is just a small sample of what you can do by combining some simple Be tools. You could also use these tools to automate testing, to send commands to multiple applications running at the same time, and for many other purposes. I hope this article has given you a feel for some of the helpful BeBox tools that make application development a little easier. Better yet, perhaps these tools will help you create even more powerful tools as we all help to get this new platform off the ground and make developing on the BeBox a rewarding experience.


Be Developer Profile: Jim Menard

To be successful, most computing platforms aim to attract both "big guys" (see the Adobe Systems Developer Profile in the January 24, 1996, "Be Newsletter") and "little guys." But most often it's the "little guys" who bring innovation and breakthrough products to a platform. They're also the ones who provide solutions for vertical markets. Jim Menard, a Be developer and musician based in Boston, is a great example.

Jim is a one-person development shop whose been designing MIDI software and serving the music marketplace for over ten years. MIDI (Musical Instrument Digital Interface) is a standard for how musical instruments, computers, and other devices exchange music data. For example, using the common MIDI communications protocol, a performer can daisy-chain several synthesizers together in a way that makes it possible to create a "layering" of sounds (much like recording multiple tracks in a music studio), in real time in a live setting .

Jim's product, The KeyMaster, is real-time MIDI performance software. At the stomp of a footswitch during a performance (or any other MIDI event), it allows a performer to totally reconfigure his or her MIDI setup. A performer can split controlling keyboards, layer and transpose MIDI channels, send program changes and system-exclusive messages, limit controller and velocity values, and much more. The KeyMaster can also be used for MIDI studio control, lighting control, and other music/performance applications. The first incarnation of the product was on a Commodore 64, followed by a port to the Atari ST. Currently, Jim's porting it to the Macintosh, and plans to port it to the BeBox later this year.

Why is Menard targeting the Be platform? Like many early Macintosh developers, he says he isn't doing it to get rich quick (though he wouldn't be averse to the idea). While he definitely sees a business opportunity for the BeBox down the road, he's developing for it now because he "believes in Be's vision of the marketplace and its software distribution model." Not only that, but the BeBox's architecture boasts many capabilities that are especially appealing to him as a MIDI developer: Built-in MIDI hardware and real-time software support, audio, multitasking and multithreading, easy hooks into real-time sound manipulation, and simple inter- and intra-application communications, to name a few.

"I hope the BeBox becomes the next Macintosh," Menard says. "It's new, it's fun, and Be's done most everything the right way—including being responsive to developers' ideas." Jim is so excited about the BeBox he tells us he's working nights and weekends to bring The KeyMaster to the BeBox. After that? He's got lots of future product plans, including a MIDI sequencer and a MIDI librarian.

For more information on The KeyMaster, including a list of features and future directions, visit Jim's web site: http://www.io.com/~jimm/keymaster.html. Or send him e-mail at jimm@io.com.


PPCP, MLD/LERD, and Other Permutations

By Jean-Louis Gassée

I came in early this morning, straight from the school bus pick-up where I drop my son Paul around 7 am. As always, I was late writing this column and I wanted some time before the phone started ringing. I was going to write about PPCP (the PowerPC Platform), my hopes for it, some concerns too. That was before I read the story in the March 19 "San Francisco Chronicle" discussing the new Macintosh Licensing Design, MLD for short, also called LERD (Low End Reference Design) in other publications. This new licensing design sheds an entire new light on the future of PPCP or, as some critics are already pointing out, confirms their long-held suspicions that Apple wasn't as committed to PPCP (nee CHRP, itself nee PREP) as claimed earlier.

We'll discuss the PPCP theory, then implementation questions and implications of the MLD announcement. But first: Why do we care?

We care because a unified hardware platform propelled by Apple, Motorola, and to some degree IBM could reach critical mass, attract followers, cloners if you wish, suppliers, third-party hardware augmenters, developers and, at the beginning of the food chain, customers. Be, in turn, would have a stable, credible platform upon which to base a multiprocessor version of the BeBox. Also, the Be OS could run in single-processor mode on the millions of PPCP boxes out there. Be heaven.

In short, PPCP was designed to be the PC/AT of the PowerPC world. In the Wintel space, you buy spare parts, chipsets, processors, BIOS, and the like and you design your own clone. Differentiation is limited. In some cases it's only marketing, just like cigarettes. When you buy an Intel motherboard, a case and power supply, a Seagate drive, and a Mitsumi floppy, there isn't much room for difference. And you have a stable platform, one that runs many operating systems besides Windows and Windows NT. It'll run OS/2, Linux, and various expensive or free variants of UNIX. And I must be missing one or two interesting systems. There are glitches here and there, BIOS and other compatibility problems but, by and large, the market trusts the platform. And trust is the operative word.

With this in mind, how does the PPCP consortium create a self-fulfilling prophecy? How does the market get to trust that, yes, there is such a thing as a real PowerPC platform, and, as a result, an industry arises and creates a stable life form around the PowerPC? Before this morning, our concerns were of two kinds: Chips and human beings.

On the silicon side the vagueness of some technical specifications concerned us and we didn't quite like the dreaded "third-party opportunity" used to describe some support chips. In our business, "third-party opportunity" is a code word, now over-used and transparent. It refers to products the main player doesn't have the will, the money, or the brains to make. In a world where the other processor vendor also makes full chipsets and complete motherboards, I believe trust in the platform will be enhanced if the PowerPC suppliers also supply the complete set of building blocks. Mac ROMs are supposed to come from Apple and "third-party vendors," the chip with Apple-specific I/O, code-named Hydra, also from Apple, the processors from IBM and Motorola, one support chip from Motorola, and less noble I/O chips are the "third-party opportunities" already mentioned.

Turning to the human beings issue, with so many cooks, you always end up with politics, which isn't really a synonym for trust. And as Richard Brandt mentioned in this month's "Upside," in all these delicate standard-building activities (he was referring to HTML), you always run the risk of someone making a last-minute, conscious or unconscious, proprietary move. Imagine this: Your OS depends on a BIOS. And the BIOS supplier happens to be Microsoft, instead of independents such as Phoenix or AMI. How would you feel?

Now we hear there's yet another platform for the Mac OS: MLD or LERD. With the usual caveats, this is recent and perhaps incomplete information. PPCP is supposed to be a multi-OS platform. But it's deemed too expensive for the low end. The new MLD is a simpler platform, it will only run the MacOS. There is no disputing the merit of the least expensive Mac design possible. Several questions arise, however. First, what's this MacOS-only story? Perhaps a Be-biased question. Today, I can buy a PC/AT clone system with hard disk, monitor, and so on, for prices ranging from $700 to $7000 retail, more or less. They can all run Windows, Windows NT, and all the other operating systems mentioned earlier. Why can't the LERD run all manner of system software? What's there to gain by such a limitation? How trustworthy will it feel? It seems the LERD was born because the PPCP didn't scale down very well, perhaps a result of the Apple/Motorola/IBM politics driving the design process. If that's a correct assumption, then the viability of the PPCP platform is questionable. With IBM on the sidelines, offering no high-volume designs, the PowerPC camp is already divided. It can't afford more fragmentation. If the LERD is really a good, manufacturable design, cloners will take it, pervert it, augment it, and make it perform the unnatural acts that signify success in our industry. And if that includes running Windows NT on it, great—as long as there's only one reference platform, the necessary but not sufficient condition for a PowerPC industry to arise.

Creative Commons License
Legal Notice
This work is licensed under a Creative Commons Attribution-Non commercial-No Derivative Works 3.0 License.