ini: Fix the ini-file parser and Tcl interaction

ini: Expose enum mapping functions in python
ini: Improve linuxcnc pre-run ini-file check
ini: Reintroduce to remove comments in values

Author: BsAtHome

debian/linuxcnc.install.in

@@ -41,6 +41,7 @@ usr/bin/latency-plot
 usr/bin/latency-test
 usr/bin/lineardelta
 usr/bin/linuxcnc
+usr/bin/linuxcnc_check_ini
 usr/bin/linuxcnc_info
 usr/bin/linuxcnc_module_helper
 usr/bin/linuxcnc_var

debian/linuxcnc.manpages.in

@@ -39,6 +39,7 @@ usr/share/man/man1/latency-plot.1
 usr/share/man/man1/latency-test.1
 usr/share/man/man1/lineardelta.1
 usr/share/man/man1/linuxcnc.1
+usr/share/man/man1/linuxcnc_check_ini.1
 usr/share/man/man1/linuxcnc_info.1
 usr/share/man/man1/linuxcnclcd.1
 usr/share/man/man1/linuxcncmkdesktop.1

docs/man/.gitignore

@@ -48,6 +48,7 @@ man1/latency-histogram.1
 man1/latency-plot.1
 man1/latency-test.1
 man1/lineardelta.1
+man1/linuxcnc_check_ini.1
 man1/linuxcnc_info.1
 man1/linuxcnc_module_helper.1
 man1/linuxcnc_var.1

docs/src/config/ini-config.adoc

@@ -46,7 +46,6 @@ In this list, the DISPLAY variable will be set to axis because the other one is
 If someone carelessly edits a list like this and leaves two of the lines uncommented, the first one encountered will be used.
 
 Note that inside a variable's value, the "#" and ";" characters are part of the value:
-
 [source,{ini}]
 ----
 # Below does not result in INCORRECT=value
@@ -116,26 +115,26 @@ ini.1.max_velocity \
 ini.2.max_velocity
 ----
 
-A specific variable in a specific sections is often denoted in the documentation as [SECTION]VARIABLE.
+A specific variable in a specific sections is often denoted in the documentation as `[SECTION]VARIABLE`.
 This specification mirrors the same way they are specified in HAL files for expansion.
 
 Variable values may embed special characters in literal or escaped forms.
 Single or double quotes are not treated as special and are a literal part of the value.
 Values also support all common escape formats and full Unicode:
 
-* control: \\[abfnrtv]
-* octal: \\[0-2][0-7]{0,2}
-* hex: \\x[0-9a-fA-F]{2}
-* UTF-16: \\u[0-9a-fA-F]{4}
-* UTF-32: \\U[0-9a-fA-F]{8}
+* control: `\[abfnrtv]`
+* octal: `\[0-2][0-7]{0,2}`
+* hex: `\x[0-9a-fA-F]{2}`
+* UTF-16: `\u[0-9a-fA-F]{4}`
+* UTF-32: `\U[0-9a-fA-F]{8}`
 
 The resulting value is always converted into UTF-8 and checked for validity.
 It is not allowed to embed NUL characters either literally or by using an escape.
 
 Leading and trailing white space is normally removed from a value.
-You can add leading and trailing space in a value by using an escaped value for space (\\x20) as first or last character.
+You can add leading and trailing space in a value by using an escaped value for space (`\x20`) as first or last character.
 Spaces inside a value are automatically part of the value.
-Tabs and newlines can be added using \\t and \\n.
+Tabs and newlines can be added using `\t` and `\n`.
 
 .Value Escape Example
 [source,{ini}]
@@ -148,10 +147,10 @@ STRING = Hello\
 World\
 !
 
-SMILE = \\370\\237\\230\\200 = 😀
-SMILE = \\xf0\\x9f\\x98\\x80 = 😀
-SMILE = \\ud83d\\ude00 = 😀
-SMILE = \\U0001f600 = 😀
+SMILE = \370\237\230\200 = 😀
+SMILE = \xf0\x9f\x98\x80 = 😀
+SMILE = \ud83d\ude00 = 😀
+SMILE = \U0001f600 = 😀
 ----
 
 Variables' value can have types associated when they are read by LinuxCNC.
@@ -171,18 +170,18 @@ Plain old 32-bit integers are marked `int` and are always signed.
 The default number base is decimal. Alternative bases may be specified using a prefix.
 The complete list of valid integer numbers:
 
