--- freem/doc/freem.texi 2025/04/28 14:52:54 1.34 +++ freem/doc/freem.texi 2025/05/01 21:02:31 1.35 @@ -2215,10 +2215,12 @@ In its argumentless form, @code{BREAK} s @emph{FreeM Extension} -In its single-argument form, @code{BREAK} sets @emph{Ctrl-C} handling and error handling characteristics, provided the optional @emph{postcondition} is @emph{true} or omitted. +In its single-argument form, @code{BREAK} enters the interactive debugger or sets @emph{Ctrl-C} handling and error handling characteristics, provided the optional @emph{postcondition} is @emph{true} or omitted. The following table enumerates the possible values of @emph{breakflag} @table @code +@item "DEBUG" +Enters the interactive debugger @item 0 Disables @emph{Ctrl-C} handling @item -2 @@ -2280,6 +2282,14 @@ In its inclusive form, transfers program DO[@emph{:postcondition}] @emph{entryref}[@emph{:postcondition}[,...]] @end example +@cartouche +@quotation +@emph{Non-Standard Behavior} + +FreeM allows @code{DO} @emph{entryref}s to follow the format of @code{+@emph{intexpr}}. In this case, the value of @emph{intexpr} will be interpreted as an offset from the first line of the current routine. +@end quotation +@end cartouche + In its argumentless form, transfers control to the following block of code where the line level is one greater than the level at which @code{DO} was encountered, provided the optional @emph{postcondition} evaluates to @emph{true} or is omitted. @emph{Syntax} @@ -2307,7 +2317,7 @@ ELSE[@emph{:postcondition}] FreeM allows a @emph{postcondition} on @code{ELSE}. While explicitly forbidden in the @emph{standard}--and for good reason--it was decided that FreeM should allow postconditions everywhere, both for the sake of foolish consistency (the likes of which Emerson warned against), and for the benefit of entrants to a hypothetical future obfuscated M contest, and those with a Machiavellian predisposition to wicked perversions and undue cleverness. -Using postconditions on @code{ELSE} should be strictly avoided in production code, as they have no practical use, and may contribute to technical debt, hardening of the arteries, hobgoblins, a small mind, a surfeit of logic, climate change, Daily WTF rants, or meltdown of global financial markets. +Using postconditions on @code{ELSE} should be strictly avoided in production code, as they have no practical use, and may contribute to technical debt, hardening of the arteries, hobgoblins, a small mind, a surfeit of logic, climate change, @emph{Daily WTF} rants, or the meltdown of global financial markets. @end quotation @end cartouche @@ -2403,6 +2413,15 @@ Transfers program execution to another l GOTO[@emph{:postcondition}] @emph{entryref} @end example +@cartouche +@quotation +@emph{Non-Standard Behavior} + +FreeM allows @code{GOTO} @emph{entryref}s to follow the format of @code{+@emph{intexpr}}. In this case, the value of @emph{intexpr} will be interpreted as an offset from the first line of the current routine. +@end quotation +@end cartouche + + @node HALT @section HALT @cindex HALT @@ -5606,6 +5625,31 @@ Raised when an attempt is made to use a @chapter Debugging @cindex debugging +FreeM includes an interactive debugger, entered using the @code{BREAK "DEBUG"} command. The debugger is also entered if @code{Ctrl-C} is pressed, @code{Ctrl-C} handling is enabled, and you are in direct mode. + +The debugger uses its own unique command language, where M commands are unavailable. Commands are as follows: + +@table @asis +@item @code{exit}, @code{quit} +Exits the debugger and returns to direct mode or normal program execution. +@item @code{e} @emph{glvn}, @code{examine} @emph{glvn} +Prints the value of @emph{glvn} to the terminal. +@item @code{t}, @code{trace} +Toggles @emph{trace mode} on and off. When trace mode is on, FreeM will display information about each @code{DO} or @code{GOTO} command encountered, including the routine which invoked the branch, which type of branch was invoked, and the target of the branch. +@item @code{s}, @code{step} +Single-steps through FreeM code command-by-command. +@item @code{n}, @code{next} +Single-steps through FreeM code line-by-line. +@item @code{c}, @code{cont}, @code{continue} +Resumes normal program execution, disabling single-step mode. +@item @code{bt}, @code{backtrace} +Produces a stack trace. +@item @code{h}, @code{halt} +Halts the process being debugged and returns control to the operating system. +@item @code{w [[+|-|?]@emph{}]}, @code{watch [[+|-|?]@emph{}]} +With no arguments, toggles watchpoints on and off. With @code{+}, adds @emph{} to the watchlist. With @code{-}, removes @emph{} from the watchlist. With @code{?}, queries the watch status of @emph{}. +@end table + @node System Configuration @chapter System Configuration @cindex configuration, system @@ -5613,56 +5657,101 @@ Raised when an attempt is made to use a @section Installing FreeM @cindex installation -@section Build Configuration -@cindex build configuration - -When configuring FreeM with the supplied @code{configure} script, there are some FreeM-specific options that may be used to compile in optional features, or exclude default ones: +@subsection Installation Methods +FreeM allows the following installation methods: @table @asis +@item Binary Repository +On recent versions the Ubuntu and Debian distributions of GNU/Linux, we provide package repositories from which FreeM may easily be installed. See the @emph{FreeM Wiki} for more information, and @emph{https://packages.coherent-logic.com} for instructions. -@item @code{--enable-mwapigtk} (EXPERIMENTAL) -Enables experimental support for the M Windowing API using the GTK3 libraries. Requires that you have GTK 3 libraries, their headers, and their dependencies installed on your system. - -Please consult your operating system's documentation for the correct commands to install the required libraries. +If available, this is the simplest method of installing FreeM. +@item Binary Packages +We provide binary packages of FreeM for @emph{dpkg} and @emph{rpm}-based distributions of GNU/Linux, and @emph{pkgadd} packages for Solaris 8-10. If you cannot use repositories, this is the easiest option. -@emph{Example} +See @emph{https://freem.coherent-logic.com/binaries.cfm} for downloads and instructions. +@item Source Archive +If you prefer installing from source, we recommend that you download the latest @emph{.tar.gz} file from @emph{https://freem.coherent-logic.com/downloads.cfm}, and follow these steps: @example -$ ./configure --enable-mwapigtk +$ gunzip freem-@emph{}.tar.gz +$ tar xf freem-@emph{}.tar +$ cd freem +$ ./configure # see the Build Configuration section for optional flags $ make $ sudo make install @end example -@item @code{--enable-berkeleydb} (EXPERIMENTAL) -Enables experimental support for using the BerkeleyDB database as a global handler for FreeM global namespaces. Requires that you have the @code{libdb} library, headers, and dependencies installed on your system. - -Please consult your operating system's documentation for the correct commands to install the required libraries. +Once this process has been completed, you may proceed to @emph{Initial Configuration}. -@emph{Example} +Installation from source archive is the most challenging but flexible supported option for advanced users. +@item CVS Repository +If you wish to try the bleeding-edge development version of FreeM, you may do so by following these steps: -@example -$ ./configure --enable-berkeleydb +@verbatim +$ cvs -d :pserver:anonymous@cvs.coherent-logic.com:/home/cvsroot co freem +$ cd freem +$ ./autogen.sh +$ ./configure # see the Build Configuration section for optional flags $ make $ sudo make install -@end example +@end verbatim + +Once this process has been completed, you may proceed to @emph{Initial Configuration}. + +This installation method is by far the most complicated, and is intended only for those who wish to contribute to FreeM development. It is not intended for end users, and no technical support will be provided. + +See the @emph{Contributor Guide} on the @emph{FreeM Wiki} for more information. +@end table +@subsection Build Configuration +@cindex build configuration + +When configuring FreeM with the supplied @code{configure} script, there are some FreeM-specific options that may be used to compile in optional features, or exclude default ones: +@table @asis -@item @code{--without-readline} -Builds FreeM without GNU @code{readline} support, even if @code{readline} is installed on your system. +@item @code{--enable-mwapi} (EXPERIMENTAL) +Enables experimental support for the M Windowing API (ANSI @emph{X11.6-1995}) using the OSF/Motif widget toolkit. Requires that you have the @code{X11}, @code{Xt}, @code{ICE}, and @code{Xm} libraries, as well as all of their C header files. -Please note that building FreeM without GNU @code{readline} will also exclude REPL functionality and all direct-mode utility commands, i.e. @code{events}, @code{tdump}, @code{shmstat}, and @code{shmpages}. +Please consult your operating system's documentation for the correct commands to install the required libraries. @emph{Example} @example -$ ./configure --without-readline +$ ./configure --enable-mwapi $ make $ sudo make install @end example - @end table +@subsection Initial Configuration +Once FreeM is installed, you will need to configure it: + +@enumerate +@item Create a user and group, each named @emph{freem}, under which FreeM will run +@item Add any user accounts that will need to run FreeM to the @emph{freem} group +@item Have all users added in step 2 sign out and sign in for the new group membership to take effect +@item Run @code{fmadm configure} with superuser privileges to create the @code{DEFAULT} environment with @code{SYSTEM} and @code{USER} namespaces and default after-image journal settings, and populate the bundled vendor routines +@item Run @code{fmadm start environment} with superuser privileges to start the @code{DEFAULT} environment +@item Make sure the environment is ready by running @code{fmadm status environment} with superuser privileges +@end enumerate + +@subsubsection Creating Additional Environments +To create additional environments, do the following steps: + +@enumerate +@item Create a new user and group for the environment @emph{(optional)} +@item Run @code{fmadm configure -e=@emph{} -u=@emph{} -g=@emph{} [-E=@emph{true|false}]} @emph{(the @code{-E} flag enables or disables the environment)} +@item Run @code{fmadm start environment -e=@emph{}} to start the environment +@item Run @code{fmadm status environment} to make sure the environment is healthy +@end enumerate + +@subsubsection Additional Customization + +See the FreeM @emph{environment catalog} at @code{@emph{$PREFIX}/etc/freem/env.conf}, and the @emph{fmadm}(1) @code{man} page for more information. + +@emph{$PREFIX} represents the root location of your FreeM installation. This can be @code{/usr/local}, @code{/}, or others, depending on how FreeM was built and installed. + @node Accessing FreeM from C Programs @chapter Accessing FreeM from C Programs