path: root/doc/mdk_gmixvm.texi

@c -*-texinfo-*-
@c This is part of the GNU MDK Reference Manual.
@c Copyright (C) 2000, 2001, 2003, 2004
@c   Free Software Foundation, Inc.
@c See the file mdk.texi for copying conditions.

@c $Id: mdk_gmixvm.texi,v 1.17 2004/08/01 23:32:58 jao Exp $

@node gmixvm, mixguile, mixvm, Top
@comment  node-name,  next,  previous,  up
@chapter @code{gmixvm}, the GTK virtual machine
@cindex @code{gmixvm}
@cindex GUI
@cindex GTK+

This chapter describes the graphical MIX virtual machine emulator
shipped with @sc{mdk}. In addition to having all the command-oriented
functionalities of the other virtual machines (@code{mixvm} and
@code{mixguile}), @code{gmixvm} offers you a graphical interface
displaying the status of the virtual machine, the source code of the the
downloaded programs and the contents of the MIX devices.

@menu
* Invoking @code{gmixvm}::      Invoking the GTK+ interface.
* MIXVM console::               Using @code{mixvm} commands.
* MIX virtual machine::         The MIX virtual machine window.
* MIXAL source view::           Viewing the MIXAL source code.
* MIX devices view::            Device output.
* Menu and status bars::        Available menu commands.
@end menu

@node Invoking @code{gmixvm}, MIXVM console, gmixvm, gmixvm
@comment  node-name,  next,  previous,  up
@section Invoking @code{gmixvm}

If you have built @sc{mdk} with GTK+ support (@pxref{Installing MDK}), a
graphical front-end for the MIX virtual machine will be available in
your system. You can invoke it by typing

@example
gmixvm [-vhuq] [--version] [--help] [--usage] [--noinit]
@end example
@noindent
at your command prompt, where the options have the following meanings:

@defopt -v
@defoptx --version
Prints version and copyleft information and exits.
@end defopt

@defopt -h
@defoptx --help
@defoptx -u
@defoptx --usage
Prints a summary of available options and exits.
@end defopt

@defopt -q
@defoptx --noinit
Do not load the Guile initialisation file @code{~/.mdk/mixguile.scm} at
startup. This file contains any local Scheme code to be executed by the
embedded Guile interpreter at startup (@pxref{Using Scheme in mixvm and
gmixvm}).
@end defopt

Typing @code{gmixvm} or @code{gmixvm -q} at your command prompt, the
main window will appear, offering you a graphical interface to run and
debug your MIX programs.

@ifinfo
@image{img/ss_mix, 400pt}
@end ifinfo

@ifhtml
@image{../img/ss_mix, 400pt}
@end ifhtml

Apart from the menu and status bars, we can distinguish two zones (or
halves) in this main window. In the upper half of @code{gmixvm}'s main
window there is a notebook with three pages, namely,

@itemize
@item
a MIX virtual machine view, which shows you the registers, flags, memory
contents and time statistics of the virtual machine;
@item
a MIXAL source view, which shows the MIXAL file and lets you manage
breakpoints;
@item
a Devices view, which shows you the output to character based MIX block
devices.
@end itemize

@noindent
These three windows can be detached from the notebook, using either
the penultimate toolbar button (which detachs the currently visible
notebook page) or the menu entries under @code{@w{View->Detached windows}}.

@ifhtml
Here is an screenshot showing how @code{gmixvm} looks like when running
with a couple of detached windows:

@image{../img/ss_split, 420pt}

@end ifhtml

On the other hand, the main window's lower half presents you a
@code{mixvm} command prompt and a logging area where results of the
issued commands are presented. These widgets implement a @code{mixvm}
console which offers almost the same functionality as its
@acronym{CLI} counterpart.

When @code{gmixvm} is run, it creates a directory named @file{.mdk} in
your home directory (if it does not already exist). The @file{.mdk}
directory contains the program settings, the device files used by your
MIX programs (@pxref{Devices}), and a command history file.

The following sections describe the above mentioned components of
@code{gmixvm}.

@node MIXVM console, MIX virtual machine, Invoking @code{gmixvm}, gmixvm
@comment  node-name,  next,  previous,  up
@section MIXVM console

