maintainer.txt:

General notes for the configs directory, root/configs.
'root' refers to the toplevel of the linuxcnc git tree.

-------------------------------------------------------

The configs dir contains a hierarchy of configurations,
each with one or more ini files, that are intended to:

  1) run as-is on a RIP (run-in-place) build
  2) run when copied to a user ~/linuxcnc directory
     by the configuration picker (pickconfig.tcl)

Additionally, demonstration scripts identified by a file
extension .demo, can run standalone to show linuxcnc-related
functionality without requiring start-up of linuxcnc.
A configs directory should not contain both .ini and .demo
files.

Directories for .demo applications by default are offered
for copying to a user directory.  Some apps are not usefully
copied so a directory containing .demo files (and
no .ini files) will not be copied if the directory includes a
file named 'nodemocopy'.

When a desktop shortcut is made for a copied .demo application,
the shortcut will execute the .demo file.  The environment
for files executed by .desktop files  is limited so extra care
is required to ensure that a desktop shortcut created for
a .demo file is usable.

-------------------------------------------------------

The configuraton picker (pickconfig.tcl) walks through
existing _user_ configurations in ~linuxcnc/configs and the
distribution's root/configs directory.  It presents both
existing user configurations and sample configurations.
When a sample configuration is selected the configuration
picker:

  1) creates a directory in ~/linuxcnc/configs for the
     selected item and copies all relevant files and
     directories to the newly created directory.  When
     a name clash occurs, the picker appends a number
     to the directory name to make it distinct.

  2) creates a directory ~/linuxcnc/nc_files (if it
     does not exist).  It creates links in this directory
     to the system locations for examples and libraries
     (examples, ngcgui_lib, gladevcp_lib)

  3) edits all ini files being copied so that
     [DISPLAY]PROGRAM_PREFIX = ~/linuxcnc/nc_files.

A similar process occurs for demonstration (.demo) files when
directories for .demo files are copied (only when no file
named 'nodemocopy' exists).

Most general purpose demonstration scripts can be located
in the directory named: root/configs/apps and its
subdirectories.

-------------------------------------------------------

A configuration directory may contain subdirectories.

If a subdirectory contains a file with a .ini or .demo
suffix, it is considered to be a selectable configuration
directory and will be included in the selection tree
provided by the configuraton picker.

Subdirectories required for other purposes must not
contain a file with a .ini or .demo suffix.

When a subdirectory requires file or directory resources
that are shared by other configurations, it should use a
symlink to a parent's file or directory.  The configuration
picker copies the file or directory referred to by
the symlink.  Use of symlinks in this manner reduces
the number of real files in the git tree.

-------------------------------------------------------

Occasional relocation of configuration directories within
the root/configs tree is anticipated.  To minimize the
editing of files required for such moves, the following
guidelines apply:

Ini files may need to refer to root/nc_files resources.
The most common case, [DISPLAY]PROGRAM_PREFIX is handled
as described above.  Other examples include path items
such as:
   [RS274NGC]SUBROUTINE_PATH
   [RS274NGC]USER_M_PATH

Items like these should refer to ../../nc_files and use
appropriate symlinks within the configuration directory.

Example:
   A configuration named: root/configs/sim/axis/ngcgui
   could, for example, refer to:
   [RS274NGC]SUBROUTINE_PATH = ../../nc_files/ngcgui_lib:../../nc_files/ngcgui_lib/utilitysubs

   The root/configs/sim directory must contain a symlink:
      root/configs/sim/nc_files --> ../../nc_files
   so that the ini file reference will work in rip builds.

These conventions work because:

   1) Copied user configurations
      have configs located in --------- ~/linuxcnc/configs/
      and nc_files located as --------- ~/linuxcnc/nc_files/

      So if ini files always refer to root/nc_files as
        ../../nc_files
      they will not require modifications when copied to
      users' directories nor when moved within the
      distribution tree

  2) Since symlinks are usually required to make ../../nc_files
     resolve to root/nc_files (for RIP usage).

     Because of this, symlinks for nc_files are never copied
     to user dirs.


-------------------------------------------------------
Any configuration directory may include a file named
  maintainer.txt
to include comments or details about maintaining the
configuration.  These files will not be copied to user's
configuration directories.