Current Versions of Virtual AGC Downloads
Target Platform
Description
Download Version
Instructions
All platforms (but note that
Mac OS X doesn't currently have
workable build-instructions)
Complete source code
(Apps, AGC, and AEA)
Current Building from source
Windows, Mac OS X, Linux, Solaris,
or FreeBSD (32- or 64-bit 'x86)
VirtualBox virtual machine
(Apps and visual AGC
debugging)
2016-11-19, 900MB Using the VM
Ubuntu 14.04 (32-bit 'x86)
App-installer program
2016-11-16, 27MB Using Ubuntu installer
Raspberry Pi (Raspbian-Jessie)
App-installation tarball
2016-08-13, 12MB
Using Raspbian tarball

Contents

Introduction

This page covers various ways to download and/or install Virtual AGC project software.  Three methods are currently recommended, and a fourth is possible if not really recommended:

  1. If you simply wish to run one of the provided AGC or AEA simulations, examine the AGC or AEA program code, and/or do visual debugging of (Block II) AGC code, then the easiest thing to do is to download and run the provided VirtualBox virtual machine.  The VM is guaranteed to work properly on any 32-bit or 64-bit 'x86 platform for which VirtualBox is available, namely Windows, Mac, Linux, and Solaris, and (according to this page) FreeBSD as well even though the latter is not obvious from the VirtualBox website.
  2. If you just happen to have a computer system which is currently supported by an installation package, then you can simply download and install the proper installation package.  At present, however, these platforms are only the following:
    1. Raspberry Pi
    2. Ubuntu 14.04 32-bit 'x86.
  3. If you wish to do not only the above, but also wish to delve more deeply into the Virtual AGC project code (as opposed to just the AGC/AEA code), then you should instead download the Virtual AGC source code, and perhaps build it yourself.  This works on many more platforms, though is more-involved to set up, and visual AGC debugging may not be possible easily on platforms other than 'x86 Windows, Mac, or Linux.
  4. If you are satisfied with older versions of Virtual AGC, many additional computer platforms were once directly supported with installer programs, which you can still find here or here.  Ideally, we would like to directly support all major platforms with Virtual AGC installer programs, but in practice it is far too hard to do so with the resources available at present, so this is no longer being done currently.

Note that a lot of detail about known quirks on different platforms, and about trouble-shooting, can be found at the older links listed in approach #4 above, but isn't found on the present page.  That's because the information hasn't been updated in so long that its reliability is dubious, and because many of the platforms mentioned there are long-obsolete.  It should also be noted that the build-instructions for some platforms presented here are similarly out-of-date and may need corrections.

Downloading, Running, or Updating Virtual AGC in VirtualBox

Characteristics of the Virtual AGC VM

The approach described here should work with any host system supported by VirtualBox:  namely, any 32-bit or 64-bit 'x86 version of Windows, Mac, Linux, Solaris, or FreeBSD.  It's nice because it lets you work with the most-commonly-desired elements of Virtual AGC, while skipping past the most-annoying and tricky setup steps, such as compiling Virtual AGC's source code.  It provides you with a "virtual machine", with Virtual AGC and other things you need in order to be able to work with Virtual AGC already pre-installed and pre-configured.

When the VM is run, the first thing you see is the VirtualAGC GUI, from which you can run an AGC simulation using various selectable options, browse nicely syntax-highlighted AGC source code, or various other things.  In the screenshots below, you'll also notice a "website" desktop icon, which lets you browse to the website you happen to be looking at right at this instant not a big deal (you're already doing it, right?), but convenient for making downloads directly into the VM.




The other main thing the VM allows you to do is to work with the AGC source code in Code::Blocks.  Code::Blocks is an Integrated Development Environment (IDE), which means that you can edit the AGC source code and reassemble it ... but more importantly, it means you can visually debug it: i.e., single-step through the AGC code, examine AGC variables, and so forth, so that you can get a very intimate understanding of how the AGC code works, if that's something that interests you.  Most of the desktop icons in the images above are for debugging the various versions of AGC code in Code::Blocks.  For example, in the VM screenshot below, the Luminary 131 (Apollo 13 LM) code is being debugged, and the program is at line 379 (the EXTEND instruction) of the Fresh Start and Restart section of the code.



Okay, enough of the sales pitch already!  What's do you actually have to do to install the thing?

Installation of the Virtual AGC VM

It's hard to pin down exactly what computer resources you'll need to run the VM.  The minimum is probably around 2 GB of RAM and 12GB of free disk space, but the more of everything you have, the better.  In particular, you will have a far more satisfactory experience if your CPU has VT-x (Intel) or AMD-V (AMD) extensions.  The VM itself requires only about 5GB of disk space, but in the process of decompressing the downloaded VM, you'll temporarily need a lot more (hence the 12GB mentioned).

Before doing anything with Virtual AGC as such, you should take care of the following:

Then to actually install the VirtualAGC VM, you do the following.

  1. Download the current compressed VM, as listed at the top of this page.
  2. Uncompress it, resulting in a folder called "VirtualAGC-runtime".  This may (or may not) be a 2-step process, in which the .tar.7z file is first uncompressed into a .tar file, which in turn needs to be uncompressed to get the mentioned folder.  The .tar.7z (and .tar) file are no longer used after that and may be deleted ... though obviously we'd prefer you retained it for a while to make sure you don't need to download it again if some mishap occurs.  VirtualBox tends to store all of its virtual machines in the same folder (on Linux, for example, that folder is "~/VirtualBox VMs"), so although it's not necessary to do so, you might want to move the VirtualAGC-runtime folder into the corresponding "VirtualBox VMs" folder on your computer.
  3. In whatever file-system browser your computer has, descend into the VirtualAGC-runtime folder, and double-click the mouse on the file VirtualAGC-runtime.vbox.  This makes VirtualBox aware of your VM, and may or may not actually immediately run it.  At any rate, the VM will be visible in VirtualBox's manager program, and you can run it from there.

In its as-downloaded form, the VM is typically configured to use 1GB of RAM and 2 CPU cores.  You can dial these settings down in VirtualBox, but you may need to scale your expectations at the same time.  For example, with 512GB of RAM and 1 CPU core, you may find that simulation and debugging works perfectly fine, but browsing the source code may be miserable, due to the fact that modern browsers (Mozilla Firefox is what's included in the VM) take enormous amounts of RAM.

Note that username and password for the VM are both "virtualagc".  Since you are automatically logged in whenever you run the VM, you don't normally need this information, but it's good to know just in case (for example) you ever need to install some new, non-Virtual-AGC software on it, or perform some other administrative action.

Updating the Virtual AGC VM

Because the VM is such a large download, you don't want to have to download it every time there's updated Virtual AGC software!

Because the VM is based on 32-bit Ubuntu 14.04, which (surprise!) happens to be one of the target platforms supported directly by a Virtual AGC installer program, the updating the VM to new Virtual AGC versions is generally quite simple.  Do all of the following from within the VM itself:

  1. Exit from the VirtualAGC program, if it's running in the VM.  (In other words, we just want the VM desktop, without any programs running on it.)
  2. Download the current Virtual AGC Ubuntu 14.04 32-bit installer, as listed at the top of this page.
  3. Make the VirtualAGC-installer executable:  right-click on it, and on the pop-up list that appears choose Properties/Permissions, and change the Execute setting to "Only owner".
  4. Double-click VirtualAGC-installer to run it, accepting all of the defaults offered to you by the installer program.

Platforms Directly Supported by Virtual AGC Installers

Virtual AGC Installer for Raspberry Pi (Raspbian)

Installation is trivial:
  1. Download the current Raspberry Pi installation tarball, as listed at the top of this page.
  2. Unpack the installation tarball somewhere:  "tar --bzip2 -xvf VirtualAGC-Raspbian-VERSION.tar.bz2".
This gives you a directory called lVirtualAGC/.  To run the program, simply do the following from the command line, or set up a desktop icon that does the equivalent:
sudo apt-get install libwxgtk2.8-0 libsdl libncurses5 liballegro4 tk
cd lVirtualAGC/Resources
../bin/VirtualAGC

Installer for Ubuntu 14.04 32-bit 'x86 Linux

Installation:
  1. Install the following system libraries from the Ubuntu repository:  tk, libsdl1.2, libncurses5, liballegro4.4, libgtk2.0, libwxgtk2.8.
  2. Download the Virtual AGC Ubuntu installer, as listed at the top of this page.
  3. Make the VirtualAGC-installer executable:  some ways of doing that are to change its desktop-icon properties permissions to "executable", or to do "chmod +x VirtualAGC-installer" from the command line.
  4. Double-click VirtualAGC-installer to run it.
A desktop icon called "Virtual AGC" will be installed unless you deselect it.  Additionally, a program group will be placed on your desktop start menu called "Virtual AGC", and it will contain both the VirtualAGC program and an uninstaller program.  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.

Downloading and Building Virtual AGC from Source

Limitation

Building Virtual AGC from source actually has a limitation compared to running the VM as described above, which is that while the VM is already set up for visual debugging of AGC code using Code::Blocks, this capability is not a part of Virtual AGC proper.  That is, Code::Blocks based AGC debugging has its own set of installations, requirements, and setups, distinct from those of building Virtual AGC proper ... which is what's discussed below.  If (once Virtual AGC is built and working satisfactorily) you want to do visual debugging, you need to install Code::Blocks and should consult the instructions for development using Code::Blocks on our GitHub wiki, as well as the instructions for visual debugging.

Getting the Source Code

The complete up-to-the-moment source code is available from GitHub.  There are several ways which one might choose to download it, such as in a zipfile or using the 'git' program, which in Linux (for example) would look like this:

git clone https://github.com/virtualagc/virtualagc

In either case, you end up with a folder called virtualagc. 

What you do with it after that depends on which platform you intend to run Virtual AGC on, and that's the topic of the next few sections.  It's also possible that the instructions at the GitHub repository may (or may not) be more up-to-date than those here.

Linux


This works!
Last verified: 2016-11-23

These instructions apply to building Virtual AGC on Ubuntu-like systems, but are probably directly applicable to most Ubuntu, Debian, or Mint desktop systems.  They are known to work on 64-bit Linux Mint 17.3 and 32-bit Ubuntu 14.04.  If you have a Linux distribution with a different kind of packaging system, such as Fedora, you'll probably have to adapt the first step somewhat.

One-time setup:

Building Virtual AGC:

This process creates a desktop icon from which you can run Virtual AGC.  In some versions of Linux, you will need to right-click the icon and indicate that it is "trusted" before it will work properly. You can "uninstall" by removing the icon, the ~/VirtualAGC folder, and the source-code directory you downloaded from GitHub.

Raspberry Pi (Raspbian)


This works!

This really isn't any different from building it on any other Linux system, but I'll go through the steps for you anyway in a bit more detail, for a completely clean Raspbian installation.  Laszlo Morocz provided the original instructions.  They have been tested with Raspbian-Jessie.  Note that while not a requirement, the building process goes a lot faster if you do it on (say) a physical hard disk on the USB port, rather than on the standard SD card.

One-time setup:

sudo apt-get install wx2.8-headers libwxgtk2.8-0 libwxgtk2.8-dev libsdl-dev libncurses5-dev liballegro4-dev git
git clone https://www.github.com/virtualagc/virtualagc

Building Virtual AGC:

cd virtualagc
make install

or perhaps "make clean install" instead.  (No 'sudo' should be used.)  This process creates a desktop icon from which you can run Virtual AGC.  You can "uninstall" by removing the icon, the ~/VirtualAGC folder, and the source-code directory you downloaded from GitHub.

FreeBSD


This works!
Last verified: 2016-11-23

The instructions here relate to building Virtual AGC using PC-BSD 10.3, desktop version.  That isn't the latest version of FreeBSD (version 11), but it's much easier to install than FreeBSD proper, and should be 100% equivalent for the same version numbers.  At any rate, I know nothing about FreeBSD, so my instructions may not be the most-efficient ones.  The executive summary is that the build process works, and VirtualAGC acts normally once built. 

Setup:
  1. Install 'cmake' and GNU 'make' (gmake) using the "package" system, with the command "sudo pkg install cmake gmake".
  2. Install the "ports" system, if you haven't already.
  3. Install wxWidgets 2.8.12, or as close to that 2.8.x version as you can get, using the "ports" system:  "cd /usr/ports/x11-toolkits/wxgtk28" and "sudo make install".
  4. For whatever reason, the 'wx-config' program is installed with a different name.  Make a symbolic link with the proper name for it somewhere in your path:  "mkdir $HOME/bin" and "ln -s /usr/local/bin/wxgtk2u-2.8-config $HOME/bin/wx-config".  If you test this with the command "wx-config --list", you should see that the default wxWidgets configuration is "gtk2-unicode-release-2.8".
  5. Download Allegro 4.4.2, or as close to that 4.4.x version as you can get.  Prior to building Allegro, I had to do this: "sudo ln -s /usr/local/lib/libasound* /usr/lib"; I'm sure there's a much cleaner way to handle that problem (namely, that Allegro couldn't find libasound), but I don't know what it is.  To build and install, do this:

Building Virtual AGC:

This process creates a desktop icon from which you can run Virtual AGC.  You can "uninstall" by removing the icon, the ~/VirtualAGC folder, and the source-code directory you downloaded from GitHub.

Solaris


This works!
Last verified: 2016-11-23

The instructions here relate to building Virtual AGC using Solaris 11.3.  Note that my knowledge of Solaris is mid-way between "completely ignorant" and "dangerously misinformed", so you have to take what I say with a grain of salt.  Nevertheless, the executive summary is that the instructions do work.

One-time setup:
  1. Install Oracle Developer Studio tools.  I used version 12.5, and only installed the tools rather than the complete IDE.  This is to give you the C and C++ compilers ('cc' and 'CC'), which have command-line options required by wxWidgets but not supported by 'gcc'.
  2. Install the Open CSW system, add /opt/csw/bin to your PATH, and /opt/csw/lib to LD_LIBRARY_PATH.
  3. Install wxWidgets via the Open CSW system.
  4. Install gtk2, tcl-8, tk-8, ncurses, freeglut, cmake, and gnu-grep using the Package Manager.

Build Virtual AGC:

This creates a Virtual AGC launcher (which is actually just a shell script) on the Desktop, and you can run Virtual AGC from that.  If it asks you whether to "Run" or "Run in terminal", the proper choice is "Run".  Unfortunately, no icon gets associated with the launcher, but you can optionally associate one by right-clicking on the launcher, selecting Properties, and using ~/VirtualAGC/Resources/ApolloPatch2-transparent.png as the image.

You can "uninstall" by the deleting the desktop launcher, the  ~/VirtualAGC folder, and the source-code directory you downloaded from GitHub.

Mac OS X


This fails!

This section relates to building Virtual AGC on Mac OS X Lion (10.7), with Xcode 4.6.3.  The executive summary is that the compilation all works, but that I am not forming the "app" folder structure properly, apparently, so right now the programs have problems running even though probabaly built correctly.

Note that both the Mac OS X and Xcode versions are both very far behind the times ... but they're the latest that can be installed on the newest Mac I have, and unless somebody wants to give me a newer one for free, that's the last Mac I'll ever have.  So these instructions may or may not work on your Mac.  Similarly, the README file at GitHub may or may not contain useful information on building in newer versions of Mac OS X.  Let me know if you have a better build procedure than I do.

Setup:
  1. Install most-current version of Xcode for your version of Mac OS X ... of course!
  2. Install MacPorts.
  3. Use MacPorts to install wxWidgets 2.8.12:  "sudo port install wxgtk-2.8" or "sudo port install wxWidgets-2.8", depending on your Xcode version.
  4. Use MacPorts to install cmake:  "sudo port install cmake".
  5. Install Allegro 4.4.2:

Building Virtual AGC:

  1. 'cd' into Virtual AGC source directory, as obtained from GitHub.
  2. Determine where wxWidgets was installed by using the command "port contents wxgtk-2.8 | grep /bin/" (or "port contents wxWidgets-2.8 | grep /bin/").  What you're actually trying to find out is the directory in which the program 'wx-config' is installed.  In my case, I found that the location was /opt/local/Library/Framework/wxWidgets.frameworks/Versions/wxGTK/2.8/bin.  You have to add that to your PATH, so that the 'wx-config' program can be found during the build.  The command is "export PATH=$PATH:/opt/local/.../bin".  You can test that it worked with a command like "wx-config --list", from which we would like to see that the default configuration is "gtk2-unicode-release-2.8".  By the way, unless you make this change to the PATH permanent, the PATH will be reset back to the default one as soon as you close the command-line terminal you're using for this.
  3. Do "make MACOSX=yes install" or "make MACOSX=yes clean install".
The result is that a new app icon appears on the desktop, and you can launch Virtual AGC from that.

The process above works, but for some reason the VirtualAGC.app folder structure is no longer formed correctly.  You can run VirtualAGC, but none the other stuff it's supposed to control (like browsing the source code or running a simulation) works, due to the malformation mentioned.  Once that's fixed, I suspect that it will run properly.

Windows


This works!
Last verified: 2016-11-23

This section relates to building Virtual AGC on 64-bit Windows 7, though the procedure doesn't seem to have anything in it that's specific to that version of Windows.  (It's merely that I've only tried it on Windows 7.)  The building process uses MinGW/Msys (as opposed to Visual Studio), and I don't know whether or not there is a valid Visual Studio build process.

First-time setup of the Windows box is somewhat time-consuming (but building Virtual AGC is pretty easy after that):
  1. Install the MinGW compiler and the Msys Linux-like command-line development environment, using the downloadable "MinGW Installation Manager".  This installation program changes over time, so I cannot tell you precisely how to use it, and can only give you a general idea.  Use the default choices for installation directory (c:\mingw) and other settings, if any are offered.  Note that by default, the batch file c:\mingw\msys\1.0\msys.bat is what's used to start the Msys command shell as in the next step below, and you might want to manually create a desktop icon or a Windows start-menu entry for running that batch file.  If you are unlucky enough to have a Windows user name containing spaces, you will encounter difficulties.  The instructions at the www.mingw.org website explain what to do in that situation.  Specific packages which you need to install using the MinGW Installation Manager, at least at this writing, which may not be among the defaults are:
  2. Run Msys, to bring up a command shell.  All of the following steps occur within this command shell and not at a "DOS" command line.  Some of the "DOS" commands you probably are familiar with (such as "dir") don't work in this shell, while Linux-type replacements ("ls -l") are used instead.  Some commands, like "cd", work almost the same way, though there are subtle differences. Also, '/' is the separator for folders in path-names, rather than '\'.  Google for "bash" if you're interested in these kinds of differences. 
  3. Install the SDL library, version 1.2.  You should find that there is a download file specifically labeled as a Win32 development library for MinGW.  Within your Msys home directory, unpack the download file, 'cd' into the directory it creates.  Do "mkdir /usr/local", and run the command "make install-sdl prefix=/usr/local".  (The /usr directory within Msys will probably correspond to something like c:\mingw\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, because while the Virtual AGC apps are being created using Msys, Msys is not needed to run them ... they are simply Windows programs like any other.
  4. Obtain a source zipfile of wxWidgets, version 2.8.12, or as close to this 2.8.x version as is available.  Of the several varieties offered for download (wxAll, wxMSW, wxGTK, ...) chose wxMSW, and make sure you get the source code rather than an installer program.  Unzip the downloaded file in your home directory, 'cd' into the directory this creates, and then do "./configure --enable-unicode", "make", and "make install".
  5. Though it has nothing to do with building Virtual AGC, if you want to have access to Stephen Hotto's contributed Lunar Module accessories when you run Virtual AGC, you'll also have to install Tcl/Tk
Once this one-time setup is complete, you should now be able to build Virtual AGC as follows.  As above, all of the following steps take place in the Msys command shell, and not from a "DOS" command line:
  1. Get the Virtual AGC source code from GitHub (from the link at the top of this page), either by using 'git', if installed on your computer, or by downloading a zipfile and unzipping it.  For the sake of discussion, I'm going to suppose that the folder you get from doing this is called "virtualagc" and is in your home directory.
  2. Do "cd virtualagc".
  3. Build it: "make WIN32=yes install" or "make WIN32=yes clean install". 
This process creates a Desktop launcher for Virtual AGC (actually, it's just a batch file on your Desktop), and you can run Virtual AGC from that launcher.

You can "uninstall" simply by removing the desktop icon and %HOMEPATH%\VirtualAGC, and whatever source-folder you downloaded from GitHub.

iPhone


Still okay?

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.

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 Resource Issues on Slower Computers, Such as Raspberry Pi

On new but slow computers like Raspberry Pi, or old computers such as PowerPC-based Macs, the CPU utilization for Virtual AGC can be rather high.  Indeed if you ran every available option on an early-model Pi, you could find yourself using close to 100% of the CPU.  For the default configuration of VirtualAGC (Lunar Module AGC with DSKY and Telemetry but without abort system or IMU), I find the following:

If that's too much for you, there are some things you may be able to do to make it more efficient.  First, note that the VirtualAGC program — which isn't a component of the simulation, but merely a convenient graphical interface so that you don't have to memorize command-line options for the actual components — actually takes 25-30% of the CPU (for either of the two Pi models mentioned above) all by itself.  You don't really need to run it if you don't want to.  But how do you run a simulation easily without VirtualAGC?  Well, if you run the simulation just once from VirtualAGC, and exit the simulation immediately after starting it, you'll find that it has automatically created a script called "simulate" which can be used to start that exact configuration of the simulation without running VirtualAGC itself.  As a result, you get CPU utilizations closer to 50% or 10%, respectively, on the two Pi models mentioned above.  To just run that script, you do this:

cd VirtualAGC/temp/lVirtualAGC/Resources
./simulate


Last modified by Ronald Burkey on 2016-11-23.

Virtual AGC is hosted
              by ibiblio.org