2. Managing Projects



This chapter focuses on how to create BeOS applications, libraries, and shared libraries.


BeOS Project Overview

This section shows you how to create new application, library, and shared library projects for the BeOS. The procedure is the same regardless of what kind of project you want. The only difference between the project types is the project type and project settings.

Topics discussed in this section include:


Project Entry Point Settings

Use the information shown in Table 2.1 to specify a projects entry points in the Link Options settings panel.

Table 2.1 Project Entry Point settings

Entry Points
Initialization
Main
Termination
Application
_init_routine_
__start
_term_routine_
Library
_init_routine_
_term_routine_
Shared Library
_init_routine_
_term_routine_


Managing an Application Project

This section describes how to create, run, and debug an application that operates in the BeOS. The topics include:


Creating a New Application Project

The following procedure describes how to create a new application project.

1. Launch the BeIDE.

2. Choose New Project from the File menu.

CodeWarrior displays the New Project dialog box, as shown in Figure 2.1

Figure 2.1 New Project window


3. Choose a stationery project, or an empty project.

Twist down the C_C++ or Java disclosure triangles to select a stationery project, or click Empty Project to select a new project that contains no files. Click Create to continue.


NOTE:

For further information on stationery projects, and how to create custom stationery, see the topic "Creating a Project" in the Working with Projects chapter of the BeIDE User Guide.

4. Name your project, and click Save.

Inside the Save Project dialog, enter a project name, choose a directory to store it in, then click Save. The convention for naming a BeOS project is to use the extension .proj.

The Save dialog disappears and the New Project window is renamed with the new project name just entered.

Figure 2.2 Saved application project window




5. Set project options in the Settings dialog.

Choose Settings from the Window menu. The Apply To pop-up should already read Current Project. If not, choose it. See the BeIDE User Guide for more information on "Configuring IDE Options."

6. Click the Save button.

CodeWarrior saves your project settings.


Running an Application Project

To run an application project, choose Run from the Project menu. CodeWarrior compiles your files, and then begins execution of your program.


Debugging an Application Project

The following section describes how to set up a project so you can debug it under the Metrowerks Debugger.


To Setup a Project for Debugging

1. Choose Enable Debugger from the Project menu.

If CodeWarrior must change your project's settings it displays the dialog below.

Figure 2.3 Settings alert


When you click OK, CodeWarrior changes your project in these ways:

If no SYM Markers are turned on in your project window, CodeWarrior turns on the SYM markers for all files that it can debug at the source code level. If any SYM markers are turned on, CodeWarrior doesn't change the markers.

If you're debugging a PPC project, CodeWarrior turns on these options in the PPC Options settings panel:

Many optimizations change your binary code in such a way that the debugger cannot figure out which source code statements correspond to which binary code instructions. Generally, you'll want to turn off the optimizations so you can step through your source code more easily.

