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 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)

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

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 configuration directory may contain subdirectories.

If a subdirectory contains a file with a .ini 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 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.