This document describes how the BeOS Release 3 development world for Intel is layed out: Where libraries and header files are located, which libraries you need, what tools you need to build an application, and so on. Note that the discussions here are specifically for developing BeOS apps on Intel platforms. This document will be updated soon to describe the differences between PPC and Intel development (such differences should be few and minor).
The following topics are discussed:
At the highest level of the directory structure, nothing has changed. The /boot directory is at the root of the Be file system and contains the eight "real" (nonvirtual) subdirectories that you're already familiar with:
You can create your own /boot subdirectories, although it's recommended that you put all your own work in subdirectories of /boot/home.
Currently, the Intel version of the Be file system (bfs) is not compatible with the PPC bfs (endian trouble). This means, as an annoying example, that your Intel machine will not be able to read a floppy that was initialized on a PPC machine (and vice versa). If you want to use a floppy to transfer data between Intel and PPC, use tar.
The bfs incompatibility doesn't affect ftp: Files that are transferred through ftp will be properly converted.
The layout and use of the header files is similar to PR2; to wit:
be contains the header files for Be's software kits.
cpp contains headers for the Metrowerks Standard Library.
gnu contains a couple of GNU headers.
posix contains headers for Be's POSIX implementation.
There's an important new header file in Release 3:
You'll also notice that each global symbol that's defined in the Be headers is marked with a _IMPEXP_LIB keyword, where LIB is the Be library in which the symbol is defined. For example (from storage/FilePanel.h):
/* These are defined in libtracker.so. */
extern _IMPEXP_TRACKER void run_open_panel();
extern _IMPEXP_TRACKER void run_save_panel();
These keywords work in conjunction with the switch that's thrown by BeBuild.h. We'll return to the _IMPEXP_LIB business when we describe how to build a shared library.
Within /boot/develop/headers/be, the following directories and files have either been removed or should have been (if you find them on your CD, ignore them):
In the Intel world, you link against one set of libraries and load another:
- glue-noinit.a, init_term_dyn.o, and start_dyn.o contain dynamic linking glue.
- _KERNEL_.lib and kitruntime_sta.a are used by device drivers.
As in PR2, the two fundamental libraries, libbe and libroot, are included by default (when you use the BeIDE). To link against additional libraries, you have to add the libraries to your project yourself. But remember, the linkable libraries are in /boot/develop/lib/x86. For example, if you want to link against the Tracker library, you would add /boot/develop/lib/x86/libtracker.so.LIB to your project. (We'll speak more about the BeIDE, libraries, and projects in the next section.)
The tools that are provided (or not) are:
$ mwccx86 -machinecodelist ...
See the Metrowerks documentation for details
You can also dump symbols and code by running your app inside the Be debugger (db). Type 'help' for assistance.
The resource conversion tools and the BeIDE are described in the following sections.
To convert your PPC resources into Intel resources, you need two tools:
Both programs live in /boot/beos/bin. To use them, follow these steps:
1. Copy rescvt_ppc to your PPC machine; for convenience, put it in /boot/beos/bin:
/* ftp from intel to ppc */
beos_intel$ ftp my_mac
/* login business here */
...
ftp> lcd /boot/beos/bin
ftp> cd /boot/beos/bin
ftp> put rescvt_ppc
ftp> /* don't quit yet... */
2. On your PPC machine, run rescvt_ppc on the application executable that you want to convert. The program will list the app's resources (on standard out) and create an App.res file. For example, here we convert Pulse's resources:
beos_ppc$ cd /boot/beos/apps
beos_ppc$ rescvt_ppc Pulse
Pulse:
type APPV, id 1, size 680, name BEOS:APP_VERSION
TYPE UNKNOWN!
type APPF, id 1, size 4, name BEOS:APP_FLAGS
type MIMS, id 1, size 26, name BEOS:APP_SIG
type MIMS, id 2, size 28, name BEOS:TYPE
type MICN, id 101, size 256, name BEOS:M:STD_ICON
type ICON, id 101, size 1024, name BEOS:L:STD_ICON
beos_ppc$
3. Copy the App.res file to your Intel machine, putting it in your project directory. Here we put Pulse.res in the apps directory (for lack of a project directory):
/* continuing our previous ftp session (i.e. intel->ppc) */
ftp> lcd /boot/beos/apps
ftp> cd /boot/beos/apps
ftp> get Pulse.res
ftp> quit
4. On your Intel machine, run rescvt_intel on the App.res file. Here we convert the Pulse resources and create the file Pulse.rsrc:
intel_ppc$ cd /boot/beos/apps
intel_ppc$ rescvt_intel Pulse.res
$ rescvt2 Pulse.res
file Pulse.res
type APPV, id 1, size 680, name BEOS:APP_VERSION
type APPF, id 1, size 4, name BEOS:APP_FLAGS
type MIMS, id 1, size 26, name BEOS:APP_SIG
type MIMS, id 2, size 28, name BEOS:TYPE
type MICN, id 101, size 256, name BEOS:M:STD_ICON
type ICON, id 101, size 1024, name BEOS:L:STD_ICON
|
rescvt_intel will crash your system if you pass it an executable. You must only pass in App.res files. |
5. Add the App.rsrc file to your Intel BeIDE project.
If you've followed these instructions correctly, the resources will be automatically added to your executable the next time you build your project .
The following sections tell you...
You've got a project on the PPC. You want to move it to Intel. Here's what works and what doesn't:
Release 3 includes an example HelloWorld project in the directory /boot/apps/Metrowerks/HelloWorld_x86. This is a sample application, not a library; if you're building a new application, you should copy HelloWorld.proj to your own project directory and modify it appropriately. If you're building a library, skip to the "Building a Library" section.
When you open the HelloWorld project window, you'll notice that the libraries are not the same as in the PPC version. These libraries all live in /boot/develop/lib/x86:
(The first three are needed to support dynamic linking.)
As mentioned earlier, the Intel version of BeOS uses two sets of libraries: One set to link against, and the other set to load. A "linkable" library is indicated by the ".LIB" extension, as shown in the list above, and lives in the /boot/develop/lib/x86 directory. libbe and libroot are included by default; if you need to link against others, you add the Be libraries that are in /boot/develop/lib/x86, not the ones in /boot/beos/system/lib.
If you're building a static library (a library against which apps can statically link), then there's nothing new in the Intel world for you. However, if you're developing a shared library you should explicitly export every global symbol in your library by using the __declspec() macro. To export a symbol, you declare it thus...
__declspec(dllexport) type name
...where "_declspec(dllexport)" is literal, and type and name declare the symbol. Some examples:
__declspec(dllexport) char *some_name;
__declspec(dllexport) void some_func() {...}
__declspec(dllexport) class MyView {...}
To import these symbols, an app that wants to use your library must "reverse" the declaration by replacing dllexport with dllimport:
__declspec(dllimport) char *some_name;
__declspec(dllimport) void some_func();
__declspec(dllimport) class MyView;
The trouble with this system is that it implies two sets of headers, one for exporting (for building your library) and another for importing (that the library client would use). The Be libraries use macros, defined in BeBuild.h, that throw the import/export switch so the header files can be unified. For example, here's the macro for libbe:
#if _BUILDING_be
#define _IMPEXP_BE __declspec(dllexport)
#else
#define _IMPEXP_BE __declspec(dllimport)
#endif
When libbe is being built, a private compiler directive defines _BUILDING_be to be non-zero, and _IMPEXP_BE exports symbols. When a developer includes BeBuild.h, the _BUILDING_be variable is set to zero, so _IMPEXP_BE is set to import symbols.
You may want to emulate this system by defining your own library macros. This implies that you have to define a compiler switch (analogous to _BUILDING_be) yourself. Set the switch to non-zero when you're building your library, and then set it to zero when you publish your headers for use by library clients.
|
The use of #pragma to export symbols, while supported, is discouraged. The __declspec method may be clunky, but it's the standard in the PC world. |
Add-ons are, in general, exactly like shared libraries. However, since the symbols in an add-on are imported programmatically (through get_image_symbol()), you don't have to use the __declspec() business when loading an add-on. But you do have to __declspec(dllexport) the symbols when you're building your add-on.
If you're building a driver, you should remove the libroot.so.LIB library from your project, and add _KERNEL_.LIB and kitruntime_sta.a. The (minimally) complete driver library suite looks like this:
BeOS Release 3
Copyright © 1998 Be, Inc. All rights reserved.
Last modified February 20, 1998.