137 lines
4.9 KiB
Plaintext
137 lines
4.9 KiB
Plaintext
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)
|
|
|
|
Note: Special cases
|
|
Any file named _panelui.ini is ignored
|
|
|
|
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 configuration 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 configuration 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.
|