-* \[0-9]+ - decimal
-* 0x\[0-9A-Fa-f]+ - hexadecimal
-* 0o\[0-7]+ - octal
-* 0b\[01]+ - binary
+* `[0-9]+` (decimal)
+* `0x[0-9A-Fa-f]+` (hexadecimal)
+* `0o[0-7]+` (octal)
+* `0b[01]+` (binary)
 
 Signed integers may be preceded by a plus (+) or minus (-) sign, regardless number base.
 Unsigned integers will generate a warning if they are preceded by a minus (-) sign upon conversion.
 
 Boolean values are case insensitive and allow the following words:
 
-* true/enabled - `TRUE`, `YES` `ON` or `1`
-* false/disabled - `FALSE`, `NO` `OFF` or `0`
+* true/enabled - `TRUE`, `YES`, `ON` or `1`
+* false/disabled - `FALSE`, `NO`, `OFF` or `0`
 
 Enumerations are a set of keywords defined by LinuxCNC and interpreted to mean a setting, value or functionality.
 The exact values are declared in the individual variable description and the variables are marked with `enum`.
@@ -253,7 +252,8 @@ G10 L20 P0 Z#<_ini[probe]z_offset>
 [[sub:ini:include]]
 === Include Files(((INI File,Components,Include)))
 
-An INI file may include the contents of another file by using a #INCLUDE directive.
+An INI file may include the contents of another file by using a `#INCLUDE` directive.
+The `#INCLUDE` directive must be in upper case, start in the first column of the line and have at least one space after it.
 
 .#INCLUDE Format
 [source,{ini}]
@@ -268,7 +268,7 @@ The filename can be specified as:
 * an absolute file name (starts with a /)
 * a user-home-relative file name (starts with a ~/)
 
-Multiple #INCLUDE directives are supported.
+Multiple `#INCLUDE` directives are supported.
 
 .#INCLUDE Examples
 [source,{ini}]
@@ -280,7 +280,7 @@ Multiple #INCLUDE directives are supported.
 #INCLUDE ~/linuxcnc/myincludes/rs274ngc.inc
 ----
 
-The #INCLUDE directives are supported up to 16 levels -- an included file may include additional files up to 16 levels deep.
+The `#INCLUDE` directives are supported up to 16 levels -- an included file may include additional files up to 16 levels deep.
 Recursive inclusion of files is detected and flagged as an error.
 The recommended file extension is '.inc'.
 Do _not_ use a file extension of '.ini' for included files.
@@ -331,12 +331,12 @@ Descriptions of the interfaces are in the Interfaces section of the User Manual.
   The example above will display only one decimal digit.
   Formatting follows Python practice: https://docs.python.org/2/library/string.html#format-specification-mini-language .
   An error will be raised if the format can not accept a floating-point value.
-* `CONE_BASESIZE = .25` - Override the default cone/tool base size of .5 in the graphics display. Valid values are between 0.025 and 2.0.
-* `DISABLE_CONE_SCALING = TRUE` - Any non-empty value (including "0") will override the default behavior of scaling the cone/tool size using the extents of the currently loaded G-code program in the graphics display.
-* `GCODE_VIEW_TOOL_MIN_DIA = 2.0` - If the tool diameter is very small, but non-zero then the displayed cylinder may be too small to see.
+* `CONE_BASESIZE = .25` - (real) Override the default cone/tool base size of .5 in the graphics display. Valid values are between 0.025 and 2.0.
+* `DISABLE_CONE_SCALING = TRUE` - (bool) Will override the default behavior of scaling the cone/tool size using the extents of the currently loaded G-code program in the graphics display.
+* `GCODE_VIEW_TOOL_MIN_DIA = 2.0` - (real) If the tool diameter is very small, but non-zero then the displayed cylinder may be too small to see.
    This could happen if the tool diameter was being used as a wear offset. This setting will cause the tool cone to be displayed
    rather than a tool cylinder.
-* `MAX_FEED_OVERRIDE = 1.2` - The maximum feed override the user may select.
+* `MAX_FEED_OVERRIDE = 1.2` - (real) The maximum feed override the user may select.
   1.2 means 120% of the programmed feed rate.
 * `MIN_SPINDLE_OVERRIDE = 0.5` - (real) The minimum spindle override the user may select.
   0.5 means 50% of the programmed spindle speed. (This is used to set the minimum spindle speed.)
