Starting a debugging session

This section first discusses preparing a program for debugging and then steps you through starting a debugging session.

Examples used in this section

This chapter uses as an example the UFO program that is included on the Portfolio CD-ROM in the /remote folder. You can follow the instructions on a Macintosh that's connected to a 3DO Station. All files used in the example here are provided on the installation CD-ROM or are easy to create.

Preparing for launch

Preparing for launch involves the following steps, discussed in this section:

Preparing the makefile
Setting up the folder structure
Using an spt script file to set source directories

Preparing the makefile

The easiest way to create a makefile with the right settings is to use the Create3DOMake tool available via the 3DO menu in MPW.

If you decide to use your own makefile, pay attention to the following requirements:

Compile with the -g flag and link with the -debug flag.
Use the modbin command with the -debug option to properly configure the final executable.
Use the stripaif command to create a separate symbols file.
Include in your makefile-after the stripaif command-a duplicate command that duplicates the following files to the /remote folder:

the executable (for example, UFO)
the symbol file (for example, UFO.sym)

Setting up the folder structure

To facilitate debugging, use the following folder structure:

The 3DO boot script file (3DOBootNTSC.scr or 3DOBootPAL.scr) should be in the same folder as the /remote folder. This is the default setup.
All data and source code should be in one folder (which may contain subfolders). This folder can reside anywhere on your hard disk.

Using an spt script file to set source directories

When the Debugger starts, it looks for a preferences file and for script files. TWo script files are currently recognized:

The .spt script file is created by the user.
The .scr boot script file is included in the system.

You can set the source directory either for one program only or for several programs the following way:
To set the source directory for a specific program, create a file name executable.spt (for example, UFO.spt) in which you specify the source directories.
```
setsourcedir
    setsourcedir PubsStation:3DO:Examples:UFO:
    setsourcedir PubsStation:3DO:Examples:Lib3DO.lib:
```
To set the source directory globally, include the following command in the 3DO boot script (.scr) file. It's a good idea to clear all source directories first by using setsourcedir with the NULL string:
```
setsourcedir
    setsourcedir dirname
```

Note: Don't make any other changes to the 3DO boot script (.scr) file. They can cause problems with the encryption process.

Starting the Debugger

After you have installed all software, turn on the Macintosh, the 3DO Station, and the TV monitor, and go through the following steps:

Make sure your station is set up for debugging:

If you have an older "Green" Station, make sure the Debug switch on the 3DO Station is in the UP position.
If you have a newer, International Station, you should be set up for debugging by default. If not, use the ROM pop-up in the Preferences dialog, as described in Preferences dialog pop-ups.
Double-click on the 3DODebug icon in the 3DO_OS:version folder.

You are prompted for a script to execute.
Select the 3DO boot script file, which should reside in the same folder as the Debugger.

The Debugger starts up the 3DO Station and downloads and launches the operating system. A number of messages appear, followed by a Debugger prompt.
You can now start using the Debugger to download your programs.