diff options
| -rw-r--r-- | INSTALL | 238 | ||||
| -rw-r--r-- | NEWS | 6 | ||||
| -rw-r--r-- | doc/.cvsignore | 1 | ||||
| -rw-r--r-- | doc/mdk.texi | 22 | ||||
| -rw-r--r-- | doc/mdk_ack.texi | 4 | ||||
| -rw-r--r-- | doc/mdk_copying.texi | 2 | ||||
| -rw-r--r-- | doc/mdk_gstart.texi | 148 | ||||
| -rw-r--r-- | doc/mdk_index.texi | 4 | ||||
| -rw-r--r-- | doc/mdk_install.texi | 2 | ||||
| -rw-r--r-- | doc/mdk_intro.texi | 4 |
10 files changed, 305 insertions, 126 deletions
@@ -1,161 +1,190 @@ -1. Installing MDK +Installing MDK +************** - 1.1 Download the source tarball - 1.2 Requirements - 1.3 Basic installation - 1.4 Emacs support - 1.5 Special configure flags - 1.6 Supported platforms +Download the source tarball +=========================== - ------------------------------------------------------------------------ - -1.1 Download the source tarball + GNU MDK is distributed as a source tarball available for download in +the following URLs: -GNU MDK is distributed as a source tarball available for download in the -following URLs: + * <ftp://ftp.gnu.org/pub/gnu/mdk> (or one of its mirrors + (http://www.gnu.org/prep/ftp.html)) - * ftp://ftp.gnu.org/pub/gnu/mdk (or one of its mirrors) - * http://sourceforge.net/project/showfiles.php?group_id=13897 + * `http://sourceforge.net/project/showfiles.php?group_id=13897' -The above sites contain the latest stable releases of MDK. The development -branch is available at: + The above sites contain the latest stable releases of MDK. The +development branch is available at: - * https://savannah.gnu.org/cvs/?group_id=118 + * `https://savannah.gnu.org/cvs/?group_id=118' -After you have downloaded the source tarball, unpack it in a directory of -your choice using the command: + After you have downloaded the source tarball, unpack it in a +directory of your choice using the command: - tar xfvz mdk-X.Y.tar.gz + tar xfvz mdk-X.Y.tar.gz where X.Y stands for the downloaded version (the current stable release -being version 0.3.2). +being version {No value for `VERSION'}). - ------------------------------------------------------------------------ +Requirements +============ -1.2 Requirements + In order to build and install MDK, you will need the following +libraries installed in your system: -In order to build and install MDK, you will need the following libraries -installed in your system: + - GLIB 1.2.0 (http://www.gtk.org) (required) - * GLIB 1.2.0 (required) - * GNU Flex 2.3 (required) - * GTK+ 1.2.0 (optional) - * libglade (optional) - * GNU readline and history libraries (optional) + - GNU Flex 2.3 (http://www.gnu.org/software/flex/flex.html) + (required) -If present, readline and history are used to provide command completion and -history management to the command line MIX virtual machine, mixvm GTK+ and -libglade are needed if you want to build the graphical interface to the MIX -virtual machine, gmixvm. + - GTK 1.2.0 (http://www.gtk.org) (optional) -Please note: you need both the libraries and the headers; this means both -the library package and the `-dev' package if you do not compile your -libraries yourself (ex: installing `libgtk1.2' and `libgtk1.2-dev' on -Debian). + - Libglade (ftp://ftp.gnome.org/pub/GNOME/stable/sources/libglade/) + (optional) - ------------------------------------------------------------------------ + - GNU Readline + (http://cnswww.cns.cwru.edu/php/chet/readline/rltop.html) + (optional) -1.3 Basic installation + - GNU Libguile 1.3 (http://www.gnu.org/software/guile) (optional) -MDK uses GNU Autoconf and Automake tools, and, therefore, should be built -and installed without hassle using the following commands inside the source -directory: + If present, readline and history are used to provide command +completion and history management to the command line MIX virtual +machine, `mixvm'. GTK+ and libglade are needed if you want to build +the graphical interface to the MIX virtual machine, `gmixvm'. Finally, +if libguile is found, the MDK utilities will be compiled with Guile +support and will be extensible using Scheme. - ./configure - make - make install + *Please note*: you need both the libraries _and_ the headers; this +means both the library package and the `-dev' package if you do not +compile your libraries yourself (ex: installing `libgtk1.2' and +`libgtk1.2-dev' on Debian). -where the last one must be run as root. +Basic installation +================== -The first command, configure, will setup the makefiles for your system. In -particular, configure will look for GTK+ and libglade, and, if they are -present, will generate the appropiate makefiles for building the gmixvm -graphical user interface. Upon completion, you should see a message with the -configuration results like the following: + MDK uses GNU Autoconf and Automake tools, and, therefore, should be +built and installed without hassle using the following commands inside +the source directory: - *** GNU MDK 0.3 has been successfully configured. *** + ./configure + make + make install - Type make to build the following utilities: - - mixasm (MIX assembler) - - mixvm (MIX virtual machine, with readline support) - - gmixvm (mixvm GTK+ GUI) +where the last one must be run as root. -where the last line may be missing if you lack the above mentioned + The first command, `configure', will setup the makefiles for your +system. In particular, `configure' will look for GTK+ and libglade, +and, if they are present, will generate the appropiate makefiles for +building the `gmixvm' graphical user interface. Upon completion, you +should see a message with the configuration results like the following: + + *** GNU MDK 0.5 has been successfully configured. *** + + Type 'make' to build the following utilities: + - mixasm (MIX assembler) + - mixvm (MIX virtual machine, with readline support, + with guile support) + - gmixvm (mixvm GTK+ GUI, with guile support) + - mixguile (the mixvm guile shell) + +where the last lines may be missing if you lack the above mentioned libraries. -The next command, make, will actually build the MDK programs in the -following locations: + The next command, `make', will actually build the MDK programs in +the following locations: - * `mixutils/mixasm' - * `mixutils/mixvm' - * `mixgtk/gmixvm' + - `mixutils/mixasm' -You can run these programs from within their directories, but I recommend -you to install them in proper locations using make install from a root -shell. + - `mixutils/mixvm' - ------------------------------------------------------------------------ + - `mixgtk/gmixvm' -1.4 Emacs support + - `mixguile/mixguile' -mixvm can be run within an Emacs GUD buffer using the elisp program -`misc/mixvm.el', kindly contributed by Philip E. King. + You can run these programs from within their directories, but I +recommend you to install them in proper locations using `make install' +from a root shell. -`mixvm.el' provides an interface between MDK's mixvm and Emacs, via GUD. -Place this file in your load-path, optionally adding the following line to -your `.emacs' file: +Emacs support +============= - (autoload 'mixvm "mixvm" "mixvm/gud interaction" t) + `mixvm' can be run within an Emacs GUD buffer using the elisp +program `misc/mixvm.el', kindly contributed by {No value for `PHILIP'}. - ------------------------------------------------------------------------ + `mixvm.el' provides an interface between MDK's `mixvm' and Emacs, +via GUD. Place this file in your load-path, optionally adding the +following line to your `.emacs' file: -1.5 Special configure flags + (autoload 'mixvm "mixvm" "mixvm/gud interaction" t) -You can fine tunning the configuration process using the following switches -with configure: +Special configure flags +======================= -User Option: --enable-gui[=yes|no] -User Option: --disable-gui - Enables/disables the built of the MIX virtual machine GUI (gmixvm). If - the required libraries are missing (see section 1.2 Requirements) the - configure script with automatically disable this feature. + You can fine tunning the configuration process using the following +switches with configure: -User Option: --with-readline[=yes|no] -User Option: --without-readline - Enables/disables the GNU Readline support for mixvm. If the required - libraries are missing (see section 1.2 Requirements) the configure - script with automatically disable this feature. + - User Option: -enable-gui[=yes|no] + - User Option: -disable-gui + Enables/disables the build of the MIX virtual machine GUI + (`gmixvm'). If the required libraries are missing (*note + Requirements::) the configure script with automatically disable + this feature. -For additional, boilerplate configure options, see the `INSTALL' file, or -run + - User Option: -with-guile[=yes|no] + - User Option: -without-guile + Enables/disables the Guile support for `mixvm' and `gmixvm', and + the build of `mixguile'. If the required libraries are missing + (*note Requirements::) the configure script with automatically + disable this feature. - configure --help + - User Option: -with-readline[=yes|no] + - User Option: -without-readline + Enables/disables the GNU Readline support for `mixvm'. If the + required libraries are missing (*note Requirements::) the configure + script with automatically disable this feature. - ------------------------------------------------------------------------ + For additional, boilerplate configure options, see the + `Generic configure help' below, or run + + configure --help -1.6 Supported platforms +Supported platforms +=================== -GNU MDK has been tested in the following platforms: + GNU MDK has been tested in the following platforms: * Debian GNU/Linux 2.2/2.3 + * Redhat GNU/Linux 7.0 (Agustin Navarro), 6.2 (Roberto Ferrero) - * FreeBSD 4.2 (Ying-Chieh Liao) + + * Mandrake 8.0 (Agustin Navarro) + + * FreeBSD 4.2, 4.3 (Ying-Chieh Liao) + * Solaris 2.8/gcc 2.95.3 (Stephen Ramsay) + * MS Windows 98 SE/Cygwin 1.1.8-2 (Christoph von Nathusius)(1) -(1) Caveats: Christoph has only tested mixvm and mixasm on this platform, -using gcc 2.95.3-2, GLIB 1.2.10 and GNUreadline 4.1-2. He has reported -missing history functionalities on a first try. If you find problems -with history/readline functionality, please try a newer/manually -installed readline version. + MDK will probably work on any GNU/Linux and BSD platform. If you try +it in a platform not listed above, please send a mail to the author +<jao@gnu.org>. + + ---------- Footnotes ---------- + + (1) Caveats: Christoph has only tested `mixvm' and `mixasm' on this +platform, using `gcc' 2.95.3-2, `GLIB' 1.2.10 and `GNUreadline' 4.1-2. +He has reported missing history functionalities on a first try. If you +find problems with history/readline functionality, please try a +newer/manually installed readline version. + -MDK will probably work on any GNU/Linux and BSD platform. If you try it in a -platform not listed above, please send a mail to the author. ------------------------------------------------------------------------ ------------------------------------------------------------------------ -2. Generic configure help +Generic configure help +********************** + Basic Installation ================== @@ -336,3 +365,6 @@ find the X include and library files automatically, but if it doesn't, you can use the `configure' options `--x-includes=DIR' and `--x-libraries=DIR' to specify their locations. +---- + +$Id: INSTALL,v 1.4 2001/09/16 22:17:33 jao Exp $
\ No newline at end of file @@ -12,6 +12,9 @@ Please send mdk bug reports to bug-mdk@gnu.org. ** Bug fix: help messages are now correctly aligned in (g)mixvm. +** Bug fix: timing statitics for the MOVE instruction are correctly + computed. + --------------------------------------------------------------------------- * Version 0.4.2 (17/08/01) @@ -260,3 +263,6 @@ Copyright (C) 2000, 2001, Free Software Foundation, Inc. under the above conditions, provided also that they carry prominent notices stating who last changed them. + +--- +$Id: NEWS,v 1.34 2001/09/16 22:17:33 jao Exp $ diff --git a/doc/.cvsignore b/doc/.cvsignore index 0128ab7..3c56128 100644 --- a/doc/.cvsignore +++ b/doc/.cvsignore @@ -15,6 +15,7 @@ mdk.info-1 mdk.info-2 mdk.info-3 mdk.info-4 +mdk.info-5 mdk.ky mdk.log mdk.pg diff --git a/doc/mdk.texi b/doc/mdk.texi index 6999267..58afc1d 100644 --- a/doc/mdk.texi +++ b/doc/mdk.texi @@ -102,6 +102,7 @@ helpful discussions, as well as actual code (@pxref{mixvm.el}). @menu * Introduction:: +* Acknowledgments:: * Installing MDK:: Installing GNU MDK from the source tarball. * MIX and MIXAL tutorial:: Learn the innards of MIX and MIXAL. * Getting started:: Basic usage of the @sc{mdk} tools. @@ -111,7 +112,6 @@ helpful discussions, as well as actual code (@pxref{mixvm.el}). * mixasm:: Invoking the MIXAL assembler. * Problems:: Reporting bugs. * Copying:: @sc{mdk} licensing terms. -* Acknowledgments:: * Concept Index:: Index of concepts. * Instructions and commands:: Index of MIXAL instructions and MIXVM commands. @@ -132,6 +132,9 @@ helpful discussions, as well as actual code (@pxref{mixvm.el}). + + + @detailmenu --- The Detailed Node Listing --- @@ -187,6 +190,7 @@ Getting started * Running the program:: Running and debugging your programs. * Using mixguile:: Using the Scheme interpreter to run and debug your programs. +* Using Scheme in mixvm and gmixvm:: Running the program @@ -196,9 +200,15 @@ Running the program Using @code{mixguile} -* The mixguile shell:: -* Additional functions:: -* Defining new functions:: +* 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 + +* Command hooks:: +* Break hooks:: @code{mixvm}, the MIX computer simulator @@ -235,6 +245,7 @@ Copying @end menu @include mdk_intro.texi +@include mdk_ack.texi @include mdk_install.texi @include mdk_tut.texi @include mdk_gstart.texi @@ -244,7 +255,6 @@ Copying @include mdk_mixasm.texi @include mdk_bugs.texi @include mdk_copying.texi -@include mdk_ack.texi @include mdk_index.texi @include mdk_findex.texi @@ -252,4 +262,4 @@ Copying @contents @bye -$Id: mdk.texi,v 1.13 2001/09/13 00:13:39 jao Exp $ +$Id: mdk.texi,v 1.14 2001/09/16 22:17:33 jao Exp $ diff --git a/doc/mdk_ack.texi b/doc/mdk_ack.texi index 4145694..cba9251 100644 --- a/doc/mdk_ack.texi +++ b/doc/mdk_ack.texi @@ -4,9 +4,9 @@ @c Free Software Foundation, Inc. @c See the file mdk.texi for copying conditions. -@c $Id: mdk_ack.texi,v 1.2 2001/09/14 00:48:29 jao Exp $ +@c $Id: mdk_ack.texi,v 1.3 2001/09/16 22:17:33 jao Exp $ -@node Acknowledgments, Concept Index, Copying, Top +@node Acknowledgments, Installing MDK, Introduction, Top @comment node-name, next, previous, up @unnumbered Acknowledgements diff --git a/doc/mdk_copying.texi b/doc/mdk_copying.texi index bfb6b34..bbcd225 100644 --- a/doc/mdk_copying.texi +++ b/doc/mdk_copying.texi @@ -1,4 +1,4 @@ -@node Copying, Acknowledgments, Problems, Top +@node Copying, Concept Index, Problems, Top @appendix Copying @menu diff --git a/doc/mdk_gstart.texi b/doc/mdk_gstart.texi index 67758f5..14a88d9 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.8 2001/09/15 02:14:01 jao Exp $ +@c $Id: mdk_gstart.texi,v 1.9 2001/09/16 22:17:33 jao Exp $ @node Getting started, mixvm.el, MIX and MIXAL tutorial, Top @chapter Getting started @@ -22,6 +22,7 @@ assumed; for a compact reminder, see @ref{MIX and MIXAL tutorial}. * Running the program:: Running and debugging your programs. * Using mixguile:: Using the Scheme interpreter to run and debug your programs. +* Using Scheme in mixvm and gmixvm:: @end menu @node Writing a source file, Compiling, Getting started, Getting started @@ -484,7 +485,7 @@ of executed instructions) and @code{weval} (which evaluates w-expressions on the fly). For a complete description of all available MIX commands, @xref{mixvm}. -@node Using mixguile, , Running the program, Getting started +@node Using mixguile, Using Scheme in mixvm and gmixvm, Running the program, Getting started @section Using @code{mixguile} With @code{mixguile} you can run a MIX simulator embedded in a Guile @@ -497,6 +498,7 @@ 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:: @end menu @node The mixguile shell, Additional functions, Using mixguile, Using mixguile @@ -620,7 +622,7 @@ list of these additional functions, In the next section, we'll see a sample of using these functions to extend @code{mixguile}'s functionality. -@node Defining new functions, , Additional functions, Using mixguile +@node Defining new functions, Hook functions, Additional functions, Using mixguile @subsection Defining new functions @cindex Scheme functions @@ -720,12 +722,26 @@ 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 +@node Hook functions, , Defining new functions, Using mixguile @subsection Hook functions @cindex hook function @cindex pre-hook @cindex post-hook +Hooks are functions called before or after a given event occurs. In +@code{mixguile}, you can define command and break hooks, which are +associated, respectively, with command execution and program +interruption events. The following sections give you a tutorial on using +hook functions within @code{mixguile}. + +@menu +* Command hooks:: +* Break hooks:: +@end menu + +@node Command hooks, Break hooks, Hook functions, Hook functions +@subsubsection Command hooks + In the previous section, we have seen how to extend @code{mixguile}'s functionality through the use of user defined functions. Frequently, you'll write new functions that improve in some way the workings of a @@ -787,11 +803,9 @@ Stopped at line 6: HLT guile> @end example -You can add any number of hooks to a given command. They will be -executed in the same order as they are registered. As a second, more -elaborated example, let's define hooks which print the address and -contents of a cell being modified using @code{smem}. The hook functions -could be something like this: +As a second, more elaborated, example, let's define hooks which print +the address and contents of a cell being modified using @code{smem}. The +hook functions could be something like this: @example (define smem-pre-hook @@ -832,3 +846,119 @@ New contents: 100 guile> @end example +@cindex global hook + +You can add any number of hooks to a given command. They will be +executed in the same order as they are registered. You can also define +global post (pre) hooks, which will be called before (after) any +@code{mixvm} command is executed. Global hook functions must admit two +arguments, namely, a string naming the invoked command and a string list +of its arguments, and they are installed using the Scheme functions +@code{mix-add-global-pre-hook} and @code{mix-add-global-post-hook}. A +simple example of global hook would be: + +@example +guile> (define pre-hook + (lambda (cmd args) + (display cmd) + (display " invoked with arguments ") + (display args) + (newline))) +guile> (mix-add-global-pre-hook pre-hook) +ok +guile> (mix-pmem 120 125) +pmem invoked with arguments (120-125) +0120: + 00 00 00 00 00 (0000000000) +0121: + 00 00 00 00 00 (0000000000) +0122: + 00 00 00 00 00 (0000000000) +0123: + 00 00 00 00 00 (0000000000) +0124: + 00 00 00 00 00 (0000000000) +0125: + 00 00 00 00 00 (0000000000) +guile> +@end example + +Note that if you invoke @code{mixvm} commands within a global hook, its +associated command hooks will be run. Thus, if you have installed both +the @code{next} hooks described earlier and the global hook above, +executing @code{mix-next} will yield the following result: + +@example +guile> (mix-next 5) +next invoked with arguments (5) +slog invoked with arguments (off) +MIXAL HELLO WORLD +Stopped at line 7: MSG ALF "MIXAL" +slog invoked with arguments (on) +guile> +@end example + +Adventurous readers may see the above global hook as the beginning of a +command log utility or a macro recorder that saves your commands for +replay. + +@node Break hooks, , Command hooks, Hook functions +@subsubsection Break hooks + +@cindex break hook + +We have seen in the previous section how to associate hooks to command +execution, but they are not the whole story. You can also associate hook +functions to program interruption, that is, specify functions that +should be called every time the execution of a MIX program is stopped +due to the presence of a breakpoint, either explicit or +conditional. Break hooks take as arguments the line number and memory +address at which the break occurred. A simple hook that logs the line +and address of the breakpoint could be defined as: + +@example +(define break-hook + (lambda (line address) + (display "Breakpoint encountered at line ") + (display line) + (display " and address ") + (display address) + (newline))) +@end example +@noindent +and installed for explicit and conditional breakpoints using + +@example +(mix-add-break-hook break-hook) +(mix-add-cond-break-hook break-hook) +@end example +@noindent +after that, every time the virtual machine encounters a breakpoint, +@code{break-code} shall be evaluated for you@footnote{You may have +noticed that break hooks can be implemented in terms of command hooks +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 Using Scheme in mixvm and gmixvm, , Using mixguile, Getting started +@section Using Scheme in @code{mixvm} and @code{gmixvm} +@cindex @code{scmf} + +In the previous section (@pxref{Using mixguile}) we have seen how the +Guile shell @code{mixguile} offers you the possibility of using Scheme +to manipulate a MIx virtual machine and extend the set of commands +offered by @code{mixvm} and @code{gmixvm}. This possibility is not +limited to the @code{mixguile} shell. Actually, both @code{mixvm} and +@code{gmixvm} incorporate an embedded Guile interpreter, and can +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} +command like this: + +@example +MIX> scmf /path/to/file/file.scm +@end example + +Therefore, you have at your disposal all the @code{mixguile} goodies +described above (new functions, new command definitions, hooks...) +inside @code{mixvm} and @code{gmixvm}. In other words, these programs +are extensible using Scheme. See @ref{Using mixguile} for examples of +how to do it. + diff --git a/doc/mdk_index.texi b/doc/mdk_index.texi index 9c3a1db..5aaecc4 100644 --- a/doc/mdk_index.texi +++ b/doc/mdk_index.texi @@ -4,9 +4,9 @@ @c Free Software Foundation, Inc. @c See the file mdk.texi for copying conditions. -@c $Id: mdk_index.texi,v 1.4 2001/09/13 00:13:39 jao Exp $ +@c $Id: mdk_index.texi,v 1.5 2001/09/16 22:17:33 jao Exp $ -@node Concept Index, Instructions and commands, Acknowledgments, Top +@node Concept Index, Instructions and commands, Copying, Top @unnumbered Concept Index @cindex tail recursion diff --git a/doc/mdk_install.texi b/doc/mdk_install.texi index a9aa9a8..2874d79 100644 --- a/doc/mdk_install.texi +++ b/doc/mdk_install.texi @@ -4,7 +4,7 @@ @c Free Software Foundation, Inc. @c See the file mdk.texi for copying conditions. -@node Installing MDK, MIX and MIXAL tutorial, Introduction, Top +@node Installing MDK, MIX and MIXAL tutorial, Acknowledgments, Top @comment node-name, next, previous, up @chapter Installing @sc{mdk} diff --git a/doc/mdk_intro.texi b/doc/mdk_intro.texi index 5464980..c86ca18 100644 --- a/doc/mdk_intro.texi +++ b/doc/mdk_intro.texi @@ -4,9 +4,9 @@ @c Free Software Foundation, Inc. @c See the file mdk.texi for copying conditions. -@c $Id: mdk_intro.texi,v 1.4 2001/09/13 00:13:39 jao Exp $ +@c $Id: mdk_intro.texi,v 1.5 2001/09/16 22:17:33 jao Exp $ -@node Introduction, Installing MDK, Top, Top +@node Introduction, Acknowledgments, Top, Top @comment node-name, next, previous, up @unnumbered Introduction @cindex Introduction |