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.

All platforms: Install Tcl/Tk
if not already
installed. I don't know how pervasive a problem it is—i.e., which
operating systems or versions of Tck/Tk
it affects—but in recently trying to install Tcl/Tk on Microsoft Vista, I found
that the installation program does not create a file called "wish.exe",
but instead creates a file called "wish85.exe". This prevents
certain features of Virtual AGC from working. In the case of
Windows Vista, I fixed it by duplicating the file
"c:\tcl\bin\wish85.exe" and calling the duplicate
"c:\tcl\bin\wish.exe". Sorry about this, but I don't honestly see
what I can do about it.

Linux: The X-Window
system, xterm, and gtk+ libraries must
be installed.

Operating systems:

Mac OS X:

10.4 and later, Intel and PowerPC, are believed to work.

10.2 or
prior is known not
to work.

Windows:

XP is known to work.

Vista and Windows 7 are known to work but various workarounds need
to be applied and some patience may be needed.

Windows 98 or prior is known not to work.

Only 32-bit systems were tried; the behavior on 64-bit
systems is unknown.

Others (2000) are untried and unknown.

Linux 'x86:

Fedora Core 4 and later versions are believed to work; Fedora
Core 1 is known not
to work.

Ubuntu 7.04 and later versions are believed to work.

SuSE 10.1 and later versions are believed to work.

Both 32-bit and 64-bit systems seem okay.

Other distributions and earlier versions of those listed
above: untried and unknown.

FreeBSD:

Currently, I am working only with PC-BSD 7.1, which is based
on FreeBSD 7.2. In the past it worked also with PC-BSD 7.02,
which is based on FreeBSD 7.1. There is no binary package for
this
platform, but if built from source it seems to work.

OpenSolaris:

Currently, I am working only with OpenSolaris 0811.
There is no binary package for
this
platform, but if built from source it partially works. I'm not
satisfied with it at this point.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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:.

Copy the contents of InstallDir/Resources/SyntaxHighlight/CodeBlocks/lexers/
to the lexers/ folder of your Code::Blocks
installation:

For a default Linux installation:
"/usr/share/codeblocks/lexers".

For a default Win32 installation: TBD.

For a default Mac OS X installation: TBD.

Run Code::Blocks.

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.

Configuration of AGC toolchain:

From the main menu, select Settings/Compiler-and-debugger.

In the Global-compiler-settings section:

Make sure that "GNU gcc Compiler" is the "Selected compiler".

Click the "Copy" button and in the "Add new compiler" pop-up
window that appears, choose the name "AGC yaYUL Assembler".

In the "Compiler Flags" tab, make sure that no flags are
enabled.

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".

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.

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:

I installed wxWidgets
2.8.9 from source into /usr/local. You have to do something
beyond my understanding to get the system to find libwx*.so* at
runtime. I managed to monkey it into working, but I'm not sure
what I did, and you FreeBSD users are unlikely to care about my wrong
methods anyhow. Please let me know the answer if you find one.

I installed GNU readline 6.0 from source into
/usr/local. (As a BSD kind of person, you may be tempted to
install the BSD-licensed editline
library instead, but it is not fully feature-compatible and cannot be
used.)

I cd'd into the yaAGC/ directory and built ("gmake
FREEBSD=yes"). Donot "configure"
and donot "gmake
install".

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.

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:

I installed (or happily accepted the pre-installation, as the
case may be) the following packages, using the package system:

I installed wxWidgets 2.8.9
from source into /usr/local, configuring with "configure
--disable-shared". (While there is a package called SUNWwxwidgets
which
can be installed from the package system, in the version I tried the
switches produced by `wx-config --cxxflags` are incompatible with gcc, so I eliminated it. Your
luck might be better.) The Virtual AGC makefiles are simply going
to take the first wx-config
found in the PATH, so the present makefiles may be too simple for you
if you have more than one version of wxWidgets
installed.

I installed Allegro 4.2.2 from source into
/usr/local, configuring as "configure --enable-shared=no
--enable-static=yes".

I put /usr/local/bin into my PATH, or otherwise somehow get
/usr/local/bin/wx-config linked into your PATH.

Then 'cd' into the yaAGC/ directory and build ("make
SOLARIS=yes"). Donot "configure"
and donot "gmake
install".

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.

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.

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.

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.

Double-click the Terminator
dmg file, and once it's open find the Terminator
application ().

Drag the Terminator
application from the open dmg file to the working directory in which
you created yaAGC/ in step 3 above.

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.

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 ().

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.)

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.

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.

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.

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.

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.

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.

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.)

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:

Unpack the development tarball in your home directory: "tar -xjvf
yaAGC-dev-YYYYMMDD.tar.bz2".

