summaryrefslogtreecommitdiffhomepage
path: root/doc/mdk_gstart.texi
diff options
context:
space:
mode:
Diffstat (limited to 'doc/mdk_gstart.texi')
-rw-r--r--doc/mdk_gstart.texi88
1 files changed, 81 insertions, 7 deletions
diff --git a/doc/mdk_gstart.texi b/doc/mdk_gstart.texi
index 14a88d9..1ec501f 100644
--- a/doc/mdk_gstart.texi
+++ b/doc/mdk_gstart.texi
@@ -4,7 +4,7 @@
@c Free Software Foundation, Inc.
@c See the file mdk.texi for copying conditions.
-@c $Id: mdk_gstart.texi,v 1.9 2001/09/16 22:17:33 jao Exp $
+@c $Id: mdk_gstart.texi,v 1.10 2001/09/18 22:53:18 jao Exp $
@node Getting started, mixvm.el, MIX and MIXAL tutorial, Top
@chapter Getting started
@@ -235,7 +235,9 @@ our sample).
As you can see, running programs non-interactively has many
limitations. You cannot peek the virtual machine's memory contents, not
to mention stepping through your program's instructions or setting
-breakpoints. Enter interactive mode.
+breakpoints@footnote{The @code{mixguile} program allows you to execute
+arbitrary combinations of @code{mixvm} commands (using Scheme)
+non-interactively. @xref{Scheme scripts}.}. Enter interactive mode.
@node Interactive mode, Debugging, Non-interactive mode, Running the program
@comment node-name, next, previous, up
@@ -498,7 +500,8 @@ using this MIX emulator.
* The mixguile shell:: Using the Scheme MIX virtual machine.
* Additional functions:: Scheme functions accessing the VM.
* Defining new functions:: Defining your own Scheme functions.
-* Hook functions::
+* Hook functions:: Using command and break hook functions.
+* Scheme scripts::
@end menu
@node The mixguile shell, Additional functions, Using mixguile, Using mixguile
@@ -616,8 +619,7 @@ guile>
Other functions returning the contents of the virtual machine components
are @code{mix-cmp} and @code{mix-over}, which eval to the value of the
comparison flag and the overflow toggle respectively. For a complete
-list of these additional functions,
-@c see @xref{mixguile----}.
+list of these additional functions, @xref{mixguile}.
In the next section, we'll see a sample of using these functions to
extend @code{mixguile}'s functionality.
@@ -722,7 +724,7 @@ loads it before entering the REPL. Therefore, you can copy your
definitions in that file, or load the @file{functions.scm} file in
@file{mixguile.scm}.
-@node Hook functions, , Defining new functions, Using mixguile
+@node Hook functions, Scheme scripts, Defining new functions, Using mixguile
@subsection Hook functions
@cindex hook function
@cindex pre-hook
@@ -934,6 +936,59 @@ associated to @code{mix-run} and @code{mix-next}. As a matter of fact,
they @emph{are} implemented this way: take a look at the file
@file{@emph{install_dir}/share/mdk/mix-vm-stat.scm} if you are curious.}.
+@node Scheme scripts, , Hook functions, Using mixguile
+@subsection Scheme scripts
+@cindex Scheme script
+@cindex non-interactive
+
+Another useful way of using @code{mixguile} is writing executable
+scripts that perform a set of commands for you. This is done using the
+@code{mixguile} switch @code{-s} (being a Guile shell, @code{mixguile}
+accepts all the command options of @code{guile}; type @code{mixguile -h}
+for a list of all available command options). For instance, if you have
+a very useful MIX program @file{foo.mix} which you want to run often,
+you don't have to fire a MIX virtual machine, load and run it every
+time; you can write a Scheme script instead:
+
+@example
+#! /usr/bin/mixguile -s
+!#
+;;; runprimes: execute the primes.mix program
+
+;; load the file you want to run
+(mix-load "../samples/primes")
+;; execute it
+(mix-run)
+;; print the contents of registers
+(mix-pall)
+;; ...
+@end example
+
+Just save the above script to a file named, say, @file{runtest}, make it
+executable (@code{chmod +x runtest}), and, well, execute it from the
+Unix shell:
+
+@example
+$ ./runtest
+Program loaded. Start address: 3000
+Running ...
+... done
+Elapsed time: 190908 /Total program time: 190908 (Total uptime: 190908)
+rA: + 30 30 30 30 30 (0511305630)
+rX: + 30 30 32 32 39 (0511313959)
+rJ: + 47 18 (3026)
+rI1: + 00 00 (0000) rI2: + 55 51 (3571)
+rI3: + 00 19 (0019) rI4: + 31 51 (2035)
+rI5: + 00 00 (0000) rI6: + 00 00 (0000)
+Overflow: F
+Cmp: L
+$
+@end example
+
+Note that this is far more flexible that running programs
+non-interactively using @code{mixvm} (@pxref{Non-interactive mode}), for
+you can execute any combination of commands you want from a Scheme
+script (not just running and dumping the registers).
@node Using Scheme in mixvm and gmixvm, , Using mixguile, Getting started
@section Using Scheme in @code{mixvm} and @code{gmixvm}
@@ -949,7 +1004,26 @@ evaluate Scheme expressions. To evaluate a single-line expression at the
@code{mixvm} or @code{gmixvm} command prompt, simply write it and press
return (the command parser will recognise it as a Scheme expression
because it is parenthesized, and will pass it to the Guile
-interpreter). You can also load and evaluate a file, using the @code{scmf}
+interpreter). A sample @code{mixvm} session using Scheme expressions
+could be:
+
+@example
+MIX > load hello
+Program loaded. Start address: 3000
+MIX > (define a (mix-loc))
+MIX > run
+Running ...
+MIXAL HELLO WORLD
+... done
+Elapsed time: 11 /Total program time: 11 (Total uptime: 11)
+MIX > (mix-pmem a)
+3000: + 46 58 00 19 37 (0786957541)
+MIX > (mix-pmem (mix-loc))
+3002: + 14 09 27 01 13 (0237350989)
+MIX >
+@end example
+
+You can also load and evaluate a file, using the @code{scmf}
command like this:
@example