@@ -373,7 +373,7 @@ Descriptions of the interfaces are in the Interfaces section of the User Manual.
   An under powered CPU may see improvement with a longer setting.
   Usually the default is fine.
 * `PREVIEW_TIMEOUT = 5` - Timeout (in seconds) for loading graphical preview of G-code. Currently AXIS only.
-* `HOMING_PROMPT = TRUE` - Any non-empty value (including "0") will enable showing a prompt message with homing request, when the Power On button is pressed in AXIS GUI. Pressing the "Ok" button in prompt message is equivalent to pressing the "Home All" button(or the Ctrl-HOME key).
+* `HOMING_PROMPT = TRUE` - (bool) Will enable showing a prompt message with homing request, when the Power On button is pressed in AXIS GUI. Pressing the "Ok" button in prompt message is equivalent to pressing the "Home All" button(or the Ctrl-HOME key).
 * `FOAM_W = 1.5` sets the foam W height.
 * `FOAM_Z = 0` sets the foam Z height.
 * `GRAPHICAL_MAX_FILE_SIZE = 20` largest size (in mega bytes) that will be displayed graphically.
@@ -425,9 +425,9 @@ See <<cha:gmoccapy,GMOCCAPY>> document for GMOCCAPY details.
 * `PYVCP_POSITION = BOTTOM` - The placement of the PyVCP panel in the AXIS user interface.
   If this variable is omitted the panel will default to the right side.
   The only valid alternative is `BOTTOM`. See the <<cha:pyvcp,PyVCP Chapter>> for more information.
-* `LATHE = 1` - Any non-empty value (including "0") causes axis to use "lathe mode" with a top view and with Radius and Diameter on the DRO.
-* `BACK_TOOL_LATHE = 1` - Any non-empty value (including "0") causes axis to use "back tool lathe mode" with inverted X axis.
-* `FOAM = 1` - Any non-empty value (including "0") causes axis to change the display for foam-cutter mode.
+* `LATHE = 1` - (bool) Causes axis to use "lathe mode" with a top view and with Radius and Diameter on the DRO.
+* `BACK_TOOL_LATHE = 1` - (bool) Causes axis to use "back tool lathe mode" with inverted X axis.
+* `FOAM = 1` - (bool) Causes axis to change the display for foam-cutter mode.
 * `GEOMETRY = XYZABCUVW` - Controls the *preview* and *backplot* of motion.
   This item consists of a sequence of axis letters and control characters, optionally preceded with a "-" sign:
 
@@ -805,26 +805,26 @@ The applications can be started after a specified delay to allow for GUI-depende
   If no executable file is found using these names, then the user search PATH is used to find the application. +
   Examples:
 ** Simulate inputs to HAL pins for testing (using sim_pin -- a simple GUI to set inputs to parameters, unconnected pins, or signals with no writers):
-+
+
 [source,{ini}]
 ----
 APP = sim_pin motion.probe-input halui.abort motion.analog-in-00
 ----
 ** Invoke halshow with a previuosly saved watchlist.
    Since LinuxCNC sets the working directory to the directory for the INI file, you can refer to files in that directory (example: my.halshow):
-+
+
 [source,{ini}]
 ----
 APP = halshow my.halshow
 ----
 ** Alternatively, a watchlist file identified with a full pathname could be specified:
-+
+
 [source,{ini}]
 ----
 APP = halshow ~/saved_shows/spindle.halshow
 ----
 ** Open halscope using a previously saved configuration:
-+
+
 [source,{ini}]
 ----
 APP = halscope -i my.halscope
@@ -846,9 +846,9 @@ ARC_BLEND_RAMP_FREQ = 100
 
 The [TRAJ] section contains general parameters for the trajectory planning module in 'motion'.
 
-* `ARC_BLEND_ENABLE = 1` - Turn on new TP.
+* `ARC_BLEND_ENABLE = 1` - (bool) Turn on new TP.
   If set to 0 TP uses parabolic blending (1 segment look ahead) (Default: 1).
