2.0 A Roadmap to the CodeBuilder CD

2.1 Installing CodeBuilder
2.1.1 Optional Installations
2.2 Exploring the CD Folders
2.2.1 Documentation
2.2.1.1 CodeBuilder UNIX Docs
2.2.1.2 HTML
2.2.2 Utilities
2.3 Performance Tuning - Optimizing CodeBuilder
2.3.1 System Optimization Guidelines
2.3.2 How Can You Tell When a System is Approaching Its Limits?
2.4 Reinstallation
2.4.1 Reconfiguration
2.4.1.1 Automated Reconfiguration
2.4.2 Accessing CodeBulder Source Files Directly From the CD-ROM
2.5 Troubleshooting

2.0 A Roadmap to the CodeBuilder CD

The entire CodeBuilder system is contained on a single CD-ROM in Macintosh HFS format.
This is the CodeBuilder installer. Run this application to install CodeBuilder on your computer. You will need a minimum of 140 MBytes of free space to install CodeBuilder.
This folder contains the bulk of CodeBuilder documentation. This documentation is available in a variety of formats including HTML, PDF, and PostScript. Some additional documentation is available from within CodeBuilder.
This text file provides an overview of CodeBuilder.
The source code distributed with CodeBuilder is stored in the Fast File System format. To view these sources, this fast file system must be mounted within CodeBuilder. (See 2.4.2 Accessing CodeBuilder Source Files Directly)
This folder contains a number of useful utilities, (e.g. debuggers and text editors) from Tenon and others.

2.1 Installing CodeBuilder

Follow the steps below to install the complete CodeBuilder software package.

Step 1 - Installing the CodeBuilder Software on Your Hard Disk
Insert the CodeBuilder CD-ROM and double-click on the disk icon. The disk will show an open window as illustrated below.

Figure 4: CodeBuilder CD-ROM Contents

Launch the CodeBuilder Installer application on the CD and select the drive on which to install. In some cases, it may be necessary to disable extensions not required for CD access. You may also copy the installer to your hard drive and then restart MacOS while holding down the shift key to disable all extensions.
The Installer application will create a folder named Code Builder v1.0. CodeBuilder requires approximately 150 MBytes of free disk space.

An optional X window server and X client development environment may be installed by using the Custom Install option. This optional package requires an additional 60 MBytes of disk space. You may install it along with CodeBuilder Basics, or separately at a later time (see 2.1.1 Optional Installations). CodeBuilder's AfterStep desktop environment requires the installation of the optional X Window software.
Configure the CodeBuilder Control Panel according to the instructions in section "3.0 The CodeBuilder Control Panel".


Step 2 - Launch CodeBuilder
Launch CodeBuilder by clicking on the CodeBuilder application in the CodeBuilder v1.0 folder. You may make an alias to this application and put it on the desktop for easier launching. If your system does not successfully start up and present you with the login: prompt after a moment, contact Tenon Technical Support.

Figure 5: CodeBuilder Folder

A CodeBuilder Console Window will appear with system configuration information taken from the CodeBuilder Control Panel.

Your CodeBuilder system is now ready to use. Please read section "4.1 The CodeBuilder Login Console" for information on how to log in. Refer to the following sections for additional set-up procedures: "3.0 The CodeBuilder Control Panel", "5.6.5 The Root Password" and "5.6.6 Setting Up User Accounts".
IMPORTANT: In the same manner that successfully booting and running the Macintosh OS is dependent on the System Folder and some very specifically named files and folders in the System Folder, CodeBuilder is dependent on its file system hierarchy, including the names, locations and permissions of its files.

Unless you are fully aware of CodeBuilder's dependency on its file system organization and the read/write ability of the contained files, DO NOT reorganize the CodeBuilder distribution hierarchy.

Be very careful when imposing Macintosh restrictions on the CodeBuilder folders and files. This includes locking or assigning File Sharing privileges to any CodeBuilder file or folder.

Figure 6: CodeBuilder Console Window

2.1.1 Optional Installations

The X window software component is optional and may be installed at any time after CodeBuilder has been installed. CodeBuilder should not be running at the time this package is installed.
Double click on the CodeBuilder v1.0 Installer on the CD. Select Custom Install. Check the X11R6 check box. Select the disk on which your have previously installed CodeBuilder.

2.2 Exploring the CD Folders


2.2.1 Documentation

CodeBuilder UNIX Docs
This folder contains a number of supplementary papers from the BSD Release.

CodeBuilder_User_Guide.html
This folder contains the CodeBuilder User's Guide in HTML format.

CodeBuilder_User_Guide.pdf
This PDF file is a printable version of the CodeBuilder User's Guide.

