Home
AGS
LVDC
Gemini
Download
Document library
Change log
Bug and issues
Developer info
Virtual AGC — AGS — LVDC — Gemini

Downloads
Installers for Linux/Windows/Mac OS X
Software Source Code
FAQ
yaAGC
yaYUL
yaDSKY
yaOtherStuff
Luminary
Colossus
Language Manual
Physical Implementations

Please enable javascript in your browser to see a site-search form here.


An archived older version of this page is also available for supporting very old versions of the software.

Contents

Prerequisites for Binary-Package Installation

Obviously, I'm not in a position to test on every platform known to man, but the following represents my beliefs based on the testing I've been able do do.  Note that when I say that Virtual AGC "works" on a given platform, it may still be subject to some limitations or reduced functionality in some areas.

Downloads

The development snapshot is versioned, and all released snapshots remain available perpetually in the archive.  However, for economy, binary downloads are not versioned and simply are current with the latest development snapshot.  The subversion repository represents a separate source tree that was forked at some point and then merged back in May 2009; therefore, all development snapshots after May 2009 can be found in the subversion repository, but not prior to that time.  The subversion repository may contain more up-to-date code than the development snapshot, but is less likely to build and work.

Item
Download
Notes
Source-code repository
subversion repository
See the instructions for compiling from source.  Note that to match
the assumptions of Virtual AGC documentation, when performing a
checkout you should explicitly rename the source-tree as "yaAGC":
svn checkout http://virtualagc.googlecode.com/svn/trunk/ yaAGC
Source code development snapshot
yaAGC-dev-20100220.tar.bz2
(same as subversion rev 609)
See the instructions for compiling from source.
Pre-built Linux x86 binary package
VirtualAGC-installer
See the installation instructions and the platform-specific quirks.
Pre-built Win32 binary package
VirtualAGC-setup.exe
See the installation instructions and the platform-specific quirks.
Pre-built Mac OS X binary package
VirtualAGC.app.tar.gz
See the installation instructions and the platform-specific quirks.
Prior releases
Archive

Note that the Mac OS X binary package includes a program called Terminator which I haven't written, but which is available under the GNU GPL license.  If you so desire, you can download the Terminator source code for the version whose binary is being provided by clicking here.  I have neither modified nor recompiled this code.  Neither the Terminator source code nor binary is versioned as provided here, because the files I downloaded were not versioned by the Terminator project itself.

You should note, by the way, that alternate installation options might be available at our GoogleCode page for certain specific computer configurations. (Whereas my "standard" install focuses almost entirely on wide cross-platform consistency.) While I won't try to track those alternate packages in detail here, I'm aware that (for example) there's a 64-bit Fedora 12 RPM there that's consistent with the 201000220 snapshot.  I'm told by Onno Hommes that the following advantages can be expected from using the RPM rather than my "standard" install:

Installing binary packages

Linux

