Copyright © 2015-2024 Bill Kochman

Published On :
Last Updated :

Purpose of This Guide

The purpose of this tutorial is to assist you in properly compiling the Hermes II BBS source code -- version 3.5.11 -- on Macintosh computers running recent versions of Mac OS X and/or macOS which no longer support Apple's Classic environment -- that is, the Applications (Mac OS 9) folder -- using the Terminal, the SheepShaver emulator and the THINK Pascal compiler. There are links to obtain all required tools lower on this same page.

Requirements

• A working installation of THINK Pascal 4.0.2 [4.5d4 and 4.5a1 will not work]
• A working installation of SheepShaver
• A copy of the Hermes II BBS source code

Preparation

Note: Some of the following steps may require that you provide your admin password. Simply do so.

• SheepShaver

This tutorial assumes that you already have SheepShaver installed on your Mac OS X or macOS hard drive. If you don't have SheepShaver installed yet, there are links further down on this same page where you can download different versions of SheepShaver which are compatible with your machine.

• THINK Pascal

If you already have THINK Pascal 4.0.2 installed in your Mac Classic environment -- that is, in your SheepShaver setup -- you may use it. However, in order to avoid any potential problems during the build process, it is advisable that you install a fresh copy of the same following these steps:

• Download the four THINK Pascal 4.0.2 disk images from the link that is found lower on this same page. The file is called THINK-Pascal-4.0.2-Disk-Images.sit

• Place the "THINK-Pascal-4.0.2-Disk-Images.sit" file -- via your Mac OS X hared folder -- into your SheepShaver environment where you have Mac OS 9.0.4 installed. You created this shared folder -- which for the purposes of this tutorial, we will assume that you have named Shared -- when you first set up SheepShaver. As you should know, this Shared folder acts as the gateway between SheepShaver's Classic environment, and Mac OS X's Unix environment.

• In your Mac OS 9.0.4 environment -- or whatever version of Classic Mac you are using -- extract the four disk images from the StuffIt archive -- [.sit]

• Simultaneously mount all four disk images on SheepShaver's desktop.

• Open the disk called THINK Pascal 1 and carefully follow the installation instructions which are found in the file called Installation THINK Pascal. You must have TeachText or SimpleText installed in your SheepShaver installation in order to properly see the images in these extracted files.

• When you have completed the installation, you should have the following six folders in the Development folder. You created the Development folder when you followed the instructions in the installation Read Me file:

MacApp 2.0 for THINK Pascal 4.0
TCL 1.1 Pascal Demos
THINK Pascal 4.0 Demos
THINK Pascal 4.0 Folder
THINK Pascal 4.0 Utilities
THINK Reference 1.0 Demo

Important: When you use the installer called THINK Pascal Utilities.sea which is found in the THINK Pascal 1 disk image, it will install a folder called THINK Pascal  4.0 Utilities. This folder name will have TWO SPACES before the 4.0. You must remove the extra space, as otherwise, you will be unable to fully convert and translate the Hermes II project files when you run the shell script in the Mac OS X terminal.

• Rename the enclosing Development folder exactly to THINK Pascal 4.0.2. This is likewise an important step, as otherwise, the shell script will not be able to locate your THINK Pascal installation on the Mac OS X side.

• Drop the renamed THINK Pascal 4.0.2 folder onto the Unix icon on your SheepShaver desktop. This will make the THINK Pascal 4.0.2 folder available in your Shared folder on the Mac OS X side.

• Now go to the top level of your Mac OS X hard drive. This is where you will find the following folders:

Applications
Library
System
Users

In that same location, create a new folder called Applications (Mac OS 9). While you don't really have Apple's Classic environment installed on your computer, nevertheless, the shell script you are going to use needs to be able to find this folder.

IMPORTANT: In more recent versions of macOS, Apple does NOT allow users to create new folders at the top level of their hard drive. As such, you need to do it in a roundabout -- but easy -- way. Please click here for instructions.