-* `ARC_BLEND_FALLBACK_ENABLE = 0` - Optionally fall back to parabolic blends if the estimated speed is faster.
+* `ARC_BLEND_FALLBACK_ENABLE = 0` - (bool) Optionally fall back to parabolic blends if the estimated speed is faster.
   However, this estimate is rough, and it seems that just disabling it gives better performance (Default: 0).
 * `ARC_BLEND_OPTIMIZATION_DEPTH = 50` - Look ahead depth in number of segments.
 +

docs/src/man/man1/linuxcnc_check_ini.1.adoc

@@ -0,0 +1,61 @@
+= linuxcnc_check_ini(1)
+
+== NAME
+
+linuxcnc_check_ini - LinuxCNC INI-file configuration checker
+
+== SYNOPSIS
+
+*linuxcnc_check_ini* [_-e_] [_-h_] _INIfile_
+
+== DESCRIPTION
+
+The *linuxcnc_check_ini* program is used to verify the LinuxCNC primary
+configuration. It takes the specified _INIfile_ and performs a set of sanity
+checks on the variables in various sections.
+
+This program is called automatically from *linuxcnc(1)* as to warn the user of
+problems that may exist in the configuration. The tests are not exhaustive
+and *linuxcnc_check_ini* does _not_ protect your machine or hardware. It merely
+ensures some basic consistency in the configuration setup. You must not rely on
+passing the *linuxcnc_check_ini* tests to have a functional machine.
+
+== OPTIONS
+
+*-e*,*--error*::
+  Treat warnings as errors
+
+*-h*,*--help*::
+  Shows brief help message
+
+== EXIT VALUE
+
+The exit value is 0 (zero) when no errors are detected and the program runs
+successfully.
+
+The exit value is 1 (one) if any errors are detected.
+Additionally, if the *--error* option was specified, then any detected warnings
+also cause the exit value be 1 (one).
+
+The exit value is 2 (two) in case of any other problem.
+
+== SEE ALSO
+
+*linuxcnc(1)*
+
+== AUTHOR
+
+This man page written by B.Stultiens, as part of the LinuxCNC Enhanced
+Machine Controller project.
+
+== REPORTING BUGS
+
+Please report any bugs at https://github.com/LinuxCNC/linuxcnc.
+
+== COPYRIGHT
+
+Copyright © 2026 The LinuxCNC authors.
+
+This is free software; see the source for copying conditions. There is
+NO warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR
+PURPOSE.

scripts/linuxcnc.in

@@ -356,41 +356,6 @@ if [ -z "$INIFILE" ] ; then
     exit 0
 fi
 
-# There is an INI-reader in the Tcl code (parse_ini in tcl/linuxcnc.tcl), but
-# that cannot read or enforce the new INI-file format. The Tcl version does not
-# handle includes, strings, continuations and comments. The includes were
-# previously handled in here by generating a patched-up INI-file. We now do the
-# same, but ensure the enforce the new format. We can generate a predigested
-# version of the INI-file using the inivalue program.
-# FIXME: This hack should be removed as soon as all the legacy Tcl code using
-# INI values has been replaced with python code.
-function make_ini_for_tcl() {
-    inifile="$1"
-    [ -r "$inifile" ] || { echo "E: Cannot read '$inifile'"; exit 1; }
-    inidir="$(dirname "$inifile")"
-    outfile="$inidir/$(basename "$inifile").expanded"
-    # Fall back to a per-user cache dir if the inifile's directory is not
-    # writable (e.g. installed sample configs under /usr/share/doc/linuxcnc/).
-    if ! [ -w "$inidir" ]; then
-        cachedir="${XDG_RUNTIME_DIR:-${TMPDIR:-/tmp}}/linuxcnc-$UID"
-        mkdir -p "$cachedir" || { echo "E: Could not create cache dir '$cachedir'"; exit 1; }
-        outfile="$cachedir/$(basename "$inifile").expanded"
-    fi
-    export LINUXCNC_INI_EXPANDED="$outfile"
-    true >|"$outfile" || { echo "E: Could not create expanded inifile '$outfile' for Tcl"; exit 1; }
-    {
-        echo "#*** Source: $inifile"
-        echo "#*** Created: $(date)"
-        echo "#*** Autogenerated INI-file using linuxcnc for tcl/linuxcnc.tcl:parse_ini()"
-        echo
-    } >> "$outfile"
-    # For all sections, output the variables as parsed
-    for s in $(inivalue --sections "$inifile"); do
-        echo "[$s]" >> "$outfile"
-        inivalue --variables --content --sec "$s" "$inifile" >> "$outfile"
-    done
-}
-
 function split_app_items () {
   app_name=$1
   shift
@@ -443,10 +408,6 @@ function run_applications () {
 # a parse error in the file or it is empty.
 inivalue "$INIFILE" > /dev/null || { echo "E: The INI-file contains errors that need to be fixed."; exit 1; }
 
-# The resulting INI-file for Tcl will be called "${INIFILE}.expanded"
-# See comment above the function why this is necessary.
-make_ini_for_tcl "$INIFILE"
-
 # delete directories from path, save name only
 INI_NAME="${INIFILE##*/}"
 INI_DIR="${INIFILE%/*}"
@@ -525,12 +486,12 @@ if [ "$retval" != "1.1" ]; then
     esac
 fi
 
-@TCLSH@ "$HALLIB_DIR/check_config.tcl" "$INIFILE"
+linuxcnc_check_ini "$INIFILE"
 exitval=$?
 case "$exitval" in
   0) ;;
-  1) echo "check_config validation failed"; exit $exitval ;;
-  *) echo "check_config validation failed in an unexpected way."; exit $exitval ;;
+  1) echo "linuxcnc_check_ini validation failed"; exit $exitval ;;
+  *) echo "linuxcnc_check_ini validation failed in an unexpected way."; exit $exitval ;;
 esac
 # 2.2. get param file
 

