# Development Layout for BeOS Release 3 for Intel

This document describes how the BeOS R3 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:

#### General File System Layout

####

- PPC BFS vs. Intel BFS

#### Header Files

- BeBuild.h
- The _IMPEXP_LIB Keyword
- Removed and Ignorable Headers

#### Libraries

#### Tools

- Resource Conversion
- Using the BeIDE
- Porting a Project
- Building a Simple App: HelloWorld
- Project Libraries
- Building a Library
- Building an Add-on
- Building a Driver

## General 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, and demonstration apps.

- var contains temporary system files.

You can create your own /boot subdirectories, although 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 header files is similar to PR2; to wit:

- /boot/develop/headers is the "master" header file directory. It contains four subdirectories:

  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.

- Currently, we don't have a policy regarding where third-party headers should go. If you're developing a library that needs to install its own headers files, you may want to install them in your own subdirectory of /boot/develop/headers. Just don't put them in the Be-defined subdirectories listed above.

- By default, the Metrowerks' BeIDE looks for system headers in the be, cpp, and posix subdirectories. If the BeIDE somehow 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

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.

### Removed and Ignorable Headers

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

- media/AVIModule.h, AudioModule.h, VideoModule.h, and MediaModule.h. The Media Kit is undergoing architectural changes; the "Module" header files have been removed in anticipation of the new organization.

- media/VideoDefs.h. This file is part of the new Media Kit architecture. Ignore it for now.

## Libraries

In the Intel world, you link against one set of libraries and load another:

- The "linkable" libraries are in /boot/develop/lib/x86 and have ".LIB" extensions; libbe.so.LIB, for example. The directory also contains some files that you may not be familiar with:

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

- The "loadable" libraries are in /boot/beos/system/lib. They don't use an additional extension: libbe.so, for example. When you run an app, these libraries are automatically found and loaded.

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

## Tools

The tools that are provided (or not) are:

- BeIDE. Metrowerks has ported the BeIDE to Intel, so project development can be done natively.

- Command line compilation. You can also compile from the command line. The compiler and linker for Intel are called `mwccx86` and `mwldx86`.

- Debugger. The Metrowerks Debugger hasn't been ported yet; for now, you can use the command line debugger (`db`) provided by Be. The Intel version of `db` is essentially the same as the PPC version.

- Disassembler. You can disassemble code from the `BeIDE` by choosing the Project/Disassemble menu item, or, on the command line, by using...

  $ 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.

- Resource conversion. If you're making an app from scratch, you can create and add icons through IconWorld and add file types through FileTypes, as usual. But if you're porting an existing PPC app, you'll want to import your icons, file types, and other resources from the PPC executable. The `rescvt_ppc` and `rescvt_intel` programs let you do this.

  The resource conversion tools and the BeIDE are described in the following sections.

### Resource Conversion

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

- `rescvt_ppc` is 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 Intel 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. 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 .

### Using the BeIDE

The following sections tell you...

- How to port your PPC projects.
- How to build a simple application.
- How to build a shared library.
- How to build a driver.

#### Porting a Project

You've got a project on the PPC. You want to move it to Intel. Here's what works and what doesn't:

- 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 all be wrong. Replace the libraries with those listed in "Project 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. This is discussed in "Building a LIbrary", below.

- Resources need to be converted, as discussed in the section immediately above.

#### Building a Simple App: HelloWorld

R3 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.

#### Project Libraries

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:

- glue-noinit.a
- init_term_dyn.o
- start_dyn.o
- libbe.so.LIB
- libroot.so.LIB

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

#### Building a Library

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.

#### Building an Add-on

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.

#### Building a Driver

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:

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

BeOS Release 3

Copyright © 1998 Be, Inc. All rights reserved.

Last modified February 20, 1998.