Building a GLUI Control Panel
#############################

..  include::   /header.inc
..  vim:filetype=rst spell:

We need a way to see our machine run. While we could hook things together and
simply turn the machine on, that is not going to be a useful way to watch what
is happening, and think our way through what is happening. In order to set up
this machine to we can watch it run, we need to be able to control it at a very
fine level, like one clock tick at a time. Actually, one control system step at
a time would be better. What I want to do is build a control panel with buttons
you can click that will tell the control unit to do one tiny step in the
sequence of steps needed to complete an instruction. Ideally, we will have
outputs showing on this control system where we can see that is going on. That
means we need to display our data, as it moves along the wires. 

We had enough power to do that in the graphics code I provided, but I found a
tool that will make things easier to set up and much nicer looking. 

GLUI
****

Originally developed at Oxford University back in 1999, GLUI_ is a lightweight
GUI package that sits on top of GLUT (freeglut is what we are using). This
package sets up a nice looking GUI, complete with several controls we can
drive with our favorite pointing gadget - your Mouse!

The code is maintained on GitHub_ and is pretty easy to get running in your VM.

Ready. Here we go!

Add Dependencies
****************

GLUI_ was available on my Mac using Homebrew_, but on Linux, I needed to compile
the code from source. To do that, I had to install a couple of other packages
needed to build the code:

..  code-block:: bash

    $ sudo apt-get install freeglut3-dev libxi-dev libxmu-dev

Those last two are needed to run graphics code on Linux using the X11 graphics
system, which has been a part of Linux since the 1980s!

Clone GLUI
**********

With the dependencies in place, we can clone the project:

..  code-block:: bash

    $ cd cosc2325
    $ git clone https://github.com/libglui/glui.git
    $ cd glui

Building the project was simple:

..  code-block:: bash

    $ make

See, Make_ is very common out there!

When the smoke cleared, there was a new file in the ``lib`` folder in this
project named ``libglui.a``. We need that file and one include file in our
project folder.

New Project Folders
*******************

This new chunk of code is available as a "library" which is basically a bunch
of object files wrapped up into a single file. Those object files are compiled
for only one system, so it is important to make sure you do not try to use a
library compiled for one system on another system.

I added the ability to build a project library file for our simulator to the
Makefile system we are using. However, the original setup did not deal with
libraries constructed for different systems. Since I routinely test on all
three major platforms, I needed to tweak the build system to handle this new
GLUI package, and be prepared to build libraries for any system. As a result, I
had to tweak two files in the ``mk`` folder. Here are the new versions:

..  literalinclude::    code/cpp-project.mk
    :linenos:
    :caption:   mk/cpp-project.mk

..  literalinclude::    code/cpp-graphics.mk
    :linenos:
    :caption:   mk/cpp-graphics.mk

The only changes involve moving libraries into subfolders under ``bin``, one
for each platform.

The Makefile system does not build these new subfolders. You can do that as follows:

..  code-block:: bash

    $ mkdir bin/Linux
    $ mkdir bin/Mac
    $ mkdir bin/PC

(Not all are needed, unless you work on these platforms).

Assuming you already have the ``bin/Linux`` folder in your project, do this:

..  code-block::    bash

    $ cp lib/libglui.a /cosc2325/lab2-CPUfactory/bin/Linux
    $ cp include/GL/glui.h /cosc2325/lab2-CPUfactory/include

..  note::

    If you build this system on anothe rplatform, be sure to compile the GLUI
    library, and copy it into the correct subdirectory of ``bin``. Currently,
    this is working on Linux and Mac.

Now, here is a test file you can run to see if this all works. The code looks a
bit strange if you have never worked with graphics projects, but it at least
proves we have a way to build a nice front-end for our simulator:

..  literalinclude::    code/avrsim.cpp
    :linenos:
    :caption:   src/main.cpp

We will remove the current ``main.cpp`` file and replace it with this code as a
start on our front-end code.

When you run this code, you should see this:

..  image:: images/glui-test.png
    :align: center

The counter is running showing the number of "frames displayed by the graphics
loop. This gives you a feel for how often we redraw the screen. The ``PC``
window shows a program counter, which we start at zero. Clicking on the
``Step`` button should increment the PC value, clicking on ``Reset`` should
return that PC to zero.

At the moment, nothing is hooked intot hsicontrol system, but that will happen
soon. I will post notes showing how that is proceeding as I get things running.

Hey, this is a good start on building something we can use to watch our
simulator work!