GNAT PostScript Docs
This folder contains PostScript versions of GNAT documentation.

HTML
This folder contains the HTML formatted documentation.

Man Pages
This alias points to the actual folder which contains HTML formatted man pages.

Objective_C-Overview.pdf
This file contains an overview of Objective C in PDF format.

Printable Man Pages
This folder contains PostScript versions of man pages.


2.2.2.1 CodeBuilder UNIX Docs

Programmer's Docs (psd)
This folder contains PDF copies of several papers from the Programmer's Supplementary Documents, which is part of the BSD release.

SysAdmin's Docs (smm)
This folder contains PDF copies of several papers from the System Manager's Manual, which is part of the BSD release.

User's Docs (usd)
This folder contains PDF copies of several papers from the User's Supplementary Documents, which is part of the BSD release.


2.2.1.2 HTML

GNAT
This folder contains information on how to program in Ada, how to use the GNAT tools, and why Ada is such a useful language.

GNU_dev_tools
This folder contains information on the GNU development tools such as gcc.

Lovelace
This folder contains Lovelace, an Ada tutorial, developed by David A. Wheeler.

Man Pages
This folder contains HTML formatted man pages.

Other_Stuff
This folder contains HTML documentation for miscellaneous other GNU utilities that are not specifically oriented towards programming such as emacs.


2.2.2 Utilities

Index.html
This HTML file gives an overview of the contents of the Utilities folder.

Debuggers
This folder contains Apple's MacsBug 6.5.3 and Macintosh Debugger 2.0, as well as information on obtaining The Debugger (also known as Jasik).

Development Utilities
This folder contains the Ada 95 Mac Application Framework (AMAF), libraries and include files from ETO #22, and Apple's resource editor ResEdit 2.1.3.

Fast File Utilities
This folder contains tools to aid correcting file system problems. Fast File First Aid is the CodeBuilder fsck utility built as a Macintosh application, and configured to perform an interactive file system check and repair operation. It may be used to correct file system corruption which prevents CodeBuilder from booting up. The Recovery folder contains a special minimal version of CodeBuilder for use when file system corruption has affected key programs or support files. In the unlikely event that file corruption occurs, drag the Recovery folder onto a hard drive and launch the CodeBuilder.emerg application. This will allow you to access your file systems from within a working CodeBuilder environment and take appropriate actions.

Mac_Perl_510r2_appl
This application installs Mac Perl. CodeBuilder also includes the UNIX version of Perl.

Text Utilities
This folder contains the Alpha, AdobeAcrobat, and BBEdit Lite 4.0 text editing and presentation applications. It also contains Unix <-> Text, an application for converting the end-of-line characters in a text file between standard Macintosh and Unix conventions. Alpha is shareware and is not registered, so if you use it, please register it.

2.3 Performance Tuning - Optimizing CodeBuilder

You can optimize CodeBuilder performance by tailoring your system to fit your particular hardware configuration and software service needs. MachTen CodeBuilder includes a native fast file system (FFS). This FFS not only significantly improves CodeBuilder's performance but also removes the Macintosh file system size and file name length limitations. CodeBuilder performance can be dramatically improved by giving some attention to the following configuration options.
The efficiency of the disk device driver plays an important role in the overall performance of the system. Choosing a fast disk and disk driver and adhering to the guidelines of disk optimizing tools will improve the CodeBuilder system's performance.
Setting the disk cache in the MacOS Memory Control Panel is essential to getting the most performance from your Macintosh. MacOS file manipulation software operates much more efficiently when disk caching is enabled and set to a large value. In some cases, the larger the value the better. A disk cache size of 512K is recommended; improved performance gains under CodeBuilder tend to diminish beyond this size. Larger cache sizes increase the chance of file corruption after an improper shutdown.
Disable the file sharing option located in the Sharing Setup Control Panel.
Do not keep the CodeBuilder scheduling priority slide bar or any Control Panel on the desktop. An open Control Panel consumes valuable CPU cycles. (Refer to section "3.0 The CodeBuilder Control Panel" for more information on using the Slide Bar.)
When running CodeBuilder in the default configuration, the following directories are searched (in the order listed) when a CodeBuilder command is executed:

.
~/bin
/usr/bin
/bin
/usr/X11/bin
/usr/libexec
"." refers to the directory the user is currently in and "~/bin" refers to the bin directory that is in the user's home directory. Adjust your search path in the .login or .profile file in your home directory.
Increase the number of UNIX file system buffers (FS buffers) in the CodeBuilder Memory Control Panel. Increasing the number of buffers to 32 or 64 can significantly improve performance by increasing the frequency of file system cache hits.