Build it: "make -C yaAGC WIN32=yes".

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.

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:

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 .

Download the installation tarball for the Windows/Mac
cross-compiling environment called I'm Cross! Please use
version 20090426 or later.

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/.

Within ~/Projects/IMCROSS/ create a text file called
Makefile.override-settings containing the following line:
"NO_SDL=".

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.

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.)

Back on Linux again, 'cd' into the yaAGC/ directory created by
unpacking the tarball.

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".

Run the VirtualAGC
program, select "Validation suite" as the simulation type, and hit the
"Run" button.

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.

Press the PRO key on the DSKY. The OPR ERR light will go
off and the validation program will begin.

There is no indication that the test is running. The test
takes
about 77 seconds.

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.)

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.

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.

Very slow machines.

You may find that the simulation uses >100% of the available
CPU, particularly if the Tcl/Tk-based
LM-Simulator component is
being used. I fear that the only workaround for this at present
is to turn off the interfaces of the simulation which you don't need.

You may find that the simulation (and particularly LM-Simulator) aborts at startup,
possibly with a pop-up box indicating that there is a failure to
connect to yaAGC. This
problem is caused by the time needed to start the various program
components. You can introduce extra delay before these checks are
performed by editing a pair of files in the installation directory (by
default, ~/VirtualAGC/Resources in Linux, c:\Program Files\Virtual
AGC\Resources in Windows, or
~/Desktop/VirtualAGC.app/Contents/Resources in Mac OS X). In the
file SimStop, change "sleep 5" to "sleep 30". In the file
VirtualAGC.tcl, change "after 5000" to "after 30000". These
change some 5-second delays to 30 seconds.

Networking must be properly configured, even though Virtual AGC
does not by default communicate with other computers, because Virtual
AGC uses TCP ports which Virtual AGC uses to interconnect the various
bits and pieces of the simulation. So if you don't have a network
card or wireless, it may be difficult to get Virtual AGC to work.
Specifically:

If you have SE Linux (or I guess, the equivalent security
features in Windows/Mac OS X) enabled, it may block Virtual AGC from
using networking as being an untrusted application. (I believe
that most modern Linux distributions, such as Fedora, enable SE Linux
functionality by default.) Personally, I have no need for SE
Linux , so I always just completely disable it, and hence I can't give
you much additional insight into details
about reconfiguring it, but I presume there's some way to identify the
bits and pieces of Virtual AGC (namely VirtualAGC, yaAGC, yaAGS,
yaDSKY2, yaDEDA2, yaTelemetry, and Tcl/Tk) as being trusted
applications.

If you have a personal firewall software enabled, it may block
the TCP
ports which Virtual AGC uses. The ports in
question are (by default) 19697-19706, 19797-19806, and
19897-19906. I generally just disable personal firewalls on my
computers since I'm always behind a physical firewall anyway, but
usually there's some sort of a GUI configuration program you can run to
open holes in the firewall for specific TCP ports.

By default, it is generally possible when making network
connection to refer to a computer either by the host name you assign it
when you install the operating system, or by the default name
"localhost". Virtual AGC uses the latter. I am told that
there are some conditions, possibly having to do with the use of
wireless (though the problem has been reported to me as a problem with
the Network Manager on Fedora 11 Linux), in which the computer cannot
be accessed using the default name "localhost". Hence Virtual AGC
fails. In Linux, this can be gotten around by adding the line
"127.0.0.1 localhost" in the file /etc/hosts. (If the line
"127.0.0.1 something" already
exists, then just add "localhost" to the end of it.) I presume
that you can diagnose both the problem and verify the fix by trying
"ping localhost" from a command line. Thanks to Onno Hommes for
pointing out this problem and the fix for it.

Linux, installed from binary package

Fedora Core 1—the VirtualAGC
binary distribution is unusable on Fedora Core 1. I believe that
a build from source does work.

Fedora Core 4, 32-bit—no oddities noted.

Fedora Core 5, 32-bit—no oddities noted.

Fedora 10, 32-bit—some odd fonts and odd positioning of text
was noted, but nothing that would make Virtual AGC unusable.
Fedora 10 is extremely odd in that it does not install xterm by default, and if you don't
install it yourself you'll find that a number of VirtualAGC features don't
work. (Thanks to Onno Hommes for noticing this!) I also
have a report that the joystick configurator does not work properly
even when xterm is added, but
it worked for me.

Ubuntu 7.04, 32-bit—no odditites noted.

Ubuntu 8.04, 64-bit—no oddities noted.

Ubuntu 8.10, 32-bit—no oddities noted.

OpenSUSE 10.1, 32-bit—no oddities noted.

