From 4002b750678f2fbbe3bd61852529f39112436af3 Mon Sep 17 00:00:00 2001 From: Luca Toniolo Date: Tue, 28 Apr 2026 10:00:58 +0800 Subject: [PATCH] docs/getting-started -document RIP vs install copy behavior in pickconfig Configuration Selector copies sample configs to ~/linuxcnc/configs on package installs but runs them in place on RIP builds. This was documented only in pickconfig.tcl source comments. Add user-facing notes covering when the copy happens (package install vs RIP) and the debug_pickconfig=1 override for forcing a copy from a RIP build. Refs #3924. --- .../src/getting-started/running-linuxcnc.adoc | 29 +++++++++++++++++++ 1 file changed, 29 insertions(+) diff --git a/docs/src/getting-started/running-linuxcnc.adoc b/docs/src/getting-started/running-linuxcnc.adoc index 719ed701195..bd75c8f655b 100644 --- a/docs/src/getting-started/running-linuxcnc.adoc +++ b/docs/src/getting-started/running-linuxcnc.adoc @@ -151,6 +151,35 @@ for a configuration to a new subdirectory of ~/linuxcnc/configs created directory will include at least one INI file (iniflename.ini) that is used to describe a specific configuration. +=== When the copy happens + +The Configuration Selector decides whether to copy a sample +configuration to ~/linuxcnc/configs based on where the source +configuration lives: + +* *Package install (deb, rpm, distro packages)*: sample configurations + live under a system path. The selector copies the configuration to + ~/linuxcnc/configs before running it, so edits never touch the + system-wide files. +* *Run-In-Place (RIP) build*: the source tree is normally writable by + the user who built it, so the selector runs the configuration + directly from the source tree without copying. Edits made through + the configuration apply to the files in the RIP tree. + +=== Forcing a copy from a RIP build + +To test the copy-and-run path from a RIP build (or to keep a +personal copy of a sample configuration outside the source tree), +set the `debug_pickconfig` environment variable before launching +LinuxCNC: + +---- +debug_pickconfig=1 linuxcnc +---- + +With this set, the selector copies the chosen sample configuration +to ~/linuxcnc/configs even though the RIP source tree is writable. + File resources within the copied directory will typically include one or more INI file (filename.ini) for related configurations and a tool table file (toolfilename.tbl).