2.3.1 System Optimization Guidelines


The System Optimization Guidelines Table which follows will help you customize CodeBuilder. A little system attention will go a long way to give you a smoothly running system.

It is important to remember that CodeBuilder relies solely on physical memory. However, if you monitor your system resources and are careful not to overload your system with unneeded daemons, you will have good results with CodeBuilder, even on small memory machines.

Table 1: System Optimization Guidelines

Disk Space Limitations

A system with 200MB or less of hard disk will probably require careful attention to "tidiness" of the available disk space.

 By default, the /etc/rc file will preserve the editor files, and then automatically remove files in /tmp on each restart. (Note that subdirectories in /tmp are not purged.)

A cron(8)Ý entry may be created to purge old 'preserved' editor files from /var/preserve.

Use df(1) to determine the capacity and available space of each mounted file system.

Memory Space Limitations

Since CodeBuilder does not support paging or swap processes from memory to disk, all of the processes (blocked, sleeping and running) consume real memory. When the memory is filled up, no new processes can be started. Process instantiation (execve(2)) will fail with an ENOMEM (Error: not enough memory).
 Run only the daemon processes that are needed. If you do not need the services provided by a daemon, you can disable it via rc.conf(5) (see opposite).

Use ps(1) to find out how much memory each process is consuming.

If available memory is filled, terminate unwanted processes with kill(1). This will free up the memory those processes were consuming.

Keep the maximum memory that you are consuming below a high water mark to avoid memory fragmentation problems. (The probability of memory fragmentation increases as the percentage of free space decreases.)

syslogd

 This is the system logger daemon. Syslogd reads and forwards system messages to the specified log files and, depending on the priority of the message and the originating facility. A major reason for running this daemon is to log the results of lpd activities. Run syslogd while changing system configuration files for other daemons, or when running lpd, but not otherwise.

wind

The default .profile and .login files provided automatically start up the window daemon each time a login occurs in the console. Note that the window daemon is started with an

exec /usr/libexec/wind

to free up the space of the invoking call.
 Wind(8) is the window daemon controlling the CodeBuilder window environment. It is not necessary to use the window daemon since CodeBuilder also supports a simple console device. However, the added value of the window environment is almost always worth the extra memory it consumes.

lpd

 The printing service is provided by lpd(8). Systems that do not require printing services need not run this daemon. CodeBuilder will automatically start this daemon when a print command is invoked.

Ý: Throughout this manual, you will see commands and utilities followed by a number in parentheses. This number refers to the section of the man pages where more information can be found. To access the correct man page, type: man # command, where # is the number in parentheses. For example, to find out more information on cron(8), type: man 8 cron.

2.3.2 How Can You Tell When a System is Approaching Its Limits?

A system that is running near full memory capacity will begin to slow down. Output to the console (or any of the windows) may be noticeably slower. Programs which request more memory may fail or simply block and wait until memory is available. The C shell will return "Not enough memory" when attempting to invoke a new program.

2.4 Reinstallation

Occasionally you may want to reinstall CodeBuilder. Your current system may become damaged, or you may need to install a system upgrade. Perform the following steps before reinstalling CodeBuilder.

Step 1 - Preserve Personalized Files and Files That Have Been Changed
If you haven't done so already, create a fast file system to preserve changed or locally created files that reside on the root file system (CodeBuilder_FFS). Also preserve any files changed underneath the CodeBuilder_HFS folder. A fast file system within a file is usually the most convenient; see section "6.9.1.1 Creating an FFS Within a File" for details. This file system should be sized large enough to preserve the files and directories identified below. The tar command is probably the best choice for copying files, as it will preserve user, group, modes, and time stamps.
Copy private user files in the /home directory that reside in the root file system (CodeBuilder_FFS). Note that the .cshrc, .login, .mailrc and .profile files for the root account (/home/root) may be updated in subsequent releases.
Copy any configuration files you have changed in /etc. This includes fstab, group and master.passwd. It may be best to save all of /etc and review the files after installation is complete.
Copy any other files you have changed in /bin, /dev, /sbin, or /usr.
Visit the var folder and determine whether or not to preserve the administrative log files, print requests and accounting files contained in the following sub-folders adm, log, spool, tmp and preserve. If in doubt, preserve the file(s) and take a closer look after the installation is complete.
Step 2 - Install the New CodeBuilder System

Step 3 - Restore the Control Panel Settings
Before launching CodeBuilder, open the CodeBuilder Control Panel and visit each configuration screen. Verify that your installation parameters are correct. Press the "Save" button, even if no changes were made.
Step 4 - Launch CodeBuilder by Opening the CodeBuilder Application