(Note: the installer program may not be marked as "executable" after download, so please change its desktop-icon properties permissions to "executable", or else do "chmod +x VirtualAGC-installer" from the command line.) Simply run the installation program, which is VirtualAGC-installer.  Usage will be obvious to you.  A desktop icon called "Virtual AGC" will be installed unless you deselect it.  Additionally, a program group will be placed on your Gnome or KDE start menu called "Virtual AGC", and it will contain both the VirtualAGC program and an uninstaller program. (I'm not sure what happens in alternate desktop environments like XFCE.)  On some systems the start menu may not be immediately updated and therefore you may not see the "Virtual AGC" program group until you log in the next time.

If you try to use the ACA simulation (joystick) and it doesn't work, read about configuring it.

Note to FreeBSD users:  You may anticipate that the Linux version of Virtual AGC can be installed, due to the optional Linux compatibility layer of FreeBSD.  I would not recommend it, since (in my experiments) it worked just enough to give you a false sense of hope, but not enough to do anything useful.  Please build from source instead if using FreeBSD.

And don't forget to read the prerequisites, the trouble-shooting tips, and the list of quirks for this platform.

Windows

Simply run the setup program, which is VirtualAGC-setup.exe.  Usage will be obvious to you.  A desktop icon called "Virtual AGC" will be installed unless you deselect it.  Additionally, a program group will be placed on your Windows start menu called "Virtual AGC", and it will contain both the VirtualAGC program and an uninstaller program.

If you are using Windows Vista or Windows 7, there are additional configuration steps you need to perform, or else the software will not work.

If you try to use the ACA simulation (joystick) and it doesn't work, read about configuring it.   And don't forget to read the prerequisites and the trouble-shooting tips.

Mac OS X

Place VirtualAGC.app.tar.gz on the desktop, and double-click it to extract the contents.  The reward will be the creation of a desktop icon for VirtualAGC.  Double-click the icon to run the program.

If you wish to uninstall Virtual AGC, just drag the desktop icon into the trash.  Note that this will also delete any custom files (configurations, core dumps, etc.) which may have been created, so if you want to preserve any of them you need to do so manually.

If you try to use the ACA simulation (joystick) and it doesn't work, read about configuring it.   And don't forget to read the prerequisites, the trouble-shooting tips, and the list of quirks for this platform.

Contents of the development snapshot

Directory
Contents
Status
yaAGC/Colossus249/
Source code (*.agc) and binary (*.bin and *.binsource) image for Build 249 of the Colossus (AGC Command Module) program.  (Apollo 9.)
100% complete, proofed, and known to be valid.
yaAGC/Luminary131/
Source code (*.agc) and binary (*.bin and *.binsource) image for Build 131 of the Luminary (AGC Lunar Module) program.  (Apollo 13.)
100% complete, proofed, and known to be valid.
Some utilities.
  • Oct2Bin --- converts a set of Luminary/Colossus binaries given in the form of an ASCII file to a core-rope binary, or vice-versa.  This is 100% working.  Needed only for validating data entry for programs like Luminary or Colossus.
  • CheckDec --- allows interactive entry of decimal numbers (suitable for DEC/2DEC pseudo-ops), and immediate viewing of their binary forms.  This is 100% working.  Needed only for experimenting with the binary formats the AGC uses for storing numbers.
  • webb2burkey-rope --- converts the core-rope files used in Virtual AGC to the format used by Julian Webb's AGC simulator, and vice-versa.  This is 100% working, but since few of you have Webb's simulator, the point is moot.
yaAGC/Artemis072/
Source code (*.agc) and binary (*.bin and *.binsource) image for Build 072 of the Artemis or Colossus 3 (AGC Command Module) program.  (Apollo 15-17.)
100% complete, proofed, and debugged.
yaAGC/Comanche055/
Source code (*.agc) and binary (*.bin and *.binsource) image for Build 055 of Comanche (Colossus 2).  (Apollo 11.)
100% complete, and debugged.
yaAGC/Luminary099/
Source code (*.agc) and binary (*.bin and *.binsource) image for Build 099 of Luminary.  (Apollo 11.)
100% complete, and debugged.
yaAGC/Solarium055/
Source code (*.agc) and binary (*.binsource) for Build 055 of Solarium (AGC Command Module) program.  (Apollo 4.) I'm not sure of the present status of this, but it seems mostly complete.  We presently have no way to assemble the source code to check it against the binary, nor to run the binary in yaAGC, so there's no way to be sure yet of the accuracy of what we have.
yaAGC/yaAGC/
Source code for the yaAGC (AGC emulator) program.
99% complete.  At present, you can expect to see do the stuff described in the Quick Start section of my home page.  Both the LM and CM sims should work quite well.
yaAGC/ControlPulseSim
An emulator for the AGC at the "control-pulse" (microcode) level rather than the instruction level.
Allows interactive simulation of some (but not all) control-pulse sequences (microcode) for the AGC.  This program is only for the very brave, and very little of it works.  I'll probably never complete much more of it.
yaAGC/yaDSKY/
Source code for the yaDSKY (DSKY emulator) program.
99% complete.  (The STBY and RESTART indicator lamps are inoperable.)  In addition to being a DSKY simulation, this program can print out downlinked telemetry data.  This program has been superceded by yaDSKY2.
yaAGC/yaDSKY2/
Source code for the yaDSKY2 (DSKY emulator) program.
99% complete.  (The STBY and RESTART indicator lamps are inoperable.)  This program has superceded yaDSKY.
yaAGC/yaUniverse/
Source code for the yaUniverse (spacecraft motion emulator) program.
Is now capable of modeling the motion of heavenly bodies and spacecraft under gravitational influences.  This, perhaps, 25% of what's required in the full program.
yaAGC/yaIMU/
Source code for the yaIMU (inertial measurement unit emulator) program. This program has not yet been started.  (Because of Stephan Hotto's contributed LM_Simulator program, the yaIMU program is no longer needed, and therefore is no longer being planned.)
yaAGC/yaAOT/
Source code for the yaAOT (alignment optical telescope emulator) program. This program has not yet been started.
yaAGC/yaACA/
Source code for the yaACA (attitude controller assembly emulator) program. This program is 100% complete and seems fine on a standalone basis, but the complete system environment for it has not yet been demonstrated to work.
yaAGC/yaACA2/
Source code for the yaACA2 (attitude controller assembly emulator) program. This program is an alternate to yaACA and yaACA3.
yaAGC/yaACA3/
Source code for the yaACA3 (attitude controller assembly emulator) program. This program has superceded yaACA.
yaAGC/jWiz/
Source code for jWiz, a program to select/configure yaACA, yaACA2, and yaACA3.
Working.
yaAGC/yaTelemetry/
Source code for the yaTelemetry (telemetry-downlink console) program.
This program is 100% complete and functional.
yaAGC/yaYUL/
Source code for the yaYUL (AGC cross-assembler) program.
100% complete, and capable of assembling Luminary131, Colossus249, or Validation source code without error.
yaAGC/Validation/
Source code for a (newly-written) program in AGC assembly-langauge that is used to test the emulator's instruction set.
About as complete as it's going to get!
yaAGC/yaAGS/
Source code for the yaAGS (Abort Guidance System emulator) program.
Now working.  Probably there are a number of bugs and unimplemented features, but at least it can pass the built-in self-test, and can perform the few operations I personally know how to activate.  :-)
yaAGC/yaDEDA/
Source code for the yaDEDA (emulator for the Data Entry and Display  Assembly—i.e., the AGS user interface) program
I think this program is 100% working.  This program has been superceded by yaDEDA2.
yaAGC/yaDEDA2/
Source code for the yaDEDA2 (emulator for the Data Entry and Display  Assembly—i.e., the AGS user interface) program I think this program is 100% working.  This program has superceded yaDEDA.
yaAGC/yaLEMAP/
Source code for the yaLEMAP (AGS cross-assembler) program.
I think this program is 100% working, though there could be bugs I'm not aware of.
Sample AGS source code.
100% complete and correct.
Utilities
binLEMAP --- like Oct2Bin, but for the AGS instead of the AGC.  100% working.  Needed only for validating source-code data entry for programs like AGS FP6 or FP8.
yaAGC/FP6/
Source code (*.aea) and binary (*.bin and *.binsource) for AGS FP6 (Flight Program 6)
It is believed that the source code is 100% complete and correct, and that the binary produced by assembling the source with yaLEMAP is 100% complete and correct.
yaAGC/FP8/
Source code (*.aea) and binary for AGS FP8 (Flight Program 8)
It is believed that the source code is 100% complete and correct, and that the binary produced by assembling the source with yaLEMAP is 100% complete and correct.
yaAGC/Contributed/LM_Simulator/
Tcl/Tk source code, contributed by Stephan Hotto.
Continually evolving in its conception, and I'm not the author, so I can't give a percentage of completion.  At present, the program has the following features:
  • An operational IMU.
  • An operational FDA ball.
  • An operational "DSKY Lite" (an alternate DSKY simulation), for use on target computer platforms where yaDSKY cannot be built.
  • An operational i/o-channel monitor
yaAGC/Contributed/GamePack/
A one- or two-player tic-tac-toe and a Simon game, contributed by John Pultorak.
The source code for these games is complete, but has not presently been converted for the yaYUL assemembler, or adapted appropriately to actually be run in yaAGC.
yaAGC/Contributed/SyntaxHighlight/
AGC and AEA assembly-language highlighters for various text-editor programs in Linux and Windows, contributed by Onno Hommes.
Complete.
yaAGC/Contributed/DebugScripts/
Assistance for GUI-based debugging of AGC programs, in programs like Code::Blocks, contributed by Onno Hommes.
Working.
yaAGC/Tools/
yaAGC/Contributed/WireLister/
Some tools contributed by Jim Lawton.  I'm not presently sure what all of them are or of their general utility.
Don't know.
yaAGC/VirtualAGC/
Top-level GUI front-end VirtualAGC for all other Virtual AGC programs.
Working and very usable.  (Much more so than the alternative shell scripts it has replaced, anyhow!)
yaAGC/yaASM/
A Gemini OBC and Apollo LVDC assembler.
This is a work in progress.  It is valueless at present to any end-user.


Extras!  (Optional stuff requiring manual setup)

AGC/AEA Source-Code Syntax Highlighting

Onno Hommes has developed AGC and AEA specific syntax-highlighting extensions for various editing programs often used for developing software source code:  Kate, KWrite, Kdevelop, Eclipse, vim, TextPad, and (maybe) emacs.   Although there's no real way to integrate this feature with Virtual AGC software proper, each of the available downloads (source-code development snapshot and Linux/Win32/Mac binary installers) do provide the appropriate configuration files for updating the various text-editing programs.  There is also a file called EnableSyntaxAGC.odt included there which contains instructions for doing so.  (At present, you may want to use the free OpenOffice.org office suite to read this file.) 

For a binary installation, the files just mentioned can be found under the installation directory (typically "~/VirtualAGC/Resources/SyntaxHighlight" in Linux, "c:\Program Files\Virtual AGC\Resources\SyntaxHighlight" in Windows, and "~/Desktop/VirtualAGC.app/Contents/Resources/SyntaxHighlight" in Mac OS X).  For a development snapshot, look in "yaAGC/Contributed/SyntaxHighlight".

Here's a nice screenshot (click to enlarge) of what source highlighting looks like in Kdevelop.  As you can see, it's a lot more pleasant to read the AGC source code with the highlighting than without it.
Screenshot of source highlighting in KDevelop

Of course, syntax highlighting is also provided when browsing AGC/AEA source code from the VirtualAGC GUI—thanks to enhancements to the assemblers prompted by seeing Onno's text-editor extensions in action—but the VirtualAGC GUI syntax-highlighting depends on having previously assembled the programs and does not provide developmental editing of the source code.

gdb-compatible AGC/AEA debugging

Onno has also done a lot of work on changing the debugging options of the AGC and AEA simulations—i.e., the ability to debug AGC and AEA assembly-language code—from the original methods I conceived to a gdb-compatible method in which gdb commands and GUI front-ends like Kdbg, Code::Blocks, or EMACS could be used.  This is largely working.  The official explanation is maintained by Onno at the separate website Onno has set up

One-time setup procedure for Code::Blocks

What follows is my explanation of the minimum one-time setup steps needed to make CUI-based debugging via Code::Blocks work directly with the VirtualAGC GUI.  With some luck, we may be able to eventually provide scripts to automate the setup, but for now it's a manual procedure.  Note that I'm describing work in progress, and so my description may not yet be fully accurate.

In the explanation that follows, we'll need to refer to the folder in which Virtual AGC is installed, which differs from platform to platform and according to your installation or build choices.  By default, the installation directory will be something like:. For simplicity we'll just refer to it as InstallDir.  Also, we'll always pretend for simplicity that the character '/' is used as a path separator, even though it is really '\' on Windows.

So here is the setup procedure:
  1. Install Code::Blocks for your desired development platform.  (If you are developing/debugging your AGC/AEA code in Linux, Code::Blocks may be in your Linux distribution's packaging system.)
  2. Installation of AGC/AEA syntax-highlighting enhancement for Code::Blocks:
    1. Copy the contents of InstallDir/Resources/SyntaxHighlight/CodeBlocks/lexers/ to the lexers/ folder of your Code::Blocks installation:
      1. For a default Linux installation:  "/usr/share/codeblocks/lexers".
      2. For a default Win32 installation:  TBD.
      3. For a default Mac OS X installation:  TBD.
    2. Run Code::Blocks.
    3. Verify installation of syntax-highlighting by selecting Settings/Editor/Syntax-highlighting from the main menu.  If "AGC Assembly" and "AEA assembly" are among the choices in the language-selection drop-down list, then the syntax-highlighting enhancement has been installed properly.
  3. Configuration of AGC toolchain:
    1. From the main menu, select Settings/Compiler-and-debugger.
    2. In the Global-compiler-settings section:
      1. Make sure that "GNU gcc Compiler" is the "Selected compiler".
      2. Click the "Copy" button and in the "Add new compiler" pop-up window that appears, choose the name "AGC yaYUL Assembler".
      3. In the "Compiler Flags" tab, make sure that no flags are enabled.
      4. In the "Toolchain executables" tab (which you may need to scroll rightward to find):
        • For Mac OS X only, in the "Additional Paths" tab next to the "Program Files" tab, add the path "InstallDir/MacOS".  (All of the other settings below are in the "Program Files" tab and apply to all platforms unless stated otherwise.)
        • For the "Compiler's installation directory" choose InstallDir.
        • For the "C compiler", "C++ compiler", "Linker for dynamic libs", and "Linker for static libs" choose either "yaYUL" or "yaYUL.exe" depending on your platform.
        • For the "Debugger", set "yaAGC" or "yaAGC.exe" depending on your platform.
        • Leave the "Resource compiler" setting blank.
        • For Win32, you may will probably need to change the "Make program" setting whatever 'make' you're actually using, and to add the path in which it is located to the "Additional Paths" tab.
        • For FreeBSD only, if you are using GNU make rather than the default 'make' provided by the operating system, change the "Make program" setting to "gmake".
  4. Configuration of AEA toolchain:  Not implemented yet.

Project-creation procedure in Code::Blocks

TBD

Building the Virtual AGC software

Linux

Prerequisites:  You will need the normal gcc C/C++ compiler toolchain, as well as developer packages ("dev" or "devel") for wxWidgets and SDL.  These are all available in the package repositories of the common current Linux distributions, though figuring out what the package names are can be an adventure.  Or, you can install them from source if you swing that way.

From the command line, unpack the development-snapshot tarball as follows:

tar --bzip2 -xf yaAGC-dev-YYYYMMDD.tar.bz2

After unpacking there will be a new directory called "yaAGC".   To build the programs,

cd yaAGC
# Do not "configure".
make
# Do not "make install".

(Note that while there is a 'configure' script provided, it is presently used only for setting up builds of a couple of now-obsoleted programs.  Therefore, it does not matter whether you run it or not, nor whether it succeeds or fails.)

You'll find that this has created a directory yaAGC/VirtualAGC/temp/lVirtualAGC/, which is same as the installation directory provided by the binary installer program, VirtualAGC-installer.  To match the default setup of the installer program, you would

mv yaAGC/VirtualAGC/temp/lVirtualAGC ~/VirtualAGC

(assuming you don't already have a directory ~/VirtualAGC/) and make a desktop icon called "Virtual AGC" that links to ~/VirtualAGC/bin/VirtualAGC.  The image normally used for the desktop icon is found at  ~/VirtualAGC/bin/ApolloPatch2.png.  At this point you would have something equivalent to what the binary installer would have provided, except that you would have no uninstaller program.

If you try to use the ACA simulation (joystick) and it doesn't work, read about configuring it.   And don't forget to read the prerequisites, the trouble-shooting tips, and the list of quirks for this platform.

FreeBSD

Development snapshots 20090405 through 20090421 could be built natively in PC-BSD 7.02 (based on FreeBSD 7.1), and snapshots 20090502 and after can be build natively on PC-BSD 7.1 (based on FreeBSD 7.2).  Other versions of FreeBSD may work, but I have no great confidence because my knowledge of FreeBSD is nil.

As mentioned above, I would not recommend installing the Linux binary version of Virtual AGC.  You may be able to run the installer, but if your experience is like mine you won't like what happens after that.  Thus you should build from source instead, according to the instructions in this section.

Here's the way I made it work, in PC-BSD 7.1 with its software-developer package group intalled:
You'll find that this has created a directory yaAGC/VirtualAGC/temp/lVirtualAGC/.  I'd suggest you should also

mv yaAGC/VirtualAGC/temp/lVirtualAGC ~/VirtualAGC

(assuming you don't already have a directory ~/VirtualAGC/) and make a desktop icon called "Virtual AGC" that links to ~/VirtualAGC/bin/VirtualAGC.  The image normally used for the desktop icon is found at  ~/VirtualAGC/bin/ApolloPatch2.png.  The end result of these manipulations is something identical to what the Linux binary installer would have produced except that it will actually work and that there won't be any uninstaller program.

If you try to use the ACA simulation (joystick) and it doesn't work, read about configuring it.   And don't forget to read the prerequisites, the trouble-shooting tips, and the list of quirks for this platform.

Solaris

Note that I've only tried OpenSolaris 0811.  In order to get development snapshot 20090503 (and hopefully beyond) to build, having no knowledge of Solaris, I had to do quite a lot of ignorant monkeying around.  When that happens, of course, there may be essential steps of the process that don't get recorded, or extra steps that are accomplished but serve no purpose.  I expect that any Solaris users are likely clever enough about their OS to figure these things out and let me know of deficiencies in my description. 

There are so many problems on Solaris right now that I'd hesitate to recommend using Virtual AGC in that environment.

At any rate, here are the one-time setup steps I performed:
After that, build Virtual AGC as follows:
You'll find that this has created a directory yaAGC/VirtualAGC/temp/lVirtualAGC/.  I'd suggest you should also

mv yaAGC/VirtualAGC/temp/lVirtualAGC ~/VirtualAGC

(assuming you don't already have a directory ~/VirtualAGC/) and make a desktop icon called "Virtual AGC" that links to ~/VirtualAGC/bin/VirtualAGC.  The image normally used for the desktop icon is found at  ~/VirtualAGC/bin/ApolloPatch2.png.  The end result of these manipulations is something identical to what a binary installer would have produced (if one existed), except that there won't be any uninstaller program.

Sadly, none of the ACA simulation (joystick) programs work in this environment, so you'll have no joystick controls.  But I suppose it's possible that this is just my test environment, which is a virtual machine, so you might have better luck than I.   And don't forget to read the prerequisites, the trouble-shooting tips, and the list of quirks for this platform.

Mac OS X

Note that personally I build the Mac OS X version of the Virtual AGC binaries in Linux rather than in Mac OS X.  Nevertheless, in development snapshot 20090415 and later, it's possible to build the Mac OS X version of Virtual AGC natively from Mac OS X 10.5.  I've only tried it in 10.5.6 (Intel) myself.  Anything I say below about building in 10.4 is pure speculation.  Note also that since I don't use this procedure myself, you can't expect that I try it out for every development snapshot.  Building the Mac version natively according to the instructions below gives you something functionally identical to the binary download package, except that you won't have the alternate joystick handler (yaACA), so if the primary joystick handler (yaACA3) doesn't work for your joystick model then you won't be able to use a joystick.

Note that most of the steps below are one-time setup, and that the actual build after setup is complete is quite simple.
  1. Mac OS X 10.5 includes wxWidgets 2.8.4, which in theory is too early a version.  Nevertheless, it appears to work and I won't quibble about it.  Mac OS X 10.4 includes wxWidgets 2.5, which is definitely (I think) not going to work, so you'll want to install wxWidgets 2.8.9 or later; probably you'll need to do this from source.
  2. SDL, which is needed for the joystick handler program (yaACA3) is also pre-installed, but I haven't figured out how to use it.  (Hint: if from a command line a program called "sdl-config" is in your PATH, you don't need to install SDL; if it isn't, then you do.)  So what I did was to download the source tarball, unpack it, configure it ("./configure"), build it ("make"), and install it ("sudo make install").  This puts SDL into /usr/local, where it won't conflict with your already-installed version.
  3. From a command-line, cd to some (preferably empty) working directory and unpack the Virtual AGC development-snapshot tarball ("tar -xjf yaAGC-dev-YYYYMMDD.tar.bz2"), thus creating a sub-folder called yaAGC/ containing the Virtual AGC source tree.
  4. Browse to the web to download the Terminator application's dmg file.
  5. Double-click the Terminator dmg file, and once it's open find the Terminator application ().
  6. Drag the Terminator application from the open dmg file to the working directory in which you created yaAGC/ in step 3 above.
  7. From a command line in that working directory, make a tarball from Terminator.app ("tar -cjvf Terminator.app.tar.bz2 Terminator.app").  Once you have the tarball, you can eliminate the Terminator app itself, along with its dmg file.
  8. From the working directory (not from within the yaAGC/ directory) you would build Virtual AGC using the command "make -C yaAGC MACOSX=yes".  In the  folder yaAGC/VirtualAGC/temp/, you should now find the VirtualAGC application ().
  9. If you like, drag the VirtualAGC application from yaAGC/VirtualAGC/temp/ to the desktop.  (It's better to drag rather than to use a 'cp' command, to make sure that Mac OS X admits that the folder is actually an application.)
  10. You're ready to go!
And don't forget to read the prerequisites, the trouble-shooting tips, and the list of quirks for this platform.

Windows

Note that personally I build the Windows version of the Virtual AGC binaries in Linux rather than in Windows.  However, Onno Hommes (thanks, Onno!) has worked out the build procedures, so for versions of May 2009 and later, you should be able to do a native build on Windows.  I have tried it only on Windows XP and Windows 7.  Since I have no interest in it myself, this capability is not tested for every development snapshot.  First-time setup of the Windows box is somewhat time-consuming, but the build is pretty easy after that.  I have information only on using open-source tools for this, and if you wish to use tools like Microsoft Visual C++ you'll have to work out the details for yourself.  (If you do, expect it to be easy to build the AGC and AGS CPU simulation programs and more difficult to build the various GUI interfaces such as the DSKY and DEDA.)

The trick is to install a Linux-like environment in which to build the Virtual AGC software; but the Virtual AGC software itself does not then need the Linux-like environment to run.  Here are the steps for first-time setup.  I fear that a certain amount of knowledge of UNIX-like systems is needed, so if you are a pure Windows person you may find that the following steps are more trouble to figure out than they are worth to you.
  1. Install the MinGW compiler, using the downloadable setup.exe file.  Use the default choices for installation directory, etc.  Among the options you should choose (if given the choice) are installation of the g++ compiler and of make.
  2. Install the Msys (Linux-like command shell) environment using the downloadable setup.exe file.
  3. Run Msys, to bring up a command shell.  If you are unlucky enough to have a Windows user name containing spaces, you will encounter difficulties.  For example, my home directory in Msys is "/home/Ron Burkey", and this messes up some of the build steps that need to be performed.  My solution to this was to create a directory called "/home/rburkey" and to 'cd' to that directory whenever starting up Msys.  It would also be wise to change the value of the HOME environment variable to reflect this change.  When I refer below to your "home directory", I mean whatever your equivalent of "/home/rburkey" is.
  4. Install the SDL library.  You should find that there is a download file specifically labeled as a Win32 development package for MinGW.  Within your Msys home directory, unpack the download file, 'cd' into the directory it creates, and run the command "make install-sdl prefix=/usr/local".  The /usr directory withing Msys will probably correspond to something like c:\msys\1.0\ in your Windows filesystem.   Note:  All software needed to build Virtual AGC will be installed under /usr/local, so eventually it will be populated with sub-directories such as /usr/local/bin, /usr/local/include, /usr/local/lib, and so on.  The Virtual AGC makefiles are hard-coded to assume these installation locations.  Note, however, that the Virtual AGC binaries you are going to create are not installed under /usr/local.
  5. Obtain a source tarball of wxWidgets.  At present, Virtual AGC binary packages are always built with wxWidgets 2.8.9, so 2.8.9 is a safe choice though it is not the only choice which works.  Unpack the tarball in your home directory, 'cd' into the directory this creates, and then do "./configure", "make", and "make install".  The "configure" step will accept various command-line options that select unicode vs. ansi, static linking vs. dynamic linking, etc., but the default options seem to work fine.
  6. Install POSIX Threads for Windows ("pthreads").  There may be a number of methods that work, but here is what I did:  Unpack the source tarball, 'cd' into the directory it creates, then run the command "make clean GC-inlined".  This creates various files that you should copy into /usr/local as follows:  copy *.dll into /usr/local/bin; copy *.h into /usr/local/include; copy the single libpthread*.a file created into /usr/local/lib and rename it libpthread.a.
  7. Install GNU readline for Windows.  You should find zipfiles of both "binaries" and "developer files" are available for download.  They should both be downloaded and unpacked into /usr/local.  (I.e., each zipfile contains directories like bin/, include/, lib/, and so on, and we want these to be merged into /usr/local/bin/, usr/local/include/, etc.)
  8. Install a regular-expression library.  The MinGW project has a "contributed" regex library ("libgnurx") that you can use.  Download both the "bin" and "dev" tarballs and unpack them into /usr/local.
If all of this was done correctly, you should now be able to build Virtual AGC, as follows:
  1. Unpack the development tarball in your home directory: "tar -xjvf yaAGC-dev-YYYYMMDD.tar.bz2".
  2. Build it: "make -C yaAGC WIN32=yes".
  3. On Windows 7  (but not on XP) I found it necessary additionally to copy c:\MinGW\bin\mingwm10.dll to yaAGC/VirtualAGC/temp/lVirtualAGC/Resources/.  Whether this is a difference between Windows 7 and XP, or whether it's some ghastly improvement to MinGW since the time I installed it last on XP, I can't say at the present time (and am not too motivated to figure out).
This will create a directory yaAGC/VirtualAGC/temp/lVirtualAGC/ which is the "installation directory".  When you download and run the Virtual AGC Win32 setup.exe file, this is the directory you get, except that the setup program copies "lVirtualAGC/" to "c:\Program Files\" and renames it "Virtual AGC".  In fact, this directory is relocatable, and you can move it wherever you like; nor does it need to remain within the Msys environment.  Whether you leave this directory in place, or whether you move it to Program Files, you really need to create a desktop icon in order to run the program.  The desktop icon should point to lVirtualAGC\bin\VirtualAGC.exe as the executable, and should use a "starting directory" of lVirtualAGC\Resources\.  The graphic normally used for the desktop icon is ApolloPatch2.jpg in the lVirtualAGC\Resources directory.

And don't forget to read the prerequisites, the trouble-shooting tips, and the list of quirks for this platform.

iPhone

For development snapshot 20090802 and later, it's possible to build yaAGC—not the entire Virtual AGC suite, just yaAGC—from (I guess) a Mac, if you've downloaded an iPhone development kit.  From the "I guess" in the preceding sentence, you'll probably be able to deduce that I'm just parrotting someone else's words and don't really know what I'm talking about ... and you'd be right.  The instructions and mods necessary to do it came from Alberto Galdo (thanks, Alberto!).  If you try it and it doesn't work, blame me for not implementing Alberto's instructions properly.  We'll zero in on it eventually.

To build, simply 'cd' into the yaAGC/yaAGC/ folder and do this:

make IPHONE=yes

As for how useful yaAGC by itself is, it's obviously only marginally useful until such time as there's a DSKY.  You should be able to do command-line debugging, however, so you could in theory run and debug AGC code.

Cross-Compiling

On the very-low-probability chance that somebody actually wants to know how to build the Windows and Mac versions on a Linux box, it's very simple to do.  It is, however, very wasteful of calendar time (if not personal time), computer resources, and bandwidth to set up the first time, so I would not advise you to do it on a lark:
  1. The oldest Linux on which I've made this work is Fedora Core 5, so presumably any newer Linux would be okay.  You will need the normal gcc C/C++ compilier toolchain, as well as developer packages ("dev" or "devel") for wxWidgets (2.8.9 or later), SDL, and Allegro.  These are all available in the package repositories of the recent common Linux distributions, though figuring out what the package names are can be an adventure.  Or, you can install them from source .
  2. Download the installation tarball for the Windows/Mac cross-compiling environment called I'm Cross!  Please use version 20090426 or later.
  3. In an empty directory (which for the sake of argument I'll call ~/Projects), unpack the I'm Cross tarball.  This will give you a directory called ~/Projects/IMCROSS/.
  4. Within ~/Projects/IMCROSS/ create a text file called Makefile.override-settings containing the following line:  "NO_SDL=".
  5. Install I'm Cross! using the instructions on the I'm Cross! website, noting in particular that you may have to install some additional software to insure that the Mac OS X tools and libraries are installed.  However, do not customize the I'm Cross! installation, since Virtual AGC is designed to accept the I'm Cross! defaults.  This is the part that takes a long time, and a lot of bandwidth and disk space.  The good news is that you can walk away from it and let it do its job unattended.
  6. Unpack the Virtual AGC development snapshot (yaAGC-dev-YYYYMMDD.tar.bz2) someplace.
  7. Browse to the web to download the Terminator dmg file.  In theory you may be able to 'mount' this in Linux, but I simply opened it in Mac OS X.  Inside, you'll find an application called "Terminator", which (considering the way Mac OS X works) is actually a folder called "Terminator.app".  Make a tarball from this ("tar -cjvf Terminator.app.tar.bz2 Terminator.app"), and copy Terminator.app.bz2 to the parent directory on your Linux box where you unpacked the Virtual AGC development snapshot.  (In other words, Terminator.app.tar.bz2 and yaAGC/ should be in the same directory.)
  8. Back on Linux again, 'cd' into the yaAGC/ directory created by unpacking the tarball.
  9. Do "make all-archs".
  10. In the directory yaAGC/VirtualAGC/, you'll find the binary-installation packages for Linux (VirtualAGC-installer), Windows (VirtualAGC-setup.exe), and Mac OS X (VirtualAGC.app.tar.gz).
The Windows/Mac binary packages you get this way are equivalent if not necessarily byte-for-byte identical to the ones I distribute.  However, the Linux binary package will be very different, and do not be fooled into thinking that it is as portable as the one I provide.  Very likely, it would work on only a very restricted range of Linux boxes.  The reason for this is that I've gone out of my way to create a very generic Linux system (with static as opposed to shared libraries to the extent possible) on which I build the distribution Linux installer for Virtual AGC.  If you want to know how to do that, the I'm Cross! website provides instructions.  It's considerably more time-consuming to set up than a standard I'm Cross! setup is.

Running the Validation Suite of the simulated AGC

Having installed the software as above, you can test the emulated CPU and DSKY using the "validation suite". 
  1. Run the VirtualAGC program, select "Validation suite" as the simulation type, and hit the "Run" button.
  2. A code of "00" will appear in the PROG area of the DSKY, and the OPR ERR lamp will flash.  This means that the validation program is ready to start.
  3. Press the PRO key on the DSKY.  The OPR ERR light will go off and the validation program will begin.
  4. There is no indication that the test is running.  The test takes about 77 seconds.
  5. If all tests are passed, then the PROG area on the DSKY will show the code "77", and the OPR ERR lamp will flash.  (The return code is 77 because 77 is the largest 2-digit octal number.  It is just a coincidence that the test duration is also 77 seconds.)
  6. If some tests fail, an error code other than "00" or "77" will be displayed in the PROG area on the DSKY, and the OPR ERR lamp will flash.
  7. In the latter case, you can proceed from one test to the next by pressing the PRO key.  The meanings of the error codes are determined by reading the file Validation/Validation.agc.
If this doesn't work for some reason, refer to the trouble-shooting info in the FAQ.

Some platform-specific oddities

Here are some strange things I noted when testing out the downloadable binary-installation packages on various target platforms.  I can't say whether these quirks would continue to exist if Virtual AGC was built from source.  Nor do I claim to have done a 100% test of all Virtual AGC features on each platform, since Virtual AGC is a pretty large and complex set of programs; in particular, I do not claim to have tested joystick operation with any thoroughness.  But if you have difficulties, you may or may not find some help for them below.


Last modified by Ronald Burkey on 2010-02-20.

Virtual AGC is hosted by ibiblio.org