basic_sim.tcl: create equivalent halcmds halfile

per the included, updated documentation

Signed-off-by: Dewey Garrett <dgarrett@panix.com>

configs/.gitignore

@@ -12,3 +12,4 @@ position*.txt
 !common/*.hal
 *.ini.expanded
 hallib
+*_cmds.hal

docs/src/getting-started/updating-linuxcnc.txt

@@ -855,19 +855,61 @@ component is loaded and connected.
 additional loaded hal components to simulate the inertia of a rotating
 spindle mass.
 
-These functions are activated by default but can be excluded using
+The functions are activated by default but can be excluded using
-options '-no_make_ddts, -no_simulated_home, -no_use_hal_manualtoolchange,
+options: '-no_make_ddts', '-no_simulated_home', '-no_use_hal_manualtoolchange',
--no_sim_spindle'.  For example, to omit ddts:
+'-no_sim_spindle'.
+
+For example, to omit creation of ddts:
 
 ----
 HALFILE = LIB:basic_sim.tcl -no_make_ddts
 ----
 
-Omitting one or more of the core functions allow a user to test without
+Omitting one or more of the core functions allows testing without without
-the function or add new HALFILEs to implement or expand on the
+the function or addition of new HALFILEs to implement or expand on the
 functionality.
 
-=== Notes
+==== Equivalent Hal commands file
+
+When LIB:basic_sim.tcl is used, an equivalent halfile is created (in the
+configuration directory) to show the halcmd commands issued.   The file
+name is based on the name of the inifile with '_cmds' appended to
+the basename and a conventional '.hal' file extension. Example:
+
+----
+inifilename:            example.ini
+equivalent_halfilename: example_cmds.hal
+----
+
+The equivalent halfile file supersedes previous instances of files with
+the same filename.  Inifile variables substitutions specified in the
+inifile and interpreted by halcmd are automatically substituted in the
+created halfile.  If there are [HAL]HALFILEs specified before
+LIB:basic_sim.tcl, their halcmd commands are included too.
+
+The equivalent halfile can be used to create a new configuration based on
+the original configuration made with LIB:basic_sim.tcl with the
+following steps:
+
+1) Run the simulator configuration to create a new equivalent halfile,
+for example: 'example_cmds.hal'.
+
+To use this new equivalent halfile in the original simulator
+configuration inifile (or a copy of it), edit to change:
+
+----
+[HAL]
+HALFILE = LIB:basic_sim.tcl other_parameters
+----
+
+to:
+
+----
+[HAL]
+HALFILE = ./example_cmds.hal
+----
+
+==== Notes
 
 All components and connections made by LIB:basic_sim.tcl can be viewed
 using halcmd.  The entire hal configuration (except for userspace

lib/hallib/basic_sim.tcl

@@ -4,8 +4,10 @@
 # By default, the script makes and connects ddts, simulated_home,
 # spindle, and hal_manualtoolchange components.
 #
-# Options are available to disable specific hal components and
+# Options are available to 
-# connections
+#   a) disable specific hal components and connections
+#   b) save a halfile equivalent to the hal commands executed by
+#      this script (and any prior executed hal commands)
 #
 # Coordinate letters and number_of_joints are determined from the usual
 # ini # file settings.
@@ -29,6 +31,7 @@
 
 #begin-----------------------------------------------------------------
 source [file join $::env(HALLIB_DIR) sim_lib.tcl]
+set save_options {}
 
 if [catch {check_ini_items} msg] {
   puts "\nbasic_sim.tcl ERROR: $msg\n"
@@ -56,7 +59,13 @@ if {[lsearch -nocase $::argv -no_simulated_home] < 0} {
 }
 if {[lsearch -nocase $::argv -no_use_hal_manualtoolchange] < 0} {
   use_hal_manualtoolchange
+  lappend save_options use_hal_manualtoolchange
 }
 if {[lsearch -nocase $::argv -no_sim_spindle] < 0} {
   sim_spindle
 }
+
+# make a halfile (inifilename_cmds.hal) with equivalent hal commands
+set savefilename \
+    ./[file rootname [file tail $::env(INI_FILE_NAME)]]_cmds.hal
+save_hal_cmds $savefilename $save_options

lib/hallib/sim_lib.tcl

@@ -374,3 +374,50 @@ proc sim_spindle {} {
   addf sim_spindle  servo-thread
 } ;# sim_spindle
 
+proc save_hal_cmds {savefilename {options ""} } {
+  set tmpfile /tmp/save_hal_cmds_tmp
+  set date [clock format [clock seconds]]
+  set script [info script]
+  set fd [open $savefilename w] ;# overwrite any existing file
+  puts $fd "# $date
+#
+# This file:    $savefilename
+# Created by:   $script
+# With options: $::argv
+# From inifile: $::env(INI_FILE_NAME)
+# 
+# This file contains the hal commands produced by [file tail $script]
+# (and any hal commands executed prior to its execution).
+#
+# To use $savefilename in the original inifile (or a copy of it),
+# edit to change:
+#     \[HAL\]
+#     HALFILE = LIB:basic_sim.tcl parameters
+# to:
+#     \[HAL\]
+#     HALFILE = $savefilename
+#
+# Note: Inifile Variables substitutions specified in the inifile
+#       and interpreted by halcmd are automatically substituted
+#       in the created halfile ($savefilename).
+#       
+"
+  if {[lsearch $options use_hal_manualtoolchange] >= 0} {
+    puts $fd "# user space components"
+    puts $fd "loadusr -W hal_manualtoolchange"
+    puts $fd ""
+  }
+  close $fd
+    
+  hal save all $tmpfile
+
+  set fd [open $savefilename a]
+  set ftmp [open $tmpfile r]
+  while {![eof $ftmp]} {
+    gets $ftmp line
+    puts $fd $line
+  } ;# while
+  close $ftmp
+  file delete $tmpfile
+  close $fd
+} ;# save_hal_cmds