In the lower half of the @code{gmixvm} main window, you will find a
command text entry and, above it, an echo area. These widgets offer you
the same functionality as its @acronym{CLI} counterpart, @code{mixvm}
(@pxref{mixvm}). You can issue almost all @code{mixmv} commands at the
@code{gmixvm}'s command prompt in order to manipulate the MIX virtual
machine. Please refer to @xref{mixvm}, for a description of these
commands, and to @xref{Getting started}, for a tutorial on using the MIX
virtual machine. The command prompt offers command line completion for
partially typed commands using the @key{TAB} key; e.g., if you type

@example
lo @key{TAB}
@end example
@noindent
the command is automatically completed to @code{load}. If multiple
completions are available, they will be shown in the echo area. Thus,
typing

@example
p @key{TAB}
@end example
@noindent
will produce the following output on the echo area:

@example
Completions:
pc     psym     preg     pflags     pall
pmem
@end example
@noindent
which lists all the available commands starting with @code{p}. In
addition, the command prompt maintains a history of typed commands,
which can be recovered using the arrow up and down keys. As mentioned
above, a file containing previous sessions' commands is stored in the
configuration directory @file{~/.mdk}, and reloaded every time you start
@code{gmixvm}.

You can change the font used to display the issued commands and the
messages in the echo area using the @code{@w{Settings->Change font->Command
prompt}} and @code{@w{Settings->Change font->Command log}} menu commands.

@node MIX virtual machine, MIXAL source view, MIXVM console, gmixvm
@comment  node-name,  next,  previous,  up
@section MIX virtual machine

The first notebook's page displays the current status of the virtual
machine. There you can find the registers' contents, the value of the
comparison and overflow flags, the location pointer, a list with all MIX
memory cells and their contents, and the time statistics (including
total uptime, elapsed time since the last run command and total
execution time for the currently loaded MIX program).

If you click any register entry, you will be prompted for a new register's
contents.

@ifhtml
The next figure shows the enter word dialog.

@image{../img/ss_worddlg, 250pt}

@end ifhtml

In the same manner, click on any address of the memory cells list to be
prompted for the new contents of the clicked cell. If you click the
address column's title, a dialog asking you for a memory address will
appear; if you introduce a valid address, this will be the first cell
displayed in the scrollable list after you click the OK button.

The register contents are shown as a list of MIX bytes plus sign. If you
place the mouse pointer over any of them, the decimal value of this MIX
word will appear inside a tooltip.

You can change the font used to display the MIX virtual machine contents
using the @code{@w{Settings->Change font->MIX}} menu command.

@node MIXAL source view, MIX devices view, MIX virtual machine, gmixvm
@comment  node-name,  next,  previous,  up
@section MIXAL source view

The second notebook's page, dubbed Source, shows you the MIXAL source of
the currently loaded MIX file.

@ifhtml
@image{../img/ss_mixal, 400pt}
@end ifhtml

The information is presented in four columns. The first column
displays little icons showing the current program pointer and any set
breakpoints. The second and third columns show the address and memory
contents of the compiled MIX instruction, while the last one displays
its corresponding MIXAL representation, together with the source file
line number. You can set/unset breakpoints by clicking on any line
that has an associated memory address.

You can change the font used to display the MIXAL source code
using the @code{@w{Settings->Change font->MIXAL}} menu command.

@node MIX devices view, Menu and status bars, MIXAL source view, gmixvm
@comment  node-name,  next,  previous,  up
@section MIX devices view

The last notebook page, dubbed Devices, shows you the output/input
to/from MIX block devices (the console, line printer, paper tape,
disks, card and tapes @pxref{Devices}) produced by the running
program.

@ifhtml

@image{../img/ss_devices, 400pt}

@end ifhtml

Input device contents is read from files located in the @file{~/.mdk}
directory, and the output is also written to files at the same
location. Note that device tabs will appear as they are used by the MIX
program being run, and that loading a new MIX program will close all
previously open devices.

The input/output for binary block devices (tapes and disks) is a list
of MIX words, which can be displayed either in decimal or word format
(e.g. @w{- 67} or @w{- 00 00 00 01 03}). The format used by
@code{gmixvm} can be configured using the @code{@w{Settings->Device output}}
menu command for each binary device.

You can change the font used to display the devices content
using the @code{@w{Settings->Change font->Devices}} menu command.

@node Menu and status bars,  , MIX devices view, gmixvm
@comment  node-name,  next,  previous,  up
@section Menu and status bars

The menu bar gives you access to the following commands:

@deffn File Load...
Opens a file dialog that lets you specify a binary MIX file to be loaded
in the virtual machine's memory. It is equivalent to the @code{mixvm}'s
@code{load} command (@pxref{File commands}).
@end deffn

@deffn File Edit...
Opens a file dialog that lets your specify a MIXAL source file to be
edited. It is equivalent to the @code{mixvm}'s @code{edit} command
(@pxref{File commands}). The program used for editing can be specified
using the menu entry @code{@w{Settings->External programs}}, or using the
@code{mixvm} command @code{sedit}.
@end deffn

@deffn File Compile...
Opens a file dialog that lets your specify a MIXAL source file to be
compiled. It is equivalent to the @code{mixvm}'s @code{compile} command
(@pxref{File commands}). The command used for compiling can be specified
using the menu entry @code{@w{Settings->External programs}}, or using the
@code{mixvm} command @code{sasm}.
@end deffn

@deffn File Exit
Exits the application.
@end deffn

@deffn Debug Run
Runs the currently loaded MIX program, up to the next breakpoint. It is
equivalent to the @code{mixvm}'s @code{run} command (@pxref{Debug
commands}).
@end deffn

@deffn Debug Next
Executes the next MIX instruction. It is equivalent to the
@code{mixvm}'s @code{next} command (@pxref{Debug commands}).
@end deffn

@deffn Debug @w{Clear breakpoints}
Clears all currently set breakpoints. It is equivalent to the
@code{mixvm}'s @code{cabp} command.
@end deffn

@deffn Debug Symbols...
Opens a dialog showing the list of symbols defined in the currently
loaded MIX program. The font used to display this list can be
customised using the meny entry @code{@w{Settings->Change font->Symbol
list}}.

@ifhtml

@image{../img/ss_symbols, 250pt}

@end ifhtml

@end deffn

@deffn View @w{Toolbar(s)}
Toggles the toolbar(s) in the @code{gmixvm} window(s) (when notebook
pages are detached, each one has its own toolbar).
@end deffn

@deffn View @w{Detached windows} @w{Virtual machine}
@deffnx View @w{Detached windows} Source
@deffnx View @w{Detached windows} Devices

These toggles let you detach (or re-attach) the corresponding notebook
page.

@end deffn

@deffn Settings @w{Change font}
Lets you change the font used in the various @code{gmixv} widgets
(i.e. commad prompt, command log, Virtual machine, Source, Devices and
Symbol list). There is also an entry (@code{All}) to change all fonts
at once.
@end deffn

@deffn Settings @w{Device output...}
Opens a dialog that lets you specify which format shall be used to show
the contents of MIX binary block devices.

@ifhtml
@image{../img/ss_devform, 250pt}
@end ifhtml

The available formats are decimal (e.g. @w{-1234}) and MIX word
(e.g. @w{- 00 00 00 19 18}).
@end deffn

@deffn Settings @w{Devices dir...}
Opens a dialog that lets you choose where the MIX device files will be
stored (@file{~/.mdk} is the default location).

@ifhtml
@image{../img/ss_devdir, 250pt}
@end ifhtml

You can also specify the devices directory using the @code{mixvm}
command @code{sddir} (@pxref{Configuration commands}).

@end deffn

@deffn Settings @w{External programs...}
This menu command opens a dialog that lets you specify the commands used
for editing and compiling MIXAL source files.

@ifhtml
@image{../img/ss_extprog, 250pt}
@end ifhtml

The commands are specified as template strings, where the control
substring @code{%s} will be substituted by the actual file name. Thus,
if you want to edit programs using @code{vi} running in an @code{xterm},
you must enter the command template @code{@w{xterm -e vi %s}} in the
corresponding dialog entry. These settings can also be changed using the
@code{mixvm} commands @code{sedit} and @code{sasm} (@pxref{Configuration
commands}).
@end deffn


@deffn Settings Save
Saves the current settings.
@end deffn

@deffn Settings @w{Save on exit}
Mark this checkbox if you want @code{gmixvm} to save its settings
every time you quit the program.
@end deffn

@deffn Help About...
Shows information about @code{gmixvm}'s version and copyright.
@end deffn

On the other hand, the status bar displays the name of the last loaded
MIX file. In addition, when the mouse pointer is over a MIXAL source
file line that contains symbols, a list of these symbols with their
values will appear in the status bar.