• Drag the THINK Pascal 4.0.2 folder which you just placed in SheepShaver's Shared folder, into the newly-created Applications (Mac OS 9) folder.

With this last step, your preparations are now complete, and you are ready to work with the Hermes II source code in the Mac OS X terminal. Congratulations!

Converting and Translating Hermes II GitHub Files

• Download the Hermes-3.5.11-Source-Code.zip archive from the link that is provided lower on this same page. The link is called Hermes 3.5.11 Source.

• Once you have downloaded the Hermes-3.5.11-Source-Code.zip file, place it in your Home directory.

• Launch the Terminal app -- it is located in your /Applications/Utilities folder -- and use the following command -- followed by hitting your Return key -- to unzip the archive in your Home folder:

unzip Hermes-3.5.11-Source-Code.zip

• Doing the above will produce a new uncompressed folder in your Home directory called HermesBBS-main.

• The next step is to change directories so that you will be inside the HermesBBS-main folder. This is necessary so that you can run the shell script that is located there. So, type the following command at the Terminal and hit the Return key:

cd HermesBBS-main

• Now it is time to run the shell script. It will do the following things in a matter of a few seconds. Let me tell you what they are before you actually run the script:

It will create a new folder in the HermesBBS-main folder called Working.

It will convert the Hermes.proj.r and Hermes.r files and place them in the Working folder.

It will translate all of the files that are found in the Includes and the Source folders, and place them in the newly-created Working folder.

• Now that you know what the shell script will do, let's do it by typing the following in the Terminal. Don't forget to hit the Return key after typing the command:

./prepare.sh working

• Before continuing, it would be good if you understood why all of these steps are even necessary. I emailed Michael Alyn Miller regarding this issue, and he wrote back to me with the following comments:

"Git doesn’t support Classic Mac OS; it pretty much only works on UNIX and Windows. This means that you have to work with the Git repository (the contents of which you have in that zip file) from a UNIX environment.

The problem with working with the files in a UNIX environment is that they are then formatted entirely differently from what works in a Classic Mac OS environment! UNIX files end in LF (\n), but Classic Mac OS files end in CR (\r). UNIX text files are in UTF-8, but Classic Mac OS is MacRoman. UNIX has no concept of resource forks and so the resource fork data for Hermes on GitHub has to be stored in .r (Rez) text files. UNIX has no concept of file/type creator, but you need the right file type and creator for things to work in Classic Mac OS. 'prepare.sh' basically fixes all of these problems for you, but it only runs in a Mac OS X terminal that has the right stuff setup."

In short, Michael not only had to do a lot of work in order to make the original Hermes II source code files compatible with the GitHub website, so that they would be available to adventurous souls around the world -- such as you and I -- but he also had to provide a way to convert those files back into something that is recognized by and compatible with THINK Pascal, once we downloaded the source to our own computers.

It kind of reminds me of how a modem works. It is a modulator/demodulator device. It converts signals back and forth so that both telephone lines and computers can use the data. So in my understanding, that is more or less what the shell script does as well.

• Now, if you have done everything properly and exactly as I have explained it to you in this tutorial, upon entering the ./prepare.sh working command at the prompt, the Terminal app will then proceed to do everything that I described to you earlier. While all of that is happening, it will display the following information in the Terminal window. If you see anything other than the following, something is probably wrong somewhere, and you are up the creek! :)

Moving the "Working" Folder to SheepShaver

• Assuming that everything has gone well for you, and there is not a single error on your screen, let us proceed. Open the HermesBBS-main folder, and then copy the Working folder within it over to SheepShaver's Shared folder. You can use the original Working folder if you like. However, I prefer to just copy it so that I still have a backup remaining in the HermesBBS-main folder.

• Next, go to your SheepShaver desktop, and open the Unix drive. You will now see the copy of the Working folder that you just placed there via the Shared folder.