When you're creating a PPC project, turn off these optimizations in the Processor settings panel:

  • Peephole Optimization
  • Instruction Scheduling
  • Global Optimizer

  • Generating SYM Files

    The Metrowerks Debugger requires SYM (symbol) files. The rest of this section describes how to generate a SYM file and include source files in it.


    To Generate a SYM File

    1. In the Linker settings panel, turn on the Generate SYM File option.

    CodeWarrior will create a SYM file for your project the next time it makes your project.

    2. Turn on Use Full Path Names option.

    CodeWarrior puts the full pathname of the source file in the SYM file. Turning on this option is recommended. However, it slightly increases the size of your SYM file.


    Outputting Traceback Tables

    Traceback tables help other people debug your application or shared library if you do not distribute the source code. If the Emit Traceback Tables option in the Processor settings panel is on, the compiler generates an AIX-format traceback table for each function, which are placed in the executable code. The Metrowerks debuggers can use traceback tables.

    This option correspond to #pragma traceback. The factory setting for this option is off.


    Managing a Library Project

    This section describes how to create a library that operates in the BeOS. The topics include:


    Creating a New Library Project

    This section describes how to create a library project.

    1. Create an empty project.

    2. In the PPC Project settings panel, select Library from the Project Type menu.

    3. Enter a name for the library in the File name field.

    When CodeWarrior creates your library, it gives it the name specified in the File Name field.

    4. Click the Save button.

    CodeWarrior saves your project settings.


    Setting Library Project Options

    This section describes how to set the options in the library PPC Project settings panel (Figure 2.4).

    Figure 2.4 Library project settings



    Project Type

    Choose Library from the Project Type pop-up menu.


    File Name

    Enter the name in the File Name field. When CodeWarrior creates your library, it gives it the name specified in that field.


    NOTE:

    You can ignore the Creator fields when creating library projects. The Type field should automatically be set to BAPP.

    Managing a Shared Library Project

    This section describes how to create a shared library that operates in the BeOS. The topics include:


    Creating a New Shared Library Project

    This section describes how to create a shared library project.

    1. Create an empty project.

    2. In the PPC Project settings panel, select Shared Library from the Project Type menu.

    3. Enter a name for the shared library.

    When CodeWarrior creates your shared library, it gives it the name specified in the File Name field.

    4. Enter type of the shared library.

    When CodeWarrior creates your shared library, enter the 4-character type `NPLF' in the Type field.

    5. Save your changes.

    Click the Save button. CodeWarrior saves your project settings.


    Exporting Symbols

    When you create a shared library, you must specify which symbols to export; that is, specify which symbols can be used by other applications and libraries. CodeWarrior gives you several ways to do this:

    The Export Settings options are located in the PEF settings panel as shown in Figure 2.5.

    Figure 2.5 Shared Library PEF settings



    Exporting symbols with an .exp file

    1. In the PEF settings panel, select Use .exp file from the Export Symbols pop-up menu.

    2. Delete any export file that is already in your project's folder.

    CodeWarrior will not create a new export file if one already exists in your project's folder.

    3. Make your project.

    Choose Make from the Project menu.

    CodeWarrior creates an export file, which lists the names of all the global variables and routines in every one of your project's files. This file's name is your project's file name with .exp appended.

    4. Open the export file.

    Listing 2.1 shows a sample .exp file.


    Listing 2.1 Sample export file


    FindDominantDevice__8UWindowsFRC4Rect		# UWindows::FindDominantDevice(const Rect &)
    GetWindowStructureRect__8UWindowsFP8GrafPort		# UWindows::GetWindowStructureRect(GrafPort *)
    GetWindowContentRect__8UWindowsFP8GrafPort		# UWindows::GetWindowContentRect(GrafPort *)
    # __sinit
    # __local_destructor_chain
    # __global_destructor_chain
    # __dc_arr
    # __del_arr
    # __new_arr
    # __init_arr
    # __copy
    # __destroy_global_chain
    # __destroy_local_chain
    # __destroy_local_objects_to
    # __destroy_local_objects
    # __reregister_local_object
    # __preregister_local_object
    # __register_local_object
    # __register_global_object
    # __ptmf_cast

    5. Comment out any symbol you don't want to export.

    To comment out a symbol, put a # at the beginning of the line that contains it.

    6. Comment out any CodeWarrior runtime symbol.

    CodeWarrior runtime symbols begin with two underscores (__).

    If you do not comment these symbols, CodeWarrior may generate linker errors when you use this library in other projects.


    Exporting symbols from a shared library with a pragma

    1. In the PEF settings panel, select Use #pragma from the Export Symbols pop-up.

    2. In your source files, turn on the export pragma for all the routines you want to export.

    When the export pragma is on, CodeWarrior exports any function your declare or define. For example, this code exports DrawBear(), DrawCat(), DrawLizard(), and DrawAlligator(), but DrawMammal() and DrawReptile() are internal.


    #pragma export on
    OSErr DrawBear(void);
    OSErr DrawCat(void);
    OSErr DrawLizard(void);
    OSErr DrawAlligator(void);
    #pragma export off
    
    
    OSErr DrawMammal(void);
    OSErr DrawReptile(void);


    Exporting all symbols in shared library

    1. In the PEF settings panel, select All Globals from the Export Symbols pop-up.

    CodeWarrior exports all the global symbols in your project.


    To export no symbols in shared library

    2. In the PEF settings panel, select None from the Export Symbols pop-up.

    CodeWarrior exports no symbols in your project.


    Setting Shared Library Project Options

    This section describes how to set the options in the library PPC Project (Figure 2.6) and PEF settings (Figure 2.5) panels.


    PPC Project Settings

    Choose the type of library to create, give it a name, and set its type in the PPC Project settings panel.

    Figure 2.6 Shared Library project settings



    Project Type

    Choose Library from the Project Type pop-up menu.


    File Name

    Enter the name in the File Name field. When CodeWarrior creates your library, it gives it the name specified in that field.


    Type

    Enter the 4-letter type of NPLF in the Type field.


    PEF Settings

    Choose from the PEF settings panel (Figure 2.5) the Export Symbols pop-up menu how symbols will be exported from your shared library project.





    Visit the Metrowerks website at: http://www.metrowerks.com
    For assistance contact Metrowerks Technical Support at: support@metrowerks.com
    Copyright © 1998, Metrowerks Corp. All rights reserved.

    Last updated: February 15, 1998 * Chris Magnuson * John Roseborough