Development Layout

BeOS Release 3.0/3.1

---

For general release notes, see Developer Release Notes.

Contents

• File System Layout
  • PPC BFS vs. Intel BFS

• Header Files
  • BeBuild.h
  • The _IMPEXP_LIB Keyword

• Libraries
  • Linking a Kernel Driver

• Exporting Symbols
  • Add-ons

• Porting from PPC to Intel
  • Resource Conversion

---

File System Layout

---

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:

• beos contains most of the operating system: the kernel, the Tracker, the loadable libraries, and so on. You never touch anything in beos, nor do you add anything to it.

• develop contains header files and "linkable" libraries. You can add your own subdirectories to develop, just don't touch anything that's already there.

• home is where you put your own work. Note that the BeOS isn't multi-user yet; thus, home isn't divided into individual subdirectory accounts.

• apps and preferences contain the applications that are provided by Be. You shouldn't add anything to these directories.

• optional and demos contain images, sounds, source code, experimental drivers, and demonstration apps. Nothing in the system depends on anything in these directories.

• var contains temporary system files.

Although you can create your own /boot subdirectories, it's recommended that you put all your own work in subdirectories of /boot/home.

PPC BFS vs. Intel BFS

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.

---

Header Files

---

The layout and use of the Release 3 header files is similar to PR2: /boot/develop/headers is the master header file master directory. It contains four subdirectories:

• be contains the header files for Be's software kits.
• cpp contains headers for the Metrowerks Standard C++ Library.
• gnu contains GNU headers.
• posix contains headers for Be's POSIX implementation.

If you're developing a library that needs to install its own headers files, you may want to create your own subdirectory of /boot/develop/headers. Just don't put them in the Be-defined subdirectories listed above.

The BeIDE looks for system headers in the be, cpp, and posix subdirectories. If the BeIDE loses these settings, visit the Project/Access Paths portion of the Settings window and either reset to Factory Settings or add the paths yourself.

BeBuild.h

There's an important new header file in R3:

/boot/develop/headers/be/BeBuild.h.

This file throws a compiler switch that tells your apps to import the global symbols that are exported by the Be libraries. The file is included by default when you build your app: You don't need to explicitly include this file in your source code.

The _IMPEXP_LIB Keyword

Starting in Release 3, each global symbol that's defined in the Be headers is marked with the keyword...

_IMPEXP_LIB

...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();

The keyword works 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.

---

Libraries

---

• The "linkable" libraries are in CPU-specific subdirectories of /boot/develop/lib:
  /boot/develop/lib/x86
  /boot/develop/lib/ppc
• The "loadable" libraries are in /boot/beos/system/lib.

Distinguishing between linkable and loadable libraries makes build management easier--even on the PPC, where it isn't strictly necessary. In theory, you could replace the linkable libraries to create different versions of the same app (a PR2 version and a Release 3 version, for example).

As in PR2, the two fundamental libraries, libbe and libroot, are included by default by the BeIDE. To link against additional libraries, you have to add the linkable libraries to the project yourself--don't add the loadable libraries.

Linking a Kernel Driver

If you're building a kernel-loaded driver, you should remove the libroot.so library from your project, and add _KERNEL_.LIB and kitruntime_sta.a. The (minimally) complete driver library suite looks like this:

• glue-noinit.a
• init_term_dyn.o
• start_dyn.o
• libbe.so
• _KERNEL_.LIB
• kitruntime_sta.a

---

Exporting Symbols

---

If you're building a normal application or a static library, you don't have to export symbols. However, if you're developing a shared library you must explicitly export every global symbol in your library. We recommend you use the __declspec() macro to export your symbols. To export a symbol, you declare it thus...

__declspec(dllexport) type name

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 set for building your library (which would declare dllexport) and another set that the library client would use (which would declare dllimport). To unify the Be headers, the Be libraries use macros, defined in BeBuild.h, that throw the import/export switch. 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 (at Be), a private compiler directive defines _BUILDING_be to be non-zero, thus causing _IMPEXP_BE to export symbols. Before the headers are shipped, _BUILDING_be is set to zero so that _IMPEXP_BE imports symbols.

You may want to emulate this system by defining your own library macros:

• Add your own macro, analogous to _IMPEXP_BE, to one of your own "global" header files.

• Define your own compiler variable, analogous to _BUILDING_be.

• Set the variable to non-zero when you're building your library.

• Set the variable to zero when you publish your headers for use by library clients.

WARNING: 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

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.

---

Porting from PPC to Intel

---

• Project files are portable, but they need to be adjusted. In general, it's easier to create a new project (to which you add your old files) than it is to port an existing one. If you must port, note that the project's libraries, and the tools (that are listed in the Project/Target window) will be wrong. Remove the libraries and replace them with the linkable libraries as described in"Libraries", and swap the tools for the toolx86 version (for example, mwcc becomes mwccx86).

• Source code is portable. You shouldn't have to alter your source code.

• Header files are mostly portable. The headers that are local to an app are eminently portable. But if you're building a library, you'll have to fiddle with the header files in order to get your symbols properly exported, as described above.

• Resources need to be converted, as discussed immediately below.

Resource Conversion

To convert your PPC resources into Intel resources, you need two tools:

• rescvt_ppc is a PPC command line program. It reads the resources from a PPC executable App and writes them into the file App.res.

• rescvt_intel is an x86 program. It reads the App.res file and writes a new App.rsrc resource file that you can add to your BeIDE project.

Both programs live in /boot/beos/bin on their respective CDs: rescvt_intel is on the Intel BeOS CD, rescvt_ppc is on the PPC BeOS CD. You can also download the programs from the Be FTP site:

rescvt_ppc.zip
rescvt_intel.zip

To use the tools, follow these steps:

1. Make sure rescvt_ppc is in /boot/beos/bin on your PPC machine, and rescvt_intel is in /boot/beos/bin on your Intel machine

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.

3. Copy the App.res file to your Intel machine, putting it in your project directory.

4. On your Intel machine, run rescvt_intel on the App.res file.

   WARNING: 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 .

   
   
   
   

   ---

   
   
   BeOS Release 3

   
   

   ---

   
   Copyright © 1998 Be, Inc. All rights reserved.
   Last modified May 14, 1998.