• Open SheepShaver's startup drive, and then open your main THINK Pascal 4.0.2 folder. This is where the following six folders are located:

THINK Pascal 4.0.2 <----- Go inside here!
    MacApp 2.0 for THINK Pascal 4.0
    TCL 1.1 Pascal Demos
    THINK Pascal 4.0 Demos
    THINK Pascal 4.0 Folder
    THINK Pascal 4.0 Utilities
    THINK Reference 1.0 Demo

• Next, drag the Working folder from the Unix drive into the now-open THINK Pascal 4.0.2 folder. When you are done, your folder hierarchy should look like this:

THINK Pascal 4.0.2
    MacApp 2.0 for THINK Pascal 4.0
    TCL 1.1 Pascal Demos
    THINK Pascal 4.0 Demos
    THINK Pascal 4.0 Folder
    THINK Pascal 4.0 Utilities
    THINK Reference 1.0 Demo
    Working

Running the THINK Pascal Compiler

• Now you are ready for some serious business! :)

• Open the Working folder and double-click on the Hermes.proj project file. Doing this will immediately launch the THINK Pascal compiler, and will display the Hermes.proj project window, which will be populated with all of the necessary resources and libraries.

• Click on the Build Application option under the Project menu, and when prompted, choose a location for the newly compiled Hermes II application. By default, THINK Pascal will select the top level of SheepShaver's hard drive, which is fine.

• Within seconds, you will have a copy of the latest build of the Hermes II application. Bravo! Well done! No sweat, right? :)

• Let's tidy up a bit now. Select Close Project under the Project menu, and then shut down the THINK Pascal compiler.

• For safe-keeping, make a backup copy of your new Hermes II application, compress it, and then store it in a secure location, either on your Mac OS X hard drive, or even on some external medium.

Replacing Your Hermes II Application

• Assuming that you already have a previous version of the Hermes II BBS package running on your virtual machine -- meaning SheepShaver -- when you are ready, do the following:

1. Shut down Hermes II if it is running.

2. Compress your current version of the Hermes II app -- that is, the one you have been running up until now -- just to avoid any possible confusion. Only compress the app itself, and not any of the folders.

3. Place the new version of Hermes II at the top level of your Hermes II installation where your current Hermes II app is already located.

4. Put your current version of the Hermes II app -- that is, the one you have been running up until now -- in the trash. Don't worry. You've already made a compressed copy of it, right?

5. Launch the new version of the Hermes II application.

6. Log on to your new Hermes II BBS and check for any possible problems.

• Congratulations! Your new version of the Hermes II BBS software package should now be running smoothly without any hiccups. Good for you! :)

Avoid the Headaches!

• Important: Please note that if you decide to change the name of your main Hermes II folder in order to reflect the new version number that you are running, you will break all of the paths to your file transfer directories. Thus, when you reboot Hermes II, you will hear a lot of beeps, and get a window full of error messages. If you only have a few file directories on your Hermes II BBS, it is no problem to fix the paths under the Setup/Transfers menu. However, if you have dozens of areas and directories on your BBS, it will be a major headache to fix them all. So think about this before you decide to change the name of your main Hermes II folder on a whim.

The Hermes II BBS Coding Challenge!

Wouldn't it be great if some THINK Pascal coding genius, or perhaps a group of coding geniuses, who have the time, interest and patience, decided to overhaul the Hermes II BBS code base so that it can run natively on the latest version of Mac OS X? Are you prepared to let Macintosh BBSing die? Are you prepared to let Hermes II wither away, die and go silently into the night without the least bit of a whimper?

It has been years now since Michael Alyn Miller made the Hermes II source code open source, and even took the time to upload it to the GitHub repository. Sadly, there it has languished, untouched, and unused, until now. Do you miss the good old days of Macintosh BBSing? Wouldn't you like to see Hermes II with a modern interface? Will you make a difference?