OpenSUSE 11.1, 32-bit—the KDE 4 desktop system refused to admit
that the installer program (VirtualAGC-installer)
was an executable program, so it was necessary to run the installer
from the command-line rather than by clicking on its desktop
icon. Moreover, the installer could not be run unless a software
package called "itcl" (which is present on the OpenSUSE distribution
disk) was installed. Fortunately, the installer ran normally, and
the KDE 4 desktop did recognize VirtualAGC
itself as an executable program after installation. Positioning
of text in some of the VirtualAGC
screens was somewhat unusual, but not unusable.

Windows, installed from binary package

Windows 95, 98—VirtualAGC
is unusable on Windows 95 or 98, even if it could be built from source
there. The reason is that none of the batch files created by
Virtual AGC are compatible with the command shell in Windows 95 or
98. It is possible that individual programs like yaAGC or yaDSKY2 may be usable there if
controlled from the command line rather than from the VirtualAGC GUI, but I no longer have
any means of verifying or denying this.

Windows 2000—unknown.

Windows XP—

Windows will sometimes (but not always) pop up a warning
window asking whether it should "block" or "unblock" yaAGC or yaAGS—presumably because they are
servers and therefore might do Very Bad Things to your computer.
I think the only thing the "block" does is to prevent network access
via a firewall, and since usually all of your Virtual AGC servers and
clients are running on the same computer anyway, it doesn't really
matter whether you block or unblock: it seems to work fine either way.

Some of the programs (such as the telemetry
monitor) may not always be closable from the operating-system-supplied
controls around the border of the windows. However, they will
close down normally if (for example) you close the DSKY.

The yaACA
program is unusable, because if its window loses focus it is unable to
access the joystick thereafter.

Windows always
displays a message when yaACA2
shuts down that it has experienced "a problem" and asks whether or not
you want Microsoft informed. Well, I don't know why the message
appears, but yaACA2 seems to
work well enough for our purposes. Neverthless, if the message
annoys you, you should use the default yaACA3
anyway (assuming that it works for you).

The main GUI programs (yaDSKY2,
yaDEDA2, yaTelemetry) don't seem to produce
any console output, so if you run them from a command line—say,
"yaDSKY2 --help"—you won't see any messages. I believe that you
may still be able to see something if you pipe the output into a
file—as,
for example, "yaDSKY2 --help >temp.txt".

The "debug" mode for
the yaAGS
program displays no prompt, but otherwise seems to work properly.

The "debug" mode for
the yaAGC
program sometimes displays garbage characters upon pressing keys at
startup. However, the commands being entered by the keystrokes
are interpreted correctly and after executing a command or two it
settles down and works properly.

If using the command-line debug modes for yaAGS or yaAGC, their terminal windows will
not close automatically when the other windows close, nor will yaAGC or yaAGS be halted. You'll have
to close those windows manually.

Windows Vista and Windows 7—I do not
have dedicated Windows
Vista or Windows 7 machines on which to
perform testing. However, because of the continued complaints
I've received about Vista, I have been able to do some limited testing
with Windows Vista Home Basic and with the Windows 7 Release
Candidate. Additionally, I have received some notes on this
subject from users
of my Project Gutenberg
Prettifier, GutenMark,
whose programs are constructed using
techniques similar to Virtual AGC. So here are some things that
may or
may not be useful to note:

