Tutorial - Session 3
| by Michael Rideout |
Getting Set Up
It's a good idea to keep things organized on your computer, to help you find things more easily. For this tutorial, we'll create a directory
where we'll put most of the programs we'll be installing. You don't have to use the same organization and directory names that I do, but I
advise you to use some kind of organization that makes sense to you.
The following instructions assume that you want to organize things the same way that I'm going to, and that you're using Windows. If you want
to organize things differently, or if you aren't using Windows, then you'll need to adjust the following instructions as appropriate.
Installing DASM
The batari BASIC package already contains an MS-DOS executable of the DASM assembler, but you might want to download and install the full DASM
package, since it includes some documentation that isn't in the batari BASIC package. And if you're using a non-Windows system, you'll need to
download DASM to get the version that works on your system.
If you don't need or don't want to download the full DASM package, you can skip to the section about "Installing an Emulator."
Go to the "C:\Atari2600" directory that you created earlier, and create a "DASM" subdirectory (i.e., "C:\Atari2600\DASM").
Go to the DASM homepage. In the "DASM Assembler Download" section, click on the link
for DASM 2.20.07. Note that this is not the newest version of DASM - the newer versions contain a bug that occasionally prevents your code
from compiling correctly. When the computer asks whether you want to open or save the file, click on "Save," then browse to the
"C:\Atari2600\DASM" directory, and save it there.
Once the file is downloaded, go to the "C:\Atari2600\DASM" directory and decompress it with whatever decompression utility you use-- WinZip,
PKUNZIP, Windows' compressed folder feature, etc. You should extract the files to the "C:\Atari2600\DASM" directory, and use the option to
keep the directory information, so the files will be extracted into their appropriate subdirectories.
Installing an Emulator
You need only one Atari 2600 emulator, but you might want to install more than one, especially if you want to try out several to see which one
you like best. For this tutorial, I'll be using the Stella emulator most of the time, but I'll give instructions for installing three of the
more popular emulators for Windows-- Stella, z26, and PCAE.
If you want to install just one emulator, decide which one you want to use, and skip to that section. Or you can follow the instructions to
install all three emulators. If you aren't using Windows, you'll need to use an emulator that works with your operating system. Stella is
available for a wide variety of operating systems; z26 is available for Windows and Linux; PCAE is available only for Windows.
Installing Stella
Go to the "C:\Atari2600" directory that you created earlier, and create a "Stella" subdirectory (i.e., "C:\Atari2600\Stella").
Go to the Stella homepage. In the left sidebar, in the "Downloads" section, click on
the link for the "Stable Releases." On the next page, click on the link for the newest version of Stella (as I write this, the newest version
is 2.1). For Windows, you'll want the "Binary installer (exe) for Windows 98/ME/2000/XP." You'll be taken to another page and asked to select
a mirror; just click on the link for the first site, or look for the site closest to your location. When the computer asks whether you want to
run or save the file, click on "Save," then browse to the "C:\Atari2600\Stella" directory, and save it there.
Once the file is downloaded, go to the "C:\Atari2600\Stella" directory and double-click it to start the installation. You should install the
program in the "C:\Atari2600\Stella" directory.
Installing z26
Go to the "C:\Atari2600" directory that you created earlier, and create a "z26" subdirectory (i.e., "C:\Atari2600\z26").
Go to the z26 homepage. Click on the link to download the newest version of z26 (as I write this, the
newest version is 2.13). When the computer asks whether you want to open or save the file, click on "Save," then browse to the
"C:\Atari2600\z26" directory, and save it there.
Once the file is downloaded, go to the "C:\Atari2600\z26" directory and decompress it. You should extract the files to the "C:\Atari2600\z26"
directory.
Installing PCAE
Warning: PCAE has not been updated in many years. bB games may not work correctly or at all with this emulator.
For our purposes, we would prefer to use an emulator that can start up playing a particular game. The most recent version of PCAE that can do
this is version 2.5, so that's the version we'll use in this tutorial.
Go to the "C:\Atari2600" directory that you created earlier, and create a "PCAE" subdirectory (i.e., "C:\Atari2600\PCAE").
The PCAE emulator has no homepage, but you can download version 2.5 from Zophar's
Domain. In the "PC Atari" section, click on the link for "v2.5." When the computer asks whether you want to open or save the file, click
on "Save," then browse to the "C:\Atari2600\PCAE" directory, and save it there.
Once the file is downloaded, go to the "C:\Atari2600\PCAE" directory and decompress it. You should extract the files to the
"C:\Atari2600\PCAE" directory.
Installing batari BASIC
Go to the "C:\Atari2600" directory that you created earlier, and create a "bB" subdirectory (i.e., "C:\Atari2600\bB"). You may download
batari Basic from the download section of this website. Unzip the contents of the batari Basic zip
file to the directory you just created.
Before you continue, you will need to copy or move GNU sed from its subdirectory to your bB directory, e.g. C:\Atari2600\bB.
Although bB will run without moving the program, sed will improve error reporting. sed is used to limit the amount of redundant
warnings and bogus errors that the assembler tends to produce. sed was not placed in the same directory as bB to avoid confusion with
their conflicting licensing terms.
You also need to set bB's path and envorinment variable before
you can use bB. There are several ways to do this. The easiest way is to just type in the commands below. This will be active for the
duration of your session, but only in the window where you define it. e.g.:
set bB=c:\Atari2600\bB
path=%path%;%bB%
If you plan to use an IDE or you just want this set permanently every time you start DOS or
the Windows command prompt, you may add the two above lines to the autoexec.nt (Windows NT/2k/XP) or autoexec.bat (DOS/Windows 95/98/Me) file.
autoexec.nt is typically located either in C:\WINNT\SYSTEM32 or C:\WINDOWS\SYSTEM32, and autoexec.bat is in the root directory. If the files
don't exist, create them.
Alternatively, there is a way to change the path and environment variables in Windows without using
autoexec. To do this, you'll need to be logged into Windows as a user with administrative rights. (If you're using your own computer, and have
only one user name set up, then you've almost certainly got administrative rights.)
Right-click the "My Computer" icon on your desktop, and left-click on "Properties." Left-click the "Advanced" tab, then left-click the
"Environment Variables" button. In the bottom half of the window, under "System variables," find the line that says "Path," and double-click
it with the left mouse button. (You might need to scroll down until you see "Path.")
This next part can be tricky, so be careful. The "Variable value" field will be highlighted, but you don't want to type in it while it's all
highlighted, or you'll delete everything in it. Instead, you want to press the "End" key, or else press the right arrow (right cursor) key,
which should put your cursor at the end of the text in the "Variable value" field. (If you accidentally press some other key and wipe out the
"Variable value" field by misyake, just left-click the "Cancel" button to abort the change, and then start over by double-clicking on "Path"
again.)
Once you've got the cursor at the end of the text in the "Variable value" field, add the following text to the end of it:
;C:\Atari2600\bB
Be sure to start with the semicolon, as shown, because it will separate your new entry from the entries that are already in the path. Also,
you should specify the particular drive and directory where you've installed batari BASIC. For example, if you've installed everything on
drive D:, then specify drive D: instead of drive C:. Or, if you've put everything in a folder named "AtariVCS," then type that name instead.
When you're done typing the new entry at the end of the "Variable value" field, click "OK" to save the changes.
Next, you should add a new variable to the "System variables." Click the "New" button in the bottom half of the window, which will open a "New
System Variable" window. (If the window says "New User Variable," then you clicked the wrong "New" button, so click "Cancel" to close the
popup window, then click the correct "New" button-- the one in the bottom half of the window.)
Click in the top field, which says "Variable name," and type in the following:
bB
(That's it-- just "bB"!)
Now click in the bottom field, which says "Variable value," and type in the following:
C:\Atari2600\bB
(Again, this should be the specific drive and directory you installed the batari BASIC package in.)
When you're done, click "OK." You should now see the "bB" entry in the bottom half of the window, under "System variables." Then click "OK" to
close the "Environment Variables" window, and click "OK" again to close the "System Properties" window.
You can verify that the entries were added correctly by opening a command prompt window. Click the "start" button, click "All Programs," click
"Accessories," and click "Command Prompt." When the "Command Prompt" window appears, type in the following command, then press the "Enter"
key:
set
This will display a whole bunch of lines that probably look very confusing, but you don't care about them. Just look for a line that says
"bB=C:\Atari2600\bB" (or whatever drive and directory path you used), which should be near the top of the list, since the lines are in
alphabetical order. (You might need to scroll up to see it.) Then look for the line that starts with "Path=" and verify that it ends with the
";C:\Atari2600\bB" directory. Once you've verified that these two entries are installed, you can close the "Command Prompt" window.
The following subdirectories should be created as a part of the unzipping process:
manual (i.e., "C:\Atari2600\bB\manual")
The reference manual (manual.html) may be found here.
includes (i.e., "C:\Atari2600\bB\includes")
This is where the various support code for bB goes. That is, assembly source files, header files and includes files.
samples (i.e., "C:\Atari2600\bB\samples")
A few sample batari Basic programs go here. Some of these are just demos but a few are playable games.
source (i.e., "C:\Atari2600\bB\source")
Complete source code for building batari Basic can be found here.
sed (i.e., "C:\Atari2600\bB\sed")
GNU sed and its license (GNU GPL) are found here. These were placed in a separate folder to avoid confusion with sed's conflicting licensing terms. You will want to copy or move sed.exe from this subdirectory to your bB directory.
Installing 2600IDE
We'll need to use a text editor to write batari BASIC programs, but as mentioned in Session 2, it's better to use an IDE ("integrated
development environment"), which is a fancy kind of text editor that programmers use for writing, compiling, and running programs. Jacco
Mintjes ("Attendo") created the 2600IDE editor just for batari BASIC, so let's install the newest version of it (0.4.1).
Before you download 2600IDE, you need to make a copy of your 2600bas.bat file, and name this copy 2600baside.bat. If you haven't already, you will need to permanently set the path and environment variable as outlined above before 2600IDE will work. Then you may
download 2600IDE, and when the computer asks whether you want to open or save the file, click on "Save," then browse to the "C:\Atari2600\bB"
directory, and save it there.
Once the file is downloaded, go to the "C:\Atari2600\bB" directory and decompress it. You should extract the file to the "C:\Atari2600\bB"
directory.
Once the "2600IDE.exe" file is extracted, double-click on it. This will pop up a "Locate emulator executable" window. Browse to the directory
that contains the emulator you want to use (Stella, z26, or PCAE). For this tutorial, we'll primarily use the Stella emulator, so browse to
the "C:\Atari2600\Stella" directory. Once there, double-click on the "stella.exe" file to select it as the emulator which 2600IDE will use.
(Note that we can switch to a different emulator later if we want.) You should now see a tiny window that says "Emulator located." Click on
the "OK" button to finish.
Now that we've installed and set up the 2600IDE editor, we can test it by compiling one of the programs that came in the batari BASIC package.
Click on the "File" menu and select the "Open" option. In the "Open" window, browse to the "C:\Atari2600\bB\Samples" directory. Let's compile
the "draw.bas" program. Double-click on the "draw.bas" file, and it will load into the 2600IDE editor. We won't worry about trying to
understand any of the program code right now. Instead, let's just compile it.
Click on the "Actions" menu and select the "Compile" option. The screen will flash, and then return to the program listing.
To run the compiled program, click on the "Actions" menu and select the "Run a Compile" option. Browse to the "C:\Atari2600\bB\Samples"
directory (if you aren't already in that directory), and double-click on the "draw.bas.bin" file to run it. The Stella emulator will start
up and display the "draw" game. Use your cursor control keys to move your car around the maze of streets. After you've tested the game for a
little while, click on the "close" icon in the upper right corner of the Stella window to exit the emulator.
Next, click on the "File" menu and select the "Exit" option to close the 2600IDE editor.
Installing Crimson Editor
Although the 2600IDE editor is easy to use, and has a built-in sprite editor and playfield editor, the primary editor that I'll be using in
this tutorial is the free Crimson Editor. Crimson Editor is much more powerful than the 2600IDE editor, because it's been under development
for a much longer period of time.
Go to the "C:\Atari2600" directory that you created earlier, and create a "CrimsonEditor" subdirectory (i.e., "C:\Atari2600\CrimsonEditor").
Go to the Crimson Editor homepage. Click on the link for the newest version (as I write
this, the newest version of Crimson Editor is 3.70). On the next page, click on the link for the "Crimson Editor 3.70 Release" file. When the
computer asks whether you want to run or save the file, click on "Save," then browse to the "C:\Atari2600\CrimsonEditor" directory, and save
it there.
You will need to permanently set the path and environment variable as outlined above before Crimson Editor will work properly.
Once the file is downloaded, go to the "C:\Atari2600\CrimsonEditor" directory and double-click it to start the installation. You should select
all of the components, and install the program in the "C:\Atari2600\CrimsonEditor" directory.
Once the installation is finished, it will put a "Crimson Editor" shortcut on your desktop. Double-click on the shortcut to start it. You may
see a scary-looking message that says the "Crimson Editor configuration file has been corrupted!" But then it says "Ignore this message if it
is the first installation." (Whew!) Click on the "OK" button to continue.
On the left side of the Crimson Editor window is a sidebar that shows your drives and directories. If you don't see this box, then look at the
menu task bar and find the binoculars. Immediately to the right of the fourth binoculars icon (which says "Find Prev" when you point to it),
there is an icon of a split window with a folder on it (which says "Directory Window" when you point to it). Clicking on that icon makes the
directory sidebar appear or disappear. If the directory sidebar is not visible, then click that icon to open it. Then double-click on the
"Atari2600" folder to expand it, double-click on the "bB" folder to expand it, and double-click on the "Projects" folder to expand it.
You should now see all of the files in the "C:\Atari2600\bB\Samples" directory. Double-click on the "zombie_chase.bas" file to open it. (Of
course, you could also click on the "File" menu, select the "Open..." option, and then browse to the file you want to open.)
You'll note that the "Text1" tab is still there. You can right-click on it and select the "Close" option to close it, since it's just a blank
text file. This will leave the "zombie_chase.bas" file open. As you can see, Crimson Editor lets you open multiple files at the same time, and
click on their tabs to go from one to the other.
In order to compile a batari BASIC program with Crimson Editor, we need to set up a menu function for us to use. Click on the "Tools" menu and
select the "Conf. User Tools..." option.
In the new window, click on the first line in the "User Tools" box, which says "- Empty - Ctrl+1." Then click in the "Menu Text" field and
type "Compile bB Program."
Next, click on the "..." button to the right of the "Command" field. Browse to the "C:\Atari2600\bB" directory, and double-click on the
"2600bas.bat" file. This will put "C:\Atari2600\bB\2600bas.bat" in the "Command" field.
Next, click on the ">" button to the right of the "Argument" field. In the pop-up menu, click on the "File Path" option. This will put
"$(FilePath)" in the "Argument" field.
Next, click on the ">" button to the right of the "Initial Dir" field. In the pop-up menu, click on the "Browse..." option. Browse to the "bB"
folder and select it, then click on the "OK" button. This will put "C:\Atari2600\bB" in the "Initial Dir" field.
Next, check the "Capture output" option, and uncheck the "Use short filename (8.3)" option. The "Save before execute" option should also be
checked. Finally, click on the "OK" button to save the setup.
Now let's compile the "zombie_chase.bas" program. Click on the "Tools" menu, and select the new "Compile bB Program" option. An "Output" window
will appear at the bottom of the screen showing the results of the compile, which should end as follows:
> Terminated with exit code 0.
(That means "Everything was A-OK!")
Now that we've successfully compiled the "zombie_chase.bas" program, let's set up another menu function so we can run it. Click on the "Tools"
menu and select the "Conf. User Tools..." option again.
In the new window, click on the "- Empty - Ctrl+2" line, just below the line that says "Compile bB Program." Then click in the "Menu Text"
field and type "Run bB Program."
Next, click on the "..." button to the right of the "Command" field. Browse to the "C:\Atari2600\Stella" directory, and double-click on the
"stella.exe" file. This will put "C:\Atari2600\Stella\stella.exe" in the "Command" field.
Next, click on the ">" button to the right of the "Argument" field. In the pop-up menu, click on the "File Path" option. This will put
"$(FilePath)" in the "Argument" field. Click at the end of the "Argument" field so the cursor is at the end of the "$(FilePath)" entry, and
add ".bin" to the end of it, so it says "$(FilePath).bin."
Next, click on the ">" button to the right of the "Initial Dir" field. In the pop-up menu, click on the "Browse..." option. Browse to the
"Stella" folder and select it, then click on the "OK" button. This will put "C:\Atari2600\Stella" in the "Initial Dir" field.
Finally, click on the "OK" button to save the setup.
Now let's run the compiled "zombie_chase" program. Click on the "Tools" menu and select the new "Run bB Program" option. This will start up the
Stella emulator with the "zombie_chase" game. Use your cursor control keys to wander around the maze. After you get totally lost, click on the
"close" icon in the upper right corner of the Stella window to exit the emulator.
There's more we could do to set up the Crimson Editor program, such as creating language files so that Crimson Editor will color code the
batari BASIC and 6502 assembly keywords, but we won't worry about that right now. We also won't worry about installing any other programs yet,
such as the Distella disassembler; we'll install them as we need to use them in the tutorial. For the time being, we're all set up and ready
to rock and roll!
Software, site and content © 2005-2007 Fred X. Quimby. All rights reserved.