src/Makefile

@@ -688,6 +688,7 @@ install-kernel-indep: install-dirs
 	$(EXE) ../scripts/gladevcp_demo $(DESTDIR)$(bindir)
 	$(EXE) ../scripts/linuxcncmkdesktop $(DESTDIR)$(bindir)
 	$(EXE) ../bin/update_ini $(DESTDIR)$(bindir)
+	$(EXE) ../bin/linuxcnc_check_ini $(DESTDIR)$(bindir)
 	$(EXE) ../scripts/halreport $(DESTDIR)$(bindir)
 	$(FILE) $(filter ../lib/%.a ../lib/%.so.0 ../lib/%.so.1,$(TARGETS)) $(DESTDIR)$(libdir)
 	cp --no-dereference $(wildcard ../lib/*.so) $(DESTDIR)$(libdir)

src/emc/ini/Submakefile

@@ -46,4 +46,12 @@ TARGETS += ../bin/inivar
 	$(ECHO) Copying python script $(notdir $@)
 	$(Q)(echo '#!$(PYTHON)'; sed '1 { /^#!/d; }' $<) > $@.tmp && chmod +x $@.tmp && mv -f $@.tmp $@
 
+# Ini-file checker at linuxcnc start
+../bin/linuxcnc_check_ini: emc/ini/linuxcnc_check_ini.py
+	@$(ECHO) Syntax checking python script $(notdir $@)
+	$(Q)$(PYTHON) -m py_compile $<
+	$(ECHO) Copying python script $(notdir $@)
+	$(Q)(echo '#!$(PYTHON)'; sed '1 { /^#!/d; }' $<) > $@.tmp && chmod +x $@.tmp && mv -f $@.tmp $@
+
 PYTARGETS += ../bin/update_ini
+PYTARGETS += ../bin/linuxcnc_check_ini

src/emc/ini/iniaxis.cc

@@ -62,15 +62,15 @@ static int loadAxis(int axis, const IniFile &ini)
     std::string axisSection = fmt::format("AXIS_{}", "XYZABCUVW"[axis]);
 
     // set min position limit
-    double limit = ini.findRealV("MIN_LIMIT", axisSection, -1e99);
+    double limit = ini.findRealV("MIN_LIMIT", axisSection, DEFAULT_AXIS_MIN_LIMIT);
     if (0 != emcAxisSetMinPositionLimit(axis, limit)) {
         print_dbg_config("emcAxisSetMinPositionLimit");
         return -1;
     }
     old_inihal_data.axis_min_limit[axis] = limit;
 
     // set max position limit
-    limit = ini.findRealV("MAX_LIMIT", axisSection, 1e99);
+    limit = ini.findRealV("MAX_LIMIT", axisSection, DEFAULT_AXIS_MAX_LIMIT);
     if (0 != emcAxisSetMaxPositionLimit(axis, limit)) {
         print_dbg_config("emcAxisSetMaxPositionLimit");
         return -1;