# HG changeset patch
# User Arun Giridhar <arungiridhar@gmail.com>
# Date 1695761340 14400
# Node ID 07f32284d5e528f055ac54b2b86abea110db5839
# Parent  711ebddc86ea1cf71b1934720a65601c19b14970
New function vm.m to provide help on VM usage

* scripts/help/vm.m: New function to provide help on VM commands,
analogous to debug.m for all the debugging commands.

* NEWS.9.md: Invite users to run `vm` or `help vm` at the prompt.

diff -r 711ebddc86ea -r 07f32284d5e5 etc/NEWS.9.md
--- a/etc/NEWS.9.md	Tue Sep 26 22:36:09 2023 +0200
+++ b/etc/NEWS.9.md	Tue Sep 26 16:49:00 2023 -0400
@@ -9,7 +9,9 @@
 `--disable-vm-evaluator` was *not* used when building Octave.  Speedups from 2X
 to 40X have been observed for different kinds of m-code.  This feature is
 considered experimental for now.  M-code that cannot be handled by the VM yet
-falls back automatically to the existing interpreter.
+falls back automatically to the existing interpreter.  User tests of the VM
+evaluator are encouraged.  To learn more about VM commands, type `vm`
+or `help vm` at the Octave prompt.
 
 - `oruntests`: The current directory now changes to the directory
 containing the files with the tests for the duration of the test.  This
diff -r 711ebddc86ea -r 07f32284d5e5 scripts/help/vm.m
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/scripts/help/vm.m	Tue Sep 26 16:49:00 2023 -0400
@@ -0,0 +1,67 @@
+########################################################################
+##
+## Copyright (C) 2008-2023 The Octave Project Developers
+##
+## See the file COPYRIGHT.md in the top-level directory of this
+## distribution or <https://octave.org/copyright/>.
+##
+## This file is part of Octave.
+##
+## Octave is free software: you can redistribute it and/or modify it
+## under the terms of the GNU General Public License as published by
+## the Free Software Foundation, either version 3 of the License, or
+## (at your option) any later version.
+##
+## Octave is distributed in the hope that it will be useful, but
+## WITHOUT ANY WARRANTY; without even the implied warranty of
+## MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+## GNU General Public License for more details.
+##
+## You should have received a copy of the GNU General Public License
+## along with Octave; see the file COPYING.  If not, see
+## <https://www.gnu.org/licenses/>.
+##
+########################################################################
+
+## -*- texinfo -*-
+## @deftypefn {} {} vm ()
+## Summary of commands related to Octave's virtual machine (VM) evaluator.
+##
+## For more information on each command and available options use
+## @code{help CMD}.
+##
+## The VM commands available in Octave are
+##
+## @table @code
+## @item __enable_vm_eval__
+## The main VM user function.  Switch on or off the VM as a whole.
+##
+## @item __compile__
+## Another VM user function.  Compiles a specified function to bytecode.
+##
+## @item __vm_clear_cache__
+## Internal function.  Clears the cache of already-processed code.
+##
+## @item __vm_is_executing__
+## Internal function.  Returns true if the VM is executing.
+##
+## @item __vm_print_trace__
+## Internal function.  Print a debug trace from the VM.
+##
+## @item __vm_profile__
+## Internal function.  Profile the code running in the VM.
+##
+## @end table
+##
+## @noindent
+##
+## @seealso{__enable_vm_eval__, __compile__, __vm_clear_cache__,
+## __vm_is_executing__, __vm_print_trace__, __vm_profile__}
+## @end deftypefn
+
+function vm ()
+  help ("vm");
+endfunction
+
+## Mark file as being tested.  No real test needed for a documentation .m file
+%!assert (1)