Step 5 - Restore the Remaining Saved Configuration Files
When the CodeBuilder installation has completed, review and restore the files preserved in Step 1. Pay special attention to the configuration files stored in /etc. It is usually best to generate differences, and then edit the versions in /etc to include your customizations.

NOTE: If you have not explicitly made changes to a configuration file, do not restore it. Configuration files sometimes change in new releases of CodeBuilder and restoring old configuration files may make the new release behave unexpectedly.

2.4.1 Reconfiguration

If your configuration changes, some files must be updated. This may be done automatically by using the CodeBuilder Control Panel or manually by updating the necessary files by hand. Where possible, the automated approach to reconfiguration is strongly recommended.

2.4.1.1 Automated Reconfiguration

In automated configuration, the following files are updated according to the information entered on the "General Configuration" screen of the CodeBuilder Control Panel:
/etc/rc.conf
/usr/etc/zoneinfo/localtime
Take the following actions:
Choose "Control Panels" from the Apple menu and open "CodeBuilder Controls". Make the appropriate changes, and press the "Save" button.
During the normal boot process, updated configuration parameter values will be noted and applied. Comments similar to the following will be displayed:

# Applying Installation configuration parameter settings..
Creating directory "/etc/PRE.Aug_20_13:54:01" to preserve original copies
Setting timezone to US/Pacific
Updating /etc/rc.conf

# "/etc/PRE.Aug_20_13:54:01" may be removed when the original copies
# it contains are no longer of interest for review or recovery.

2.4.2 Accessing CodeBuilder Source Files Directly From the CD-ROM

Code Builder source files may be accessed directly from the CD-ROM, rather than copying them to your hard disk. Although CD-ROMs typically have slower access times than hard disks, this configuration significantly reduces the hard disk footprint necessary to take full advantage of the CodeBuilder source distribution.

In order to access files directly from the CD, the CD must be online (visible on the desktop) and be mounted under CodeBuilder. The default /etc/fstab file will mount the CodeBuilder CD on the path /CDROM if the CD is online when CodeBuilder is started. The default /etc/fstab will then mount the Fast File System file Source_FFS (on the CodeBuilder CD) on the path /base/src.

If the CD is inserted when CodeBuilder is already running, the daemon macmntd will automatically mount the CodeBuilder CD on the path /CDROM . The Fast File System file Source_FFS (on the CodeBuilder CD) must be explicitly mounted. As root, execute the following commands:
# /sbin/mount -t ffs /CDROM/Source_FFS /base/src
Note that the target directory /base/macppc is still on the hard disk, so the objects for the BSD4.4 sources can be built even though the sources are on the CD. Obviously you cannot modify these programs by changing the source without copying them from the CD to your hard disk.

2.5 Troubleshooting

The CodeBuilder installation automatically configures the software and automatically adjusts the Macintosh system environment to ensure a properly running system. This section will help you solve problems that may arise as you work with CodeBuilder.


Symptom
Solution
The CodeBuilder Installer is unable to successfully install CodeBuilder. Temporarily remove or disable your INITs, particularly any anti-virus INITs. Retry the installation.
Launching CodeBuilder causes a system "bomb".
There may be a Control Panel or Extension conflict. Try temporarily disabling all INITs except the CodeBuilder INITs to determine if you have a conflict.
  • Make two new folders in your System Folder called Control Panels check and Extensions check.
  • "Select All" in the Control Panels folder, then hold the shift key down and click "CodeBuilder Controls" to unselect it. Drag the selected files into the Control Panels check folder.
  • "Select All" in the Extensions folder, then hold the shift key down and click on all the Tenon Folders to unselect them. Drag the selected files into the Extensions check folder.
  • Restart your Macintosh.
  • Run CodeBuilder.
If CodeBuilder successfully starts up, then a Control Panel or Extension in your system is incompatible with CodeBuilder. You can trace down the culprit by restoring and disabling your Control Panels and Extensions by halves until there is one remaining.
CodeBuilder seems to slow down.
Do a ps -alx and observe what processes are running. Use kill(1) to terminate unwanted processes. Read section "2.3 Performance Tuning - Optimizing CodeBuilder" for system optimization hints.

You notice loss of data due to file truncation.
Due to CodeBuilder file caching, CodeBuilder may not return an error when writing to a file system that is full. Check the free space on your file system before continuing.

You experience a power failure.
CodeBuilder must be restarted after a power failure. Although, traditional UNIX file systems are sensitive to power failures, CodeBuilder automatically checks the fast file system and it should not be necessary to further check the integrity of the file system.



[ Top of Page ][ 3.0 The CodeBuilder Control Panel ][ Table of Contents ]