Jim Adcock (thanks, Jim!) sent word that it was
necessary to change the properties of all of the .exe files in
the bin/ sub-directory of the installation directory (by default,
"c:\Program files\VirtualAGC\bin') to "Run
as Administrator". I personally did not find it necessary to do
this for Virtual AGC.

A user identified only as "Wendl" (thanks, Wendl!) sent word
that it was additionally necessary to change the properties of the .exe
files to select compatibility with XP Service Pack 2. I
personally did not find it necessary to do this for Virtual AGC.

Brendan O'Rourke (thanks Brendan!) has pointed out that an
error "Cannot create file simulation.bat" occurs when trying to run the
simulation. I have found that this may not happen at first,
but may begin happening after Windows is shut down and then restarted
again later. The problem appears to be that Windows is not
consistent in the permissions you are given, so you are fooled into
thinking that Virtual AGC works, but only later find that you don't
have the proper permissions to run it. Here is the fix:

File dialogs may not open to the proper folders. For
example, in trying to select a source-code file to assemble, I've found
that the file dialog opens at Resources\scenarios, whereas it is
supposed to open at Resources\source.

The command-line
debug modes for yaAGC and yaAGS may sometimes display garbage
at first when you type at the keyboard, though eventually starts
properly displaying keystrokes. Unfortunately, unlike other
versions of Windows in which this is merely an annoyance, in Vista/Win
7 it may instead cause the simulation to abort. I've had pretty
good luck working around this by hitting a few carriage returns before
typing in the first actual debugging command.

Windows, natively built from source

The yaACA3
joystick-handler program cannot display the joystick readings, and
therefore is hard to configure using the "Handler" functionality.
(Also, after trying to configure it with "Handler", it remains running
rather then being closed down, and you have to manually terminate it by
using ctrl-alt-delete to bring up a process list.) In spite of
these quirks, it does actually work properly when running a simulation.

AGC/AGS program listings may or may not align at the proper
tab-stop positions when viewed in a browser.

Mac OS X, installed from binary package

All—Mac OS X insists on opening all of the windows (DSKY,
DEDA, telemetry monitor, etc.) exactly atop each other, so that on each
run you have to manally move the windows around in order to see them.

10.2 and prior—the VirtualAGC
binary distribution is unusable on these platforms.

10.3.9 and 10.4.11 (PowerPC)—

The IMU (LM-Simulator)
does not seem to respond to the hand-controller (yaACA3), even though both of them
appear to work individually. This may have something to do with
the fact that the iMac I'm running it on is old and very slow.
(The simulation takes >100% of the CPU time.)

The AGS/DEDA pair of programs seems to intermittently freeze
up and require rebooting. I suspect that this is because on the
old 400 MHz G3 I'm using the CPU loading is at 300%, and there are some
timing requirements on AGS/DEDA communications that aren't being
met. But I'm not sure, and it could be a different bug.

10.3.9 (PowerPC)—

The file-save and file-open
dialogs for core-dump saves and opens, and for Digital Uplink, refuse
to navigate to
the proper directory (by default,
~/Desktop/VirtualAGC.app/Contents/Resources/scenarios/);
it may be advisable to copy or link this directory to the Desktop or
some other
accessible location if you wish to use these features.

Can't run yaAGC or yaAGS in --debug mode from VirtualAGC.

10.5.6 (Intel)—In spite of my best efforts, I've seen instances
in which the LM-Simulator portion of the
simulation suite does not shut down when the remainder of the
simulation shuts down, and needs to be terminated manually from its
menu.

Even on my fastest box (which is a Core Duo Mac Mini), LM-Simulator runs at fractional
speed, and is therefore useless (whilst the remainder of Virtual AGC
proper is running fine at full speed). I suspect an
incompatibility in Tcl/Tk.

The "debug" mode for the
yaAGS
program displays no prompt, but otherwise seems to work properly.

The "debug" mode for the
yaAGC
program sometimes displays garbage characters upon pressing keys at
startup. However, the commands being entered by the keystrokes
are
interpreted correctly and after executing a command or two it settles
down and works properly.

Mac OS X, built natively from source

The "Retro" display mode of the yaTelemetry program may not work.

FreeBSD, natively built from source.

For joystick handling, yaACA3
works, but yaACA2 and yaACA do not.

There is some unusual horizontal positioning in some text which
is supposed to be centered.

The crossed-out sub-items are observations of problems which I
no longer observe.

When running yaAGS in
command-line debug mode, there is no command-line prompt, except that
one appears sometimes after
hitting the carriage-return. Nevertheless, it seems to work
properly otherwise.

Source browsing does
not seem to work from VirtualAGC,
because the paths to the
html files (which exist!) aren't constructed properly.

Nor does
assembly of source code from VirtualAGC work, presumably for the
same reason (badly-constructed paths).

What success I had was with PC-BSD 7.1. I was previously
able to build on PC-BSD 7.02, but have not had a working setup for a
while to see if it still works in 7.02.

Solaris.

Only OpenSolaris 0811 has been tried.

There is some unusual horizontal positioning in some text which
is supposed to be centered.

No joystick-handler program is available. (yaACA2 doesn't build, while yaACA and yaACA3 build but don't work ... at
least for
me.)

Redrawing of graphical objects seems intermittent. For
example, some digits on the DSKY might get updated, and others might
not.

The telemetry-display program never displays any telemetry.

In command-line debug mode, yaAGC
and yaAGS spontaneously abort
and end the simulation.

Sometimes there is a spurious i/o command; for example, when
running the "validation" program on the AGC, the it often seems as if
it starts out with the PRO key pressed.

It appears to me that several of these phenomena may be due to
data being lost or otherwise corrupted in the socket system; perhaps
some of the socket uptions I'm using aren't as portable as I imagined.

Assembly doesn't work from within the VirtualAGC environment. I
suspect that the file-open dialogs in Solaris may cause the current
working directory to change in ways I haven't been anticipating.