From af8ae79dff9c82735b37eaac1fc9bfb38314bf2e Mon Sep 17 00:00:00 2001 From: Kevin Day Date: Sun, 8 Jan 2023 10:19:18 -0600 Subject: [PATCH] Update: Documents, restructuring and switching to more up to date files. --- .../standards/controller/documents/actions.txt | 83 +++ documents/standards/controller/documents/entry.txt | 224 ++++++++ documents/standards/controller/documents/exit.txt | 178 ++++++ .../standards/controller/documents/packet.txt | 81 +++ documents/standards/controller/documents/rule.txt | 238 ++++++++ .../standards/controller/documents/simulate.txt | 35 ++ documents/standards/controller/documents/time.txt | 51 ++ documents/standards/controller/entry.txt | 139 ----- documents/standards/controller/exit.txt | 125 ---- documents/standards/controller/packet.txt | 55 -- documents/standards/controller/rule.txt | 96 ---- .../standards/controller/specifications/entry.txt | 145 +++++ .../standards/controller/specifications/exit.txt | 131 +++++ .../standards/controller/specifications/packet.txt | 61 ++ .../standards/controller/specifications/rule.txt | 102 ++++ .../standards/controller/specifications/task.txt | 14 + .../controller/{ => specifications}/time.txt | 0 documents/standards/controller/task.txt | 7 - documents/standards/fake/documents/fakefile.txt | 627 +++++++++++++++++++++ documents/standards/fake/documents/settings.txt | 573 +++++++++++++++++++ .../fake/{ => specifications}/defines.txt | 0 .../fake/{ => specifications}/dependencies.txt | 2 +- .../fake/{ => specifications}/fakefile.txt | 2 +- .../fake/{ => specifications}/settings.txt | 1 + .../fll/{ => specifications}/fss-0000.txt | 0 .../fll/{ => specifications}/fss-0001.txt | 0 .../fll/{ => specifications}/fss-0002.txt | 2 +- .../fll/{ => specifications}/fss-0003.txt | 16 +- .../fll/{ => specifications}/fss-0004.txt | 0 .../fll/{ => specifications}/fss-0005.txt | 0 .../fll/{ => specifications}/fss-0006.txt | 0 .../fll/{ => specifications}/fss-0007.txt | 0 .../fll/{ => specifications}/fss-0008.txt | 0 .../fll/{ => specifications}/fss-0009.txt | 0 .../fll/{ => specifications}/fss-000a.txt | 0 .../fll/{ => specifications}/fss-000b.txt | 0 .../fll/{ => specifications}/fss-000c.txt | 0 .../fll/{ => specifications}/fss-000d.txt | 0 .../fll/{ => specifications}/fss-000e.txt | 0 .../fll/{ => specifications}/fss-000f.txt | 0 .../standards/fll/{ => specifications}/fss.txt | 0 .../fll/{ => specifications}/iki-0000.txt | 0 .../fll/{ => specifications}/iki-0001.txt | 0 .../fll/{ => specifications}/iki-0002.txt | 0 .../standards/fll/{ => specifications}/iki.txt | 0 .../standards/fll/{ => specifications}/time.txt | 0 46 files changed, 2555 insertions(+), 433 deletions(-) create mode 100644 documents/standards/controller/documents/actions.txt create mode 100644 documents/standards/controller/documents/entry.txt create mode 100644 documents/standards/controller/documents/exit.txt create mode 100644 documents/standards/controller/documents/packet.txt create mode 100644 documents/standards/controller/documents/rule.txt create mode 100644 documents/standards/controller/documents/simulate.txt create mode 100644 documents/standards/controller/documents/time.txt delete mode 100644 documents/standards/controller/entry.txt delete mode 100644 documents/standards/controller/exit.txt delete mode 100644 documents/standards/controller/packet.txt delete mode 100644 documents/standards/controller/rule.txt create mode 100644 documents/standards/controller/specifications/entry.txt create mode 100644 documents/standards/controller/specifications/exit.txt create mode 100644 documents/standards/controller/specifications/packet.txt create mode 100644 documents/standards/controller/specifications/rule.txt create mode 100644 documents/standards/controller/specifications/task.txt rename documents/standards/controller/{ => specifications}/time.txt (100%) delete mode 100644 documents/standards/controller/task.txt create mode 100644 documents/standards/fake/documents/fakefile.txt create mode 100644 documents/standards/fake/documents/settings.txt rename documents/standards/fake/{ => specifications}/defines.txt (100%) rename documents/standards/fake/{ => specifications}/dependencies.txt (94%) rename documents/standards/fake/{ => specifications}/fakefile.txt (99%) rename documents/standards/fake/{ => specifications}/settings.txt (99%) rename documents/standards/fll/{ => specifications}/fss-0000.txt (100%) rename documents/standards/fll/{ => specifications}/fss-0001.txt (100%) rename documents/standards/fll/{ => specifications}/fss-0002.txt (96%) rename documents/standards/fll/{ => specifications}/fss-0003.txt (72%) rename documents/standards/fll/{ => specifications}/fss-0004.txt (100%) rename documents/standards/fll/{ => specifications}/fss-0005.txt (100%) rename documents/standards/fll/{ => specifications}/fss-0006.txt (100%) rename documents/standards/fll/{ => specifications}/fss-0007.txt (100%) rename documents/standards/fll/{ => specifications}/fss-0008.txt (100%) rename documents/standards/fll/{ => specifications}/fss-0009.txt (100%) rename documents/standards/fll/{ => specifications}/fss-000a.txt (100%) rename documents/standards/fll/{ => specifications}/fss-000b.txt (100%) rename documents/standards/fll/{ => specifications}/fss-000c.txt (100%) rename documents/standards/fll/{ => specifications}/fss-000d.txt (100%) rename documents/standards/fll/{ => specifications}/fss-000e.txt (100%) rename documents/standards/fll/{ => specifications}/fss-000f.txt (100%) rename documents/standards/fll/{ => specifications}/fss.txt (100%) rename documents/standards/fll/{ => specifications}/iki-0000.txt (100%) rename documents/standards/fll/{ => specifications}/iki-0001.txt (100%) rename documents/standards/fll/{ => specifications}/iki-0002.txt (100%) rename documents/standards/fll/{ => specifications}/iki.txt (100%) rename documents/standards/fll/{ => specifications}/time.txt (100%) diff --git a/documents/standards/controller/documents/actions.txt b/documents/standards/controller/documents/actions.txt new file mode 100644 index 0000000..bbe70f5 --- /dev/null +++ b/documents/standards/controller/documents/actions.txt @@ -0,0 +1,83 @@ +# fss-0002 iki-0000 +# +# license: open-standard-license-1.0 +# +# This file (assumed to be named actions.txt) can be more easily read using the following iki_read commands: +# iki_read actions.txt +Q -w -W code '"' '"' +# +# To read the "Actions Documentation" section of this file, use this command sequence: +# fss_basic_list_read actions.txt +Q -cn "Actions Documentation" | iki_read +Q -w -W code '"' '"' +# + +Actions Documentation: + This describes the intent and purpose of the actions provided for individual Rules (or things related to a Rule). + + Each Action represents a specific intent and purpose but many of these actions are customizable via the rule file. + One should expect an Action to operate as described here but the system administrator or distributor is fully capable of doing something different. + For those doing something different, appropriate documentation is suggested. + + These actions should be usable by any code:"control" program that communicates with this code:"controller" program. + Should any code:"control" or code:"controller" program implementation not support any particular Action for any reason, one should report that the Action is unsupported. + + - Freeze Action\: + The Freeze Action is an extension of a Control Group. + This is internal to the code:"controller" program and is not customizable via any Rule file. + For a customizable code:"freeze"-like capability, look into the Pause and Resume Actions. + This is the complement of the Thaw Action. + + This designates that a processes Control Group is to be frozen. + All Rules (or any process not controlled by the code:"controller") that is within the same Control Group will be frozen. + (@todo consider instead designing this around the Control Groups instead of a code:"rule".) + (This documentation will likely change with consideration to the above @todo once this gets implemented.) + + This must not attempt to freeze (or unfreeze) the Control Group that the code:"controller" belongs to. + Therefore, if a Rule does not specify a Control Group, then it is likely that the Freeze Action will be unsupported for that Rule/Control Group. + + - Kill Action\: + Forcefully terminate some process controlled by the code:"controller". + This action cannot be blocked and it is recommended to use a Stop Action instead for a more proper termination. + + - Pause Action\: + The Pause Action will pause (or freeze) the process controlled by the Rule. + Although similar to the Freeze Action, this is intended to communicate to an individual process and inform to Pause. + This is complemented by the Resume Action. + + - Restart Action\: + The Restart Action will either perform a Stop Action and then a Restart Action or it will perform the Restart Action designated in some Rule file. + Ideally this should inform some process to perform its own restart routines. + + - Resume Action\: + The Resume Action will unpause (or unfreeze) the process controlled by the Rule. + Although similar to the Thaw Action, this is intended to communicate to an individual process and inform to Resume. + This is complemented by the Pause Action. + + - Reload Action\: + The Reload Action will perform the Reload Action designated in some Rule file. + Ideally this should inform some process to perform its own reload routines. + Many programs often differentiate the concept code:"reload" from the concept "restart" in that the program remains running during a code:"reload". + + - Start Action\: + The Start Action will perform the Start Action designated in some Rule file. + This action should be used to start some program or script. + This is the action called by Entry file. + This is complemented by the Stop Action. + + - Stop Action\: + The Stop Action will perform the Stop Action designated in some Rule file. + This action should be used to stop some program or script. + This is the action called for all running controlled processes on shutdown. + This is complemented by the Start Action. + + - Thaw Action\: + The Thaw Action is an extension of a Control Group. + This is internal to the code:"controller" program and is not customizable via any Rule file. + For a customizable code:"thaw"-like capability, look into the code:"pause" and code:"resume" Actions. + This is complemented by the Freeze Action. + + This designates that a processes Control Group is to be unfrozen. + All Rules (or any process not controlled by the code:"controller") that is within the same Control Group will be unfrozen. + (@todo consider instead designing this around the Control Groups instead of a code:"rule".) + (This documentation will likely change with consideration to the above @todo once this gets implemented.) + + This must not attempt to thaw (or unthaw) the Control Group that the code:"controller" belongs to. + Therefore, if a Rule does not specify a Control Group, then it is likely that the Thaw Action will be unsupported for that Rule/Control Group. diff --git a/documents/standards/controller/documents/entry.txt b/documents/standards/controller/documents/entry.txt new file mode 100644 index 0000000..891a134 --- /dev/null +++ b/documents/standards/controller/documents/entry.txt @@ -0,0 +1,224 @@ +# fss-0002 iki-0000 +# +# license: open-standard-license-1.0 +# +# This file (assumed to be named entry.txt) can be more easily read using the following iki_read commands: +# iki_read entry.txt +Q -r PID PID -w -WW code '"' '"' +# +# To read the "Entry Documentation" section of this file, use this command sequence: +# fss_basic_list_read entry.txt +Q -cn "Entry Documentation" | iki_read +Q -r PID PID -w -W code '"' '"' +# + +Entry Documentation: + This describes the intent and purpose of an Entry file. + + An Entry file, such as code:"default.entry", is intended to store a set of rules in which the controller will process on execution. + These are used to run some set of commands, such as booting a system. + + The code:"main" Item Object is always executed first (Therefore code:"main" is both reserved and required). + All other Basic List Objects are not executed unless either an code:"item" or a code:"failsafe" specifies a valid Item name. + Execution of all Items is top-down. + + - The code:"settings" item Object\: + Represents Entry settings and is not an code:"item" that can be executed. + A number of settings are supported, but if this Item Object is not specified, then defaults are used. + The following settings are available: code:"control", code:"control_group", code:"control_mode", code:"control_user", code:"define", code:"mode", code:"parameter", code:"pid", code:"pid_file", code:"session", code:"show". + + - The code:"control" setting\: + Represents the path to the socket file in which the Controller uses to communicate over with clients such as a Control program. + A relative path is relative to the Controller PID:"Process Identifier" directory. + An absolute path is treated exactly as the path given. + If no socket setting is specified, then no socket will be made available. + This socket file is only created once code:"ready" mode is achieved. + + Providing code:"readonly" after the socket path instructs the Controller program not to create or delete the Socket file because the file system is assumed to be readonly. + The socket file itself must therefore already exist. + This should be possible in the cases of file systems that have pre-created a socket file at the designated path. + When code:"readonly", the group, mode, and user are also not processed effectively resulting in the code:"control_group", code:"control_mode", and code:"control_user" settings being ignored. + + Future versions might expand this into supporting network addresses in addition to socket files. + + - The code:"control_group" setting\: + Represents the group name or group ID to assign to the socket file as the group. + + - The code:"control_mode" setting\: + Represents the file mode assigned to the socket file. + This could either be the string version that might look like code:"u+rw-x,g+r-wx,o-rwx" or a numeric value like code:"0750". + + - The code:"control_user" setting\: + Represents the user name or user ID to assign to the socket file as the owner. + + - The code:"define" setting\: + Use this to define an environment variable (this overwrites any existing environment variable with this name). + A define is both exported as an environment variable as well as exposed as an IKI variable. + Example IKI variable substitution: for code:"define PATH /bin:/sbin", the associated IKI variable would look like: define:"PATH". + + All environment variables, including those defined using this, must be in the code:"environment" list in any given Rule to be exported to the executed process. + Environment variables added here that are not added to the environment are still exposed as an IKI variable. + + This is only expanded within any Rule operated on by this Entry. + + - The code:"mode" setting\: + Represents the mode in which the Entry is operating in. + The following modes are supported: code:"program" and code:"service". + + - The code:"program" mode\: + Designates that the Entry operates as a program and exits when complete. + Will call the code:"exit" with the same name as this Entry, but with the extension code:"exit", such as code:"default.exit". + Supports the Item Action code:"execute" to execute a program (switching the code:"controller" program entirely with the executed process). + + - The code:"service" mode\: + Designates that the Entry operates as a service and will sit and wait for control commands when complete. + Will call the code:"exit" with the same name as this Entry, but with the extension code:"exit", such as code:"default.exit". + Does not support the Item Action code:"execute". + This is the default mode. + + - The code:"parameter" setting\: + Use this to define an IKI variable name and value. + These do not conflict with environment variables and are not exposed as environment variables. + Example IKI variable substitution: for code:"parameter hello world", the associated IKI variable would look like: parameter:"hello". + + This is only expanded within any Rule operated on by this Entry. + + - The code:"pid" setting\: + Represents how the Entry PID:"Process Identifier" file is generated or not. + The following modes are supported: code:"disable", code:"require", and code:"ready". + For code:"disable", not PID:"Process Identifier" file representing the Entry is created. + For code:"require", check to see if the PID:"Process Identifier" file exists for an Entry at startup and then when code:"ready" create a PID:"Process Identifier" file, display error on PID:"Process Identifier" file already exists or on failure and then fail. + For code:"ready", when code:"ready" create a PID:"Process Identifier" file, display error on failure and then fail (does not check if PID:"Process Identifier" file exists). + + - The code:"pid_file" setting\: + When code:"pid" is not disabled this represents the path to the PID:"Process Identifier" file. + If code:"-p" or code:"--pid" is passed to the controller program, then this value is ignored in favor of the value passed along the command line. + + - The code:"session" setting\: + Represents the default way in which child processes are executed. + This default can be overridden by individual Rules. + For code:"new", Execute Rule processes in a new session setting the process group to the executed process' id (making the executed process a code:"controlling terminal"). + For code:"same", Execute Rule processes in the same session where the process group is set to the parent process id. + + - The code:"show" setting\: + Represents the way Entry processing presents information to the screen. + This applies only to the Entry and Rule processing itself and does not handle the output of programs and scripts being executed by some Entry or Rule. + The following show options are supported: code:"normal" and code:"init". + For code:"normal", will not report the start or stop of some Entry or Rule execution but will report any errors or warnings as appropriate. + For code:"init", will report when starting programs and may include reporting success and failure status. + + - The code:"timeout" setting\: + Represents the default timeouts for the Entry. + See the code:"timeout" Action below for details. + + - The code:"main" item Object\: + Each code:"item" supports the following Action Names: code:"consider", code:"execute", code:"failsafe", code:"freeze", code:"item", code:"kill", code:"pause", code:"reload", code:"restart", code:"ready", code:"resume", code:"start", code:"stop", and code:"timeout". + Of those types, the following are considered a code:"rule" Action: code:"freeze", code:"kill", code:"pause", code:"reload", code:"restart", code:"resume", code:"start", code:"stop", and code:"thaw". + + - The code:"consider" Item Action\: + A special case of a code:"rule" Action. + All Action Parameters are the same as with the code:"rule" Action Parameters. + The difference is that code:"consider" is only processed (instead of being processed and executed) and when some code:"rule" Action designates that this consideration is required (via code:"need"), wanted (via code:"want"), or wished for (via code:"wish") from the within the Rule file. + If this is determined to be executed, then this is immediately executed when needed, wanted or wished for and applies all properties as appropriate (such as code:"asynchronous", for example). + If this is determined not to be executed, then this code:"consider" is ignored as if it was never there in the first place. + + - The code:"execute" Item Action\: + Execute into the specified program. + On successful execution, the controller program will no longer be running and will be replaced with the designated program. + This Item Action is only supported when operating in code:"program" mode. + + - The code:"failsafe" Item Action\: + Accepts only a valid Item Name in which will be executed when a failure is detected. + Only a single code:"failsafe" Item Action may function at a time. + Each successive code:"failsafe" Item Action specified replaces the previously defined code:"failsafe" Item Action (in a top-down manner). + When operating in code:"failsafe", the code:"require" Item Action is ignored (given that it is meaningless once operating in code:"failsafe" mode). + + - The code:"freeze" Item Action\: + A code:"rule" Action for freezing some Control Group. + This Item Action will process the code:"freeze" inner Content of the named Rule. + This is specific to Control Groups and is not yet fully implemented. + Once implemented this documentation will need to be updated and clarified. + + - The code:"item" Item Action\: + Accepts only a valid Item Name in which will be immediately executed. + Any valid Item Name, except for the reserved code:"main", may be used. + + - The code:"kill" Item Action\: + A code:"rule" Action for forcibly terminating some process. + This Item Action will process the code:"kill" inner Content of the named Rule. + + - The code:"pause" Item Action\: + A code:"rule" Action for pausing some process. + This Item Action will process the code:"pause" inner Content of the named Rule. + + - The code:"reload" Item Action\: + A code:"rule" Action for pausing some process. + This Item Action will process the code:"reload" inner Content of the named Rule. + + - The code:"restart" Item Action\: + A code:"rule" Action for pausing some process. + This Item Action will process the code:"restart" inner Content of the named Rule. + + - The code:"resume" Item Action\: + A code:"rule" Action for pausing some process. + This Item Action will process the code:"resume" inner Content of the named Rule. + + - The code:"ready" Item Action\: + Instructs the controller program when it is safe to perform normal tasks, such as creating the PID:"Process Identifier" file. + When not specified, the state is always assumed to be ready. + For example, the controller program may be used as a full blown code:"init" replacement and therefore may need to mount the /var/run/ directory. + If the PID:"Process Identifier" file is created at program start, then the /var/run/controller.pid would be written before the /var/run/ directory is ready. + This could be a problem, such as on a read-only file system the PID:"Process Identifier" creation fails and controller bails out on error. + Adding code:"ready" essentially specifies a point in time in the Entry in which things are expected to be safe for such basic operations. + When the optional code:"wait" is provided, then code:"ready" will wait for all currently started asynchronous processes to complete before operating. + + - The code:"start" Item Action\: + A code:"rule" Action for pausing some process. + This Item Action will process the code:"start" inner Content of the named Rule. + + - The code:"stop" Item Action\: + A code:"rule" Action for pausing some process. + This Item Action will process the code:"stop" inner Content of the named Rule. + + - The code:"thaw" Item Action\: + A code:"rule" Action for unfreezing some Control Group. + This Item Action will process the code:"thaw" inner Content of the named Rule. + This is specific to Control Groups and is not yet fully implemented. + Once implemented this documentation will need to be updated and clarified. + + - The code:"timeout" Item Action\: + (This is not currently fully implemented, only code:"exit" is implemented.) + Provides default global settings for each of the four special situations: code:"exit", code:"kill", code:"start", and code:"stop". + Each of these may only have a single one exist at a time (one code:"exit", one code:"kill", one code:"start", and one code:"stop"). + Each successive code:"timeout" Item Action, specific to each Action Name (such as code:"start"), specified replaces the previously defined code:"timeout" Action (in a top-down manner). + The second Content for each of these, when specified, may be a 0 or greater whole number representing the number of MegaTime (MT) (equivalent to milliseconds). + For code:"kill", this represents the number of MegaTime to wait after stopping some Rule and that Rule has not yet stopped to forcefully stop the Rule (aka kill the Rule). + For code:"start", this represents the number of MegaTime to wait after starting some Rule before assuming something went wrong and the Rule is returned as failed. + For code:"stop", this represents the number of MegaTime to wait after stopping some Rule before assuming something went wrong and the Rule is returned as failed. + If the second Content is not specified, then this disables the type (prevents the specified timeout action). + For code:"exit", this represents the number of MegaTime to wait when the Controller program is exiting (such as having received a terminate signal). + In this case, a terminate signal is sent to all child processes. + The code:"exit" timeout represents the amount of time to wait after sending the terminate signal before sending a kill signal to each child process still running. + When disabled, the program will not send a kill signal will continue running until all child processes to terminate. + The code:"exit" timeout does not get applied to any Rule. + +Entry Rule Documentation: + There are multiple Entry Actions that are considered code:"rule" Actions. + These are: code:"freeze", code:"kill", code:"pause", code:"reload", code:"restart", code:"resume", code:"start", code:"stop", and code:"thaw". + + The code:"rule" Actions immediately execute a named Rule file. + - The first Action Parameter represents the Rule directory, which is a relative directory path the Rule file is to be found. + - Do not include leading or trailing slashes. + - This is relative to the settings rules directory. + + - The second Action Parameter represents the base name for the Rule file, without the file extension. + - This must not have any directory paths. + + - The remaining Action Parameters may be specified in any order\: + - code:"asynchronous": Designates that execution will not block (wait). + - code:"require": Designates that this Rule must succeed or trigger execution of failsafe. + - code:"wait": Designates that this Rule will not execute until all other Actions before this (including code:"asynchronous" ones) finish executing (in a top-down manner). + + The full path to the code:"rule" is relative to the settings, such that if the controller Rule settings are found in code:"/etc/controller/rules/", then for a directory called code:"[directory]" and a Rule base name of code:"[base_name]", the resulting path would be: code:"/etc/controller/rules/[directory]/[base_name].rule". + + It is important to note that for any given code:"rule", execution within that code:"rule" may be internally asynchronous (even if the code:"rule" is synchronous). + For example, a service that is often called a daemon will execute in the background. + Until that execution succeeds and the daemon goes into the background the representing Rule will block. + After the daemon goes into the background, then the representing Rule will no longer block and be fully executed. diff --git a/documents/standards/controller/documents/exit.txt b/documents/standards/controller/documents/exit.txt new file mode 100644 index 0000000..bfa4372 --- /dev/null +++ b/documents/standards/controller/documents/exit.txt @@ -0,0 +1,178 @@ +# fss-0002 iki-0000 +# +# license: open-standard-license-1.0 +# +# This file (assumed to be named exit.txt) can be more easily read using the following iki_read commands: +# iki_read exit.txt +Q -w -r PID PID -w -W code '"' '"' +# +# To read the "Exit Documentation" section of this file, use this command sequence: +# fss_basic_list_read exit.txt +Q -cn "Exit Documentation" | iki_read +Q -r PID PID -w -W code '"' '"' +# + +Exit Documentation: + This describes the intent and purpose of an Exit file. + + An Exit file, such as code:"default.exit", is intended to store a set of rules in which the controller will process on execution. + These are used to run some set of commands, such as shutting down a system. + + An Exit is a special variation or subset of an Entry. + + - The code:"settings" Item Object\: + Represents Exit settings and is not an code:"item" that can be executed. + A number of settings are supported, but if this Item Object is not specified, then defaults are used. + The following settings are available: code:"pid" and code:"show". + + - The code:"define" setting\: + Use this to define an environment variable (this overwrites any existing environment variable with this name). + A define is both exported as an environment variable as well as exposed as an IKI variable. + Example IKI variable substitution: for code:"define PATH /bin:/sbin", the associated IKI variable would look like: define:"PATH". + + All environment variables, including those defined using this, must be in the code:"environment" list in any given Rule to be exported to the executed process. + Environment variables added here that are not added to the environment are still exposed as an IKI variable. + + This is only expanded within any Rule operated on by this Exit. + + - The code:"parameter" setting\: + Use this to define an IKI variable name and value. + These do not conflict with environment variables and are not exposed as environment variables. + Example IKI variable substitution: for code:"parameter hello world", the associated IKI variable would look like: parameter:"hello". + + This is only expanded within any Rule operated on by this Exit. + + - The code:"pid" setting\: + Represents how the Exit PID:"Process Identifier" file is generated or not. + The following modes are supported: code:"disable", code:"require", and code:"ready". + For code:"disable", not PID:"Process Identifier" file representing the Exit is created. + For code:"require", check to see if the PID:"Process Identifier" file exists for an Exit at startup and then when code:"ready" create a PID:"Process Identifier" file, display error on PID:"Process Identifier" file already exists or on failure and then fail. + For code:"ready", when code:"ready" create a PID:"Process Identifier" file, display error on failure and then fail (does not check if PID:"Process Identifier" file exists). + + - The code:"show" setting\: + Represents the way Exit processing presents information to the screen. + This applies only to the Exit and Rule processing itself and does not handle the output of programs and scripts being executed by some Exit or Rule. + The following show options are supported: code:"normal" and code:"init". + For code:"normal", will not report the start or stop of some Exit or Rule execution but will report any errors or warnings as appropriate. + For code:"init", will report when starting programs and may include reporting success and failure status. + + - The code:"timeout" setting\: + Represents the default timeouts for the Exit. + See the code:"timeout" Action below for details. + + - The code:"main" Item Object\: + Is always executed first (Therefore code:"main" is both reserved and required). + All other Basic List Objects are not executed unless either an code:"item" or a code:"failsafe" specifies a valid Item name. + Execution of all Items are top-down. + + Each code:"item" supports the following Action Names: code:"consider", code:"execute", code:"failsafe", code:"freeze", code:"item", code:"kill", code:"pause", code:"reload", code:"restart", code:"ready", code:"resume", code:"start", code:"stop", and code:"timeout". + Of those types, the following are considered a code:"rule" Action: code:"freeze", code:"kill", code:"pause", code:"reload", code:"restart", code:"resume", code:"start", code:"stop", and code:"thaw". + + - The code:"consider" Item Action\: + A special case of a code:"rule" Action. + All Action Parameters are the same as with the code:"rule" Action Parameters. + The difference is that code:"consider" is only processed (instead of being processed and executed) and when some code:"rule" Action designates that this consideration is required (via code:"need"), wanted (via code:"want"), or wished for (via code:"wish") from the within the Rule file. + If this is determined to be executed, then this is immediately executed when needed, wanted or wished for and applies all properties as appropriate (such as code:"asynchronous", for example). + If this is determined not to be executed, then this code:"consider" is ignored as if it was never there in the first place. + + - The code:"execute" Item Action\: + Execute into the specified program. + On successful execution, the controller program will no longer be running and will be replaced with the designated program. + This Item Action is only supported when operating in code:"program" mode. + + - The code:"failsafe" Item Action\: + Accepts only a valid Item Name in which will be executed when a failure is detected. + Only a single code:"failsafe" Item Action may function at a time. + Each successive code:"failsafe" Item Action specified replaces the previously defined code:"failsafe" Item Action (in a top-down manner). + When operating in code:"failsafe", the code:"require" Item Action is ignored (given that it is meaningless once operating in code:"failsafe" mode). + + - The code:"freeze" Item Action\: + A code:"rule" Action for freezing some Control Group. + This Item Action will process the code:"freeze" inner Content of the named Rule. + This is specific to Control Groups and is not yet fully implemented. + Once implemented this documentation will need to be updated and clarified. + + - The code:"item" Item Action\: + Accepts only a valid Item Name in which will be immediately executed. + Any valid Item Name, except for the reserved code:"main", may be used. + + - The code:"kill" Item Action\: + A code:"rule" Action for forcibly terminating some process. + This Item Action will process the code:"kill" inner Content of the named Rule. + + - The code:"pause" Item Action\: + A code:"rule" Action for pausing some process. + This Item Action will process the code:"pause" inner Content of the named Rule. + + - The code:"reload" Item Action\: + A code:"rule" Action for pausing some process. + This Item Action will process the code:"reload" inner Content of the named Rule. + + - The code:"restart" Item Action\: + A code:"rule" Action for pausing some process. + This Item Action will process the code:"restart" inner Content of the named Rule. + + - The code:"resume" Item Action\: + A code:"rule" Action for pausing some process. + This Item Action will process the code:"resume" inner Content of the named Rule. + + - The code:"ready" Action\: + Instructs the controller program when it is safe to perform normal tasks, such as creating the PID:"Process Identifier" file. + When not specified, the state is always assumed to be ready. + For example, the controller program may be used as a full blown code:"init" replacement and therefore may need to mount the /var/run/ directory. + If the PID:"Process Identifier" file is created at program start, then the /var/run/controller.pid would be written before the /var/run/ directory is ready. + This could be a problem, such as on a read-only file system the PID:"Process Identifier" creation fails and controller bails out on error. + Adding code:"ready" essentially specifies a point in time in the Exit in which things are expected to be safe for such basic operations. + When the optional code:"wait" is provided, then code:"ready" will wait for all currently started asynchronous processes to complete before operating. + + - The code:"start" Item Action\: + A code:"rule" Action for pausing some process. + This Item Action will process the code:"start" inner Content of the named Rule. + + - The code:"stop" Item Action\: + A code:"rule" Action for pausing some process. + This Item Action will process the code:"stop" inner Content of the named Rule. + + - The code:"thaw" Item Action\: + A code:"rule" Action for unfreezing some Control Group. + This Item Action will process the code:"thaw" inner Content of the named Rule. + This is specific to Control Groups and is not yet fully implemented. + Once implemented this documentation will need to be updated and clarified. + + - The code:"timeout" Item Action\: + (This is not currently fully implemented, only code:"exit" is implemented.) + Provides default global settings for each of the four special situations: code:"exit", code:"kill", code:"start", and code:"stop". + Each of these may only have a single one exist at a time (one code:"exit", one code:"kill", one code:"start", and one code:"stop"). + Each successive code:"timeout" Item Action, specific to each Action Name (such as code:"start"), specified replaces the previously defined code:"timeout" Action (in a top-down manner). + The second Content for each of these, when specified, may be a 0 or greater whole number representing the number of MegaTime (MT) (equivalent to milliseconds). + For code:"kill", this represents the number of MegaTime to wait after stopping some Rule and that Rule has not yet stopped to forcefully stop the Rule (aka kill the Rule). + For code:"start", this represents the number of MegaTime to wait after starting some Rule before assuming something went wrong and the Rule is returned as failed. + For code:"stop", this represents the number of MegaTime to wait after stopping some Rule before assuming something went wrong and the Rule is returned as failed. + If the second Content is not specified, then this disables the type (prevents the specified timeout action). + + For code:"exit", this represents the number of MegaTime to wait when the Controller program is exiting (such as having received a terminate signal). + In this case, a terminate signal is sent to all child processes. + The code:"exit" timeout represents the amount of time to wait after sending the terminate signal before sending a kill signal to each child process still running. + When disabled, the program will not send a kill signal will continue running until all child processes to terminate. + The code:"exit" timeout does not get applied to any Rule. + +Exit Rule Documentation: + There are multiple Exit Actions that are considered code:"rule" Actions. + These are: code:"freeze", code:"kill", code:"pause", code:"reload", code:"restart", code:"resume", code:"start", code:"stop", and code:"thaw". + + The code:"rule" Actions immediately execute a named Rule file. + - The first Action Parameter represents the Rule directory, which is a relative directory path the Rule file is to be found. + - Do not include leading or trailing slashes. + - This is relative to the settings rules directory. + + - The second Action Parameter represents the base name for the Rule file, without the file extension. + - This must not have any directory paths. + + - The remaining Action Parameters may be specified in any order\: + - code:"asynchronous": Designates that execution will not block (wait). + - code:"require": Designates that this Rule must succeed or trigger execution of failsafe. + - code:"wait": Designates that this Rule will not execute until all other Actions before this (including code:"asynchronous" ones) finish executing (in a top-down manner). + + The full path to the code:"rule" is relative to the settings, such that if the controller Rule settings are found in code:"/etc/controller/rules/", then for a directory called code:"[directory]" and a Rule base name of code:"[base_name]", the resulting path would be: code:"/etc/controller/rules/[directory]/[base_name].rule" + + It is important to note that for any given code:"rule", execution within that code:"rule" may be internally asynchronous (even if the code:"rule" is synchronous). + For example, a service that is often called a daemon will execute in the background. + Until that execution succeeds and the daemon goes into the background the representing Rule will block. + After the daemon goes into the background, then the representing Rule will no longer block and be fully executed. diff --git a/documents/standards/controller/documents/packet.txt b/documents/standards/controller/documents/packet.txt new file mode 100644 index 0000000..3a0038d --- /dev/null +++ b/documents/standards/controller/documents/packet.txt @@ -0,0 +1,81 @@ +# fss-0002 iki-0000 +# +# license: open-standard-license-1.0 +# +# This file (assumed to be named packet.txt) can be more easily read using the following iki_read commands: +# iki_read packet.txt +Q -w -W code '"' '"' +# +# To read the "Packet Documentation" section of this file, use this command sequence: +# fss_basic_list_read packet.txt +Q -cn "Packet Documentation" | iki_read +Q -w -W code '"' '"' +# + +Packet Documentation: + Describes how a packet is designed and intended to be used. + + The code:"packet" is the general category in which multiple types of packets belong. + This describes the different packets based on their code:"type". + + Each packet begins with a control block and a size block followed by a payload block. + + The control block\: + The leading bit (starting from the left) designates the the format of the payload, which is 0 for string and 1 for binary. + The second bit (starting from the left) designates the the byte order for the rest of the packet, which 0 is for little endian and 1 is for big endian. + The remaining 6-bits are reserved for future use. + + The size block\: + The size block represents the size of the entire packet (the control block, the size blocks, and the payload block). + This number is a single 32-bit unsigned integer. + + Example packet structure\: + block:" + [ Control Block ] [ Size Block ] [ Payload Block ] + [ 0b10000000 ] [ 0b00000000 0b00000000 0b00000100 0b11010010 ] [ size: 1229 (1234 - 5) ] + " + + The payload block\: + This block is represented by the code:"FSS-000E (Payload)" specification and its structure ad use is described in the next sections. + + The following types of payload are received or sent\: + 1) controller payload. + 2) error payload. + 3) init payload. + + The controller payload\: + Commands being sent to the controller and their respective responses utilize a code:"controller" payload. + These are pre-defined commands to rules or the controller program itself. + Commands such as starting or stopping some rule, for example. + A controller payload is also sent in response to a controller payload request to represent a success. + + The code:"now" condition designates that the kexec, reboot, or shutdown is to begin immediately. + The code:"at" condition designates that the kexec, reboot, or shutdown is to begin once a specific date and time is reached by the system clock. + The code:"in" condition designates that the kexec, reboot, or shutdown is to begin once a specific amount of time is passed by the system clock since the execution of this command started. + + For these code:"time" conditions, different units of time should be supported, such as code:"seconds", code:"days", code:"years" as standard time, Time, or UNIX Time (Epoch Time). + + The normal code:"controller" payload commands are any valid Rule Action that performs some action. + This does not include Actions that provide some setting or configuration (such as code:"with_pid"). + Some of the supported commands are: code:"freeze", code:"kill", code:"pause", code:"reload", code:"rerun", code:"restart", code:"resume", code:"start", code:"stop", or code:"thaw". + Multiple commands may be sent multiple code:"action" headers. + The code:"action" headers are order sensitive, executing from top to bottom, and one does not start until the previous successfully completes. + + Multiple code:"status" headers may exist in the response so long as they each match an code:"action" in the request. + + The code:"payload" is expected to be empty and have a length of 0 for a request. + The code:"payload" may have an code:"FSS-0000 (Basic)" format containing a single Object code:"message" to represent a message associated with an action. + Multiple code:"message" may exist in the response so long as they each match an code:"action" in the request. + + The error payload\: + The error payload is intended to communicate some sort of failure. + The error payload is only sent in response to some request (and not in response to another response). + The control (the client) is not expected to send error payloads and the controller (the service) should send an error in response to an error payload or ignore it entirely. + The code:"status" from the code:"header" designates the status code as either a status code name string or a status code number (where a number may have error and warning bits). + The code:"payload" will contain a NULL terminated string representing the message used to describe the error. + + The init payload\: + The init payload is intended exclusively for the code:"init" operation mode and is expected to only be available when running as code:"init". + This is used to provide special actions, namely code:"kexec", code:"reboot", and code:"shutdown". + + The code:"kexec" is for booting into another kernel, which may effectively be the same as a code:"reboot" ("kexec" is currently neither supported nor implemented). + The code:"reboot" is for rebooting the machine (currently not implemented). + The code:"shutdown" is for shutting down the machine (currently not implemented). + These three commands are configurable to fire off based on conditions. diff --git a/documents/standards/controller/documents/rule.txt b/documents/standards/controller/documents/rule.txt new file mode 100644 index 0000000..8d9e1c5 --- /dev/null +++ b/documents/standards/controller/documents/rule.txt @@ -0,0 +1,238 @@ +# fss-0002 iki-0000 +# +# license: open-standard-license-1.0 +# +# This file (assumed to be named rule.txt) can be more easily read using the following iki_read commands: +# iki_read rule.txt +Q -r PID PID -w -W code '"' '"' +# +# To read the "Rule Documentation" section of this file, use this command sequence: +# fss_basic_list_read rule.txt +Q -cn "Rule Documentation" | iki_read +Q -r PID PID -w -W code '"' '"' +# + +Rule Documentation: + This describes the intent and purpose of a Rule file. + + A Rule file, such as code:"ssh.rule", is intended to designate what to execute. + + The rule file is read top-down, except for the outer most list code:"settings", which is intended to store setting data for this rule. + Multiple outer most list Objects may be specified and they are executed as provided, in a top-down manner. + + - The code:"settings" Rule Type has the following code:"FSS-0001 (Extended)" Content\: + - code:"affinity": Define one or more processors to restrict this rule by with each number representing a specific processor by its id (starting at 0). + - code:"capability": Define a set of capabilities in which to use, using the capability code:"text" format (such as code:"= cap_chown+ep"). + - code:"cgroup": Define a cgroup (control group) in which everything within this rule executes under. + - code:"define": A single environment variable name and its associated value that is automatically exposed to processes executed within this rule. + - code:"engine": An executable name of a script, such as code:"bash", to use for the code:"script" Rule Type (which likely defaults to code:"bash" if not specified). + - code:"environment": A set of environment variables to expose to the processes executed within this rule (PATH is always exposed). + - code:"group": A set of group names or IDs to execute as with the first group being the primary group and all remaining being supplementary groups. + - code:"limit": Define a resource limit to use (multiple limits may be specified, but only once for each type). + - code:"name": A name used to represent this rule, which is printed to the user, screen, logs, etc... + - code:"nice": A single niceness value to run all processes executed within this rule as (-20 gets to be greediest in CPU usage and 19 being the nicest in CPU usage). + - code:"on": Define a Rule Action in which a specified dependency is needed, wanted, or wished for. + - code:"parameter": An IKI name and its associated value for use in this rule file. + - code:"path": A single Content used to set a custom PATH environment variable value. + - code:"scheduler": A valid name of a scheduler to use followed by an optional priority number. + - code:"timeout": A set of timeouts to wait for in which to perform a set action or to consider failure. + - code:"user": A single user name or ID to execute as. + + - The code:"capability" setting\: + If the user the controller program is run as does not have the desired capabilities already, they cannot be added. + This essentially maintains or reduces the capabilities already available. + Due to capabilities only being a draft in the POSIX standard, one may expect code:"capabilities" support may not be available and in such a case this setting will do nothing. + If the dependent project (f_capability) does not have libcap support enabled, then capabilities will be unsupported by the compilation of this project. + + - The code:"control" setting\: + The first argument is either code:"existing" or code:"new", where for code:"existing" the process is run inside the existing control used by the parent and when code:"new" the process is executed within a new control group namespace entirely. + + - The code:"define" setting\: + Use this to define an environment variable (this overwrites any existing environment variable with this name). + A define is both exported as an environment variable as well as exposed as an IKI variable. + Example IKI variable substitution: for code:"define PATH /bin:/sbin", the associated IKI variable would look like: define:"PATH". + + All environment variables, including those defined using this, must be in the code:"environment" list to be exported to the executed process. + Environment variables added here that are not added to the environment are still exposed as an IKI variable. + + - The code:"engine" setting\: + This engine is used for both code:"script" and code:"utility" Rule Types. + The program that engine refers to must accept a standard input pipe to be supported. + Additional parameters may be passed to the engine. + + - The code:"group" and code:"user" settings\: + Only users and groups that the user the controller program is being run as is allowed to use may be used. + + - The code:"limit" setting\: + The first parameter must be one of: code:"as", code:"core", code:"cpu", code:"data", code:"fsize", code:"locks", code:"memlock", code:"msgqueue", code:"nice", code:"nofile", code:"nproc", code:"rss", code:"rtprio", code:"rttime", code:"sigpending", or code:"stack". + The second parameter represents the soft limit. + The third parameter represents the hard limit. + This may be specified multiply times, but only once for each type. + + - The code:"on" setting\: + The first parameter represents the Action the dependency exists under and must be one of: code:"freeze", code:"kill", code:"pause", code:"reload", code:"restart", code:"resume", code:"start", code:"stop", or code:"thaw". + The second parameter represents how the dependency is required and must be one of: code:"need", code:"want", or code:"wish". + The third parameter is a partial path to the rule file. + The fourth parameter represents the name of the rule file. + + - In the case of the second parameter\: + - A code:"need" designates that the dependent rule is required to be executed (must exist and must succeed). + - A code:"want" designates that the dependent rule is to be executed (may exist and if it does, then it must succeed). + - A code:"wish" designates that the dependent rule is to be executed (may exist and if it does, but it does not need to succeed). + + In the case of code:"want" and code:"wish", if the desired rule is either not found or is otherwise disabled, then this will not fail or otherwise block the wanting or wishing rule. + + - The code:"path" setting\: + When specified, the code:"PATH" environment variable is automatically added to the code:"environment" setting. + + - The code:"parameter" setting\: + Use this to define an IKI variable name and value. + These do not conflict with environment variables and are not exposed as environment variables. + Example IKI variable substitution: for code:"parameter hello world", the associated IKI variable would look like: parameter:"hello". + + - The code:"scheduler" setting\: + The valid range of the priority number is dependent on the scheduler. + For example, non-real-time schedulers (such as code:"idle") only support a value of 0 whereas real-time schedulers (such as code:"fifo") only support an inclusive range of 1 to 99. + Supported non-real-time schedulers are: code:"batch", code:"idle", and code:"other" (aka: normal/default). + Supported real-time schedulers are: code:"deadline", code:"fifo", code:"round_robin". + + - The code:"timeout" setting\: + (This is not currently implemented.) + Provides settings for each of the three special situations: code:"kill", code:"start", and code:"stop". + Each of these may only have a single one exist at a time (one code:"kill", one code:"start", and one code:"stop"). + Each successive code:"timeout" Item Action, specific to each Action Name (such as code:"start"), specified replaces the previously defined code:"timeout" Action (in a top-down manner). + The second Content for each of these, when specified, may be a 0 or greater whole number representing the number of MegaTime (MT) (equivalent to milliseconds). + For code:"kill", this represents the number of MegaTime to wait after stopping some Rule and that Rule has not yet stopped to forcefully stop the Rule (aka kill the Rule). + For code:"start", this represents the number of MegaTime to wait after starting some Rule before assuming something went wrong and the Rule is returned as failed. + For code:"stop", this represents the number of MegaTime to wait after stopping some Rule before assuming something went wrong and the Rule is returned as failed. + If the second Content is not specified, then this disables the type (prevents the specified timeout action). + + There are four available Rule Types to choose from: code:"command", code:"service", code:"script", and code:"utility". + + The code:"command" Rule Type provides a simple command to run under the different circumstances: code:"start", code:"stop", code:"restart", and code:"reload". + A code:"command" always operates in the foreground. + + The code:"service" Rule Type provides a code:"command" accompanied with a PID:"Process Identifier" file (Process Identifier file). + + The code:"script" Rule Type provides a series of lines to be executed by some engine, such as GNU Bash. + This code:"script" operates in the foreground, but individual things done within the script may operate in foreground or background. + The last return state is treated as an error, so be sure to finish the script with a return code of 0 to designate no error and any other whole number, such a 1, to designate an error. + Therefore passing code:"exit 1" would return as an error and passing code:"exit 0" would return as a success. + A code:"script" is assumed to be in GNU Bash, which is the default expected behavior, but the specification does not explicitly require this. + Another scripting language can be used but changing this incurs the responsibility to ensure all rules are updated to the appropriate scripting language. + + The code:"utility" Rule Type provides a code:"script" accompanied with a PID:"Process Identifier" file (Process Identifier file). + + There are nine Rule Actions used to execute ("freeze", code:"kill", code:"pause", code:"reload", code:"restart", code:"resume", code:"start", code:"stop", and code:"thaw")\: + When code:"restart" Object's Content is not provided, then code:"start" and code:"stop" is called when the rule is executed using the restart Action, if both code:"start" and code:"stop" are provided. + When code:"reload", code:"start", or code:"stop" Object's Content are not provided, then no respective Action is performed. + + Commands are conditionally available depending on the presence of these, such as if code:"stop" is not provided then code:"stop" (and code:"restart") will not be available for the code:"control" program(s) to use. + + Thee are additional Rule Actions not used to execute ("pid_file", code:"rerun", and code:"with")\: + - The code:"pid_file" Object's Content designates the path to the PID:"Process Identifier" file created by the called program. + + - The code:"rerun" Object's Content designates how to re-run a given execution Rule type. + - The first Content represents the execution type, which may be one of: code:"freeze", code:"kill", code:"pause", code:"reload", code:"restart", code:"resume", code:"start", code:"stop", and code:"thaw". + + - The second Content represents when to run this re-run is triggered, which is either code:"success" (return code of 0) or code:"failure" (return code is not 0). + + - The third Content and more represent additional options for fine tuning how the re-run is Performed\: + When code:"delay", followed by a number of MegaTime (MT) (equivalent to milliseconds) in which to wait before attempting the re-run. + When code:"max", followed by a positive number or the number 0 designating the maximum number of re-runs to perform. + When code:"reset", the code:"max" re-run counter is reset for the opposite re-run when this re-run is triggered, such as\: + A code:"rerun start success reset" and a code:"rerun failure max 10", the failure counter would reset to 0 when the code:"success" re-run is performed and not when the code:"failure" re-run is performed. + + A code:"max" of 0 designates that the re-run will happen infinitely. + + - The code:"with" Object's Content designates special flags designating very specific behavior to be applied to any single Rule Type. + The following flags are supported: + - code:"full_path": Used only by Rule Types that execute something, wherein the entire full path is used for execution and is assigned as argument[0] (such as code:"/bin/bash"). + When not specified, the path provided is used and the argument[0] will be the base name (such as code:"bash"). + - code:"session_new": Execute in a new session setting the process group to the executed process' id (making the executed process a code:"controlling terminal"). + - code:"session_same": Execute in the same session where the process group is set to the parent process id. + + IKI Variables\: + All Rule Actions support IKI variable substitution. + The Rule Settings do not support IKI variable substitution. + + The following IKI variable names are supported\: + - define + - parameter + - program + + The code:"define" IKI variables, such as define:"PATH", expand environment variables. + + The code:"parameter" IKI variables, such as parameter:"hello", expand IKI variables defined using the code:"parameter" Setting Rule Type. + + The code:"program" IKI variables, such as program:"verbose:option", expand program arguments (where code:"verbose:option" might expand into code:"-v" ). + + Only the following code:"program" IKI variables are supported\: + - dark\: + This variable holds the code:"dark" program parameters, such as code:"+d". + This supports code:":option". + + - light\: + This variable holds the code:"light" program parameters, such as code:"+l". + This supports code:":option". + + - no_color\: + This variable holds the code:"no_color" program parameters, such as code:"+n". + This supports code:":option". + + - quiet\: + This variable holds the code:"quiet" program parameters, such as code:"+Q". + This supports code:":option". + + - error\: + This variable holds the code:"error" program parameters, such as code:"+E". + This supports code:":option". + + - normal\: + This variable holds the code:"normal" program parameters, such as code:"+N". + This supports code:":option". + + - verbose\: + This variable holds the code:"verbose" program parameters, such as code:"+V". + This supports code:":option". + + - debug\: + This variable holds the code:"debug" program parameters, such as code:"+D". + This supports code:":option". + + - cgroup\: + This variable holds the code:"cgroup" program parameters, such as code:"-c /sys/fs/cgroup/". + This supports both code:":option" and code:":value". + + - daemon\: + This variable holds the code:"daemon" program parameters, such as code:"-d". + This supports code:":option". + + - init\: + This variable holds the code:"init" program parameters, such as code:"-I". + This supports code:":option". + + - interruptible\: + This variable holds the code:"interruptible" program parameters, such as code:"-i". + This supports code:":option". + + - pid\: + This variable holds the code:"pid" program parameters, such as code:"-p controller/run/default.pid". + This supports both code:":option" and code:":value". + + - settings\: + This variable holds the code:"settings" program parameters, such as code:"-s controller/". + This supports both code:":option" and code:":value". + + - simulate\: + This variable holds the code:"simulate" program parameters, such as code:"-S". + This supports code:":option". + + - socket\: + This variable holds the code:"socket" program parameters, such as code:"-k controller/run/default.socket". + This supports both code:":option" and code:":value". + + - uninterruptible\: + This variable holds the code:"uninterruptible" program parameters, such as code:"-U". + This supports code:":option". + + - validate\: + This variable holds the code:"validate" program parameters, such as code:"-v". + This supports code:":option". diff --git a/documents/standards/controller/documents/simulate.txt b/documents/standards/controller/documents/simulate.txt new file mode 100644 index 0000000..2dae70d --- /dev/null +++ b/documents/standards/controller/documents/simulate.txt @@ -0,0 +1,35 @@ +# fss-0002 iki-0000 +# +# license: open-standard-license-1.0 +# +# This file (assumed to be named simulate.txt) can be more easily read using the following iki_read commands: +# iki_read simulate.txt +Q -w -W code '"' '"' +# +# To read the "Simulate Documentation" section of this file, use this command sequence: +# fss_basic_list_read simulate.txt +Q -cn "Simulate Documentation" | iki_read +Q -w -W code '"' '"' +# + +Simulate Documentation: + This describes the intent and purpose of the simulation and validation parameters. + + The code:"controller" program is designed to support being run as an alternative to an init program (such as Sysvinit or SystemD). + To help prevent problems, simulation and validation functionality is provided. + + - The code:"validate" functionality\: + By itself will simply check the syntax of the Entry and Rule files (for Rule files specified in the Entry or Exit file). + Errors are reported and nothing is executed. + The code:"controller" program will return 0 on validation success and 1 on validation failure. + + - The code:"simulate" functionality\: + By itself will perform a simulated execution of all Rules designated by an Entry or Exit file. + The simulation is not a true simulation in that no program is ever called to perform any operations. + Furthermore, any code:"script" specified inside a Rule is only simulated as a whole and not its individual parts. + Once the Entry file is finished executing, the code:"simulate" will continue to run waiting on code:"control" commands. + + - The code:"simulate" with code:"validate" functionality\: + Will perform similar to code:"validate" functionality except that additional information of the Rules to be executed will be printed. + There will be neither execution nor simulated execution of any Rule when both code:"simulate" and code:"validate" are used together. + + When a Rule is simulated, an empty script command (generally defaulting to code:"bash") is executed in place of the actual program being executed for each program or script in the Rule file that is to be executed. + This allows for testing the designated permissions and other settings that would be applied when calling some program. + Control Groups are not simulated but are actually created and the simulating process will actually be placed within the Control Group. diff --git a/documents/standards/controller/documents/time.txt b/documents/standards/controller/documents/time.txt new file mode 100644 index 0000000..e7c040c --- /dev/null +++ b/documents/standards/controller/documents/time.txt @@ -0,0 +1,51 @@ +# fss-0002 iki-0000 +# +# license: cc-by-sa-4.0 +# +# This file (assumed to be named time.txt) can be more easily read using the following iki_read commands: +# iki_read time.txt +Q -r UTC UTC -w -WW character "'" "'" code '"' '"' +# +# To read the "Time Documentation" section of this file, use this command sequence: +# fss_basic_list_read time.txt +Q -cn "Time Documentation" | iki_read +Q -r UTC UTC -w -WW character "'" "'" code '"' '"' +# + +Time Documentation: + This documents a unit of measurement called a bold:"Time", represented with uppercase bold:"T". + For comparison, a unit of bold:"Time" is equivalent to a nanosecond, or 10^-9 seconds. + A bold:"MegaTime (MT)" is therefore equivalent to a millisecond such that a millisecond is 10^-3 seconds. + + A unit of bold:"Time" is intended to represent some unit of bold:"Time" such that a single 64-bit integer may hold all units of bold:"Time" for a single calendar year. + This unit of bold:"Time" does not and must not include bold:"Years" (unlike bold:"Unix time"). + To convert from bold:"Time" to bold:"Unix time", one must have a year (which could be assumed to be the current year) and then calculate all of those calendar oddities. + + A unit of bold:"Time" by default is assumed to be in UTC:"Coordinated Universal Time". + - code:"1 (Earth) year ~= 31536000000000000 Time or 31536000 GT (GigaTime)". + - code:"1 (Earth) day = 86400000000000 Time or 86400 GT (GigaTime)". + - code:"1 (Earth) hour = 3600000000000 Time or 3600 GT (GigaTime)". + - code:"1 (Earth) minute = 60000000000 Time or 60 GT (GigaTime)". + - code:"1 (Earth) second = 1000000000 Time or 1 GT (GigaTime)". + + Consequentially, 1 day is easily represented in units of bold:"Time" as code:"86.4 TT (TeraTime)". + + The Time may be stored in its "year string format". + In this format, a Year may be prepended to the Time followed by a single colon ':' to associate a year with the Time. + This Year has no minimum or maximum but may not have decimals. + For example, "2020:86400000000000" would represent: January 02, 2020 0:00 UTC. + For example, "2020:86.4 TT" would represent: January 02, 2020 0:00 UTC. + + A second unit of bold:"Time", called bold:"EpochTime", works the same way as bold:"Time" except it represents seconds. + This unit is designated code:"ET". + The format is similar to bold:"Time", except there are two colons: code:"1970::1620874738" would represent: code:"May 13, 2021 2:58:58 UTC". + When the year is not specified, then this is identical to bold:"UNIX Epoch". + + A unit of bold:"EpochTime" by default is assumed to be in UTC:"Coordinated Universal Time". + - code:"1 (Earth) year ~= 31536000 EpochTime or 31.536 GE (GigaEpochTime)". + - code:"1 (Earth) day = 86400 EpochTime". + - code:"1 (Earth) hour = 3600 EpochTime". + - code:"1 (Earth) minute = 60 EpochTime". + - code:"1 (Earth) second = 1 EpochTime". + - code:"1 GT (GigaTime) = 1 EpochTime". + + Consequentially, 1 day is easily represented in units of bold:"EpochTime" as code:"86.4 KE (KiloEpochTime)". + + See the specification file:"time.txt" for more precise technical details. diff --git a/documents/standards/controller/entry.txt b/documents/standards/controller/entry.txt deleted file mode 100644 index 00fbfdd..0000000 --- a/documents/standards/controller/entry.txt +++ /dev/null @@ -1,139 +0,0 @@ -# fss-0002 -# -# license: open-standard-license-1.0 -# - -Entry Specification: - The Entry files follow the FSS-0005 (Somewhat Basic List) format. - - An Entry file name is expected to have the file extension ".entry". - - For each Entry file\: - - The outer most part is a FSS-0002 (Basic List). - - The Basic List Object is considered the "Item". - - The Basic List Content are considered the "Actions". - - The "Actions" are FSS-0001 (Extended). - - Each Action Object is the "Action Name". - - Each Action Content are the "Action Parameters". - - The Items\: - - "main": required. - - - "settings": optional, Actions may be one of\: - - "control": One to two Content. - The first Content is a relative or absolute path to a socket file. - The second Content an optional "readonly". - - "control_group": Exactly one Content that is a group name or group id. - - "control_mode": Exactly one Content that is a valid file mode. - - "control_user": Exactly one Content that is a user name or user id. - - "define": Two Content, the first Content must be a case-sensitive valid environment variable name (alpha-numeric or underscore, but no leading digits). - - "mode": Exactly one Content that is one of "program" or "service". - - "parameter": Two Content, the first Content must be a case-sensitive valid IKI name and the second being an IKI value. - - "pid": Exactly one Content that is one of "disable", "require", or "ready". - - "pid_file": Exactly one Content that is a relative or absolute path to a pid file. - - "session": Exactly one Content that is one of "new" or "same". - - "show": Exactly one Content that is one of "normal" or "init". - - "timeout": One or two content with the first being one of "exit", "start", "stop", or "kill" and the (optional) second Content being a positive whole number or 0. - - The Entry file may have any other valid Item Objects, but only the above are reserved. - - The Actions\: - - "consider": One or more Content. - The first Content is the relative file path (without any leading/trailing slashes and without file extension). - The second Content is the basename for a rule file. - The third and beyond may only be one of\: - - "asynchronous" - - "require" - - "wait" - - - "execute": One or more Content. - The first Content is the program name or full path to the program (the program may be a script). - All remaining Content are passed as parameters to the program being executed. - - - "failsafe": One Content that is a valid Object name, except for the reserved "main". - - - "freeze": Two or more Content. - The first Content that is the relative directory path (without any leading/trailing slashes). - The second Content that is the basename for a rule file. - The third and beyond may only be one of\: - - "asynchronous" - - "require" - - "wait" - - - "item": One Content that is a valid Object name, except for the reserved "main". - - - "kill": Two or more Content. - The first Content that is the relative directory path (without any leading/trailing slashes). - The second Content that is the basename for a rule file. - The third and beyond may only be one of\: - - "asynchronous" - - "require" - - "wait" - - - "pause": Two or more Content. - The first Content that is the relative directory path (without any leading/trailing slashes). - The second Content that is the basename for a rule file. - The third and beyond may only be one of\: - - "asynchronous" - - "require" - - "wait" - - - "ready": Zero or One Content. - The first may only be one of\: - - "wait" - - - "reload": Two or more Content. - The first Content that is the relative directory path (without any leading/trailing slashes). - The second Content that is the basename for a rule file. - The third and beyond may only be one of\: - - "asynchronous" - - "require" - - "wait" - - - "restart": Two or more Content. - The first Content that is the relative directory path (without any leading/trailing slashes). - The second Content that is the basename for a rule file. - The third and beyond may only be one of\: - - "asynchronous" - - "require" - - "wait" - - - "resume": Two or more Content. - The first Content that is the relative directory path (without any leading/trailing slashes). - The second Content that is the basename for a rule file. - The third and beyond may only be one of\: - - "asynchronous" - - "require" - - "wait" - - - "start": Two or more Content. - The first Content that is the relative directory path (without any leading/trailing slashes). - The second Content that is the basename for a rule file. - The third and beyond may only be one of\: - - "asynchronous" - - "require" - - "wait" - - - "stop": Two or more Content. - The first Content that is the relative directory path (without any leading/trailing slashes). - The second Content that is the basename for a rule file. - The third and beyond may only be one of\: - - "asynchronous" - - "require" - - "wait" - - - "thaw": Two or more Content. - The first Content that is the relative directory path (without any leading/trailing slashes). - The second Content that is the basename for a rule file. - The third and beyond may only be one of\: - - "asynchronous" - - "require" - - "wait" - - - "timeout": One or two Content. - The first being one of\: - - "exit" - - "start" - - "stop" - - "kill" - The (optional) second Content being a positive whole number or 0. diff --git a/documents/standards/controller/exit.txt b/documents/standards/controller/exit.txt deleted file mode 100644 index 3fbd63f..0000000 --- a/documents/standards/controller/exit.txt +++ /dev/null @@ -1,125 +0,0 @@ -# fss-0002 -# -# license: open-standard-license-1.0 -# - -Exit Specification: - The Exit files follow the FSS-0005 (Somewhat Basic List) format. - - An Exit file name is expected to have the file extension ".exit". - - For each Exit file\: - - The outer most part is a FSS-0002 (Basic List). - - The Basic List Object is considered the "Item". - - The Basic List Content are considered the "Actions". - - The "Actions" are FSS-0001 (Extended). - - Each Action Object is the "Action Name". - - Each Action Content are the "Action Parameters". - - The Items\: - - "main": required. - - - "settings": optional, Actions may be one of\: - - "pid": Exactly one Content that is one of "disable", "require", or "ready". - - "session": Exactly one Content that is one of "new" or "same". - - "show": Exactly one Content that is one of "normal" or "init". - - "timeout": One or Two content with the first being one of "exit", "start", "stop", or "kill" and the (optional) second Content being a positive whole number or 0. - - The Exit file may have any other valid Item Objects, but only the above are reserved. - - The Actions\: - - "consider": One or more Content. - The first Content that is the relative file path (without any leading/trailing slashes and without file extension). - The second Content that is the basename for a rule file. - The third and beyond may only be one of\: - - "asynchronous" - - "require" - - "wait" - - - "failsafe": One Content that is a valid Object name, except for the reserved "main". - - - "freeze": Two or more Content. - The first Content that is the relative directory path (without any leading/trailing slashes). - The second Content that is the basename for a rule file. - The third and beyond may only be one of\: - - "asynchronous" - - "require" - - "wait" - - - "item": One Content that is a valid Object name, except for the reserved "main". - - - "kill": Two or more Content. - The first Content that is the relative directory path (without any leading/trailing slashes). - The second Content that is the basename for a rule file. - The third and beyond may only be one of\: - - "asynchronous" - - "require" - - "wait" - - - "pause": Two or more Content. - The first Content that is the relative directory path (without any leading/trailing slashes). - The second Content that is the basename for a rule file. - The third and beyond may only be one of\: - - "asynchronous" - - "require" - - "wait" - - - "ready": Zero or One Content. - The first may only be one of\: - - "wait" - - - "reload": Two or more Content. - The first Content that is the relative directory path (without any leading/trailing slashes). - The second Content that is the basename for a rule file. - The third and beyond may only be one of\: - - "asynchronous" - - "require" - - "wait" - - - "restart": Two or more Content. - The first Content that is the relative directory path (without any leading/trailing slashes). - The second Content that is the basename for a rule file. - The third and beyond may only be one of\: - - "asynchronous" - - "require" - - "wait" - - - "resume": Two or more Content. - The first Content that is the relative directory path (without any leading/trailing slashes). - The second Content that is the basename for a rule file. - The third and beyond may only be one of\: - - "asynchronous" - - "require" - - "wait" - - - "start": Two or more Content. - The first Content that is the relative directory path (without any leading/trailing slashes). - The second Content that is the basename for a rule file. - The third and beyond may only be one of\: - - "asynchronous" - - "require" - - "wait" - - - "stop": Two or more Content. - The first Content that is the relative directory path (without any leading/trailing slashes). - The second Content that is the basename for a rule file. - The third and beyond may only be one of\: - - "asynchronous" - - "require" - - "wait" - - - "thaw": Two or more Content. - The first Content that is the relative directory path (without any leading/trailing slashes). - The second Content that is the basename for a rule file. - The third and beyond may only be one of\: - - "asynchronous" - - "require" - - "wait" - - - "timeout": Two Content. - The first being one of\: - - "exit" - - "start" - - "stop" - - "kill" - The (optional) second Content being a positive whole number or 0. diff --git a/documents/standards/controller/packet.txt b/documents/standards/controller/packet.txt deleted file mode 100644 index a290d20..0000000 --- a/documents/standards/controller/packet.txt +++ /dev/null @@ -1,55 +0,0 @@ -# fss-0002 -# -# license: open-standard-license-1.0 -# - -Packet Specification: - The controller program communicates use the FSS-000F (Packet). - This specification declares how the Payload Block, which is in FSS-000E (Payload) format, is required to be used. - - Only a single "header" is allowed. - Only a single "payload" is allowed. - - Packet Structure\: - Packet is grouped into the following blocks\: - - control: A single 1-byte block representing control codes. - - size: A single 4-byte block representing the size of the entire packet, including the control block. - - The "header" Object contains the following FSS-0001 Extended Objects (depending on "type")\: - - action: A valid action type: "freeze", "kexec", "kill", "pause", "reboot", "reload", "rerun", "restart", "resume", "shutdown", "start", "stop", or "thaw". - - length: A positive whole number inclusively between 0 and 4294965248 representing the length of the "payload" (may be in binary, octal, decimal, duodecimal, or hexidecimal). - - status: The status code name or number representing an FSS status code, such as F_none, F_failure, or 200 (where a number may have error and warning bits and may be in binary, octal, decimal, duodecimal, or hexidecimal). - - type: The packet type that is one of "controller", "error", or "init". - - When there are multiple Objects of the same name inside the "header"\: - - action: The order represents the order in which the actions are performed. - - length: There may only be one length Object, all others after the first are ignored (may be in binary, octal, decimal, duodecimal, or hexidecimal). - - status: A status for each action, in the same order as the order of the action, such as F_none, F_failure, or 200 (where a number may have error and warning bits and may be in binary, octal, decimal, duodecimal, or hexidecimal). - - type: The first represent the type and all others represents a sub-type. - - There are different headers and payload properties based on the "type". - - The "controller" type\: - Supports the following headers: "action", "length", "status", and "type". - - Only a single "action" may be provided and must exist for request and response packets. - Only a single "status" may be provided and must exist for response packets. - - The "payload" is dependent on the "action". - - The "error" type\: - Supports the following headers: "length", "status", and "type". - - Only a single "status" may be provided and must exist for request and response packets. - - The "payload" is a NULL terminated string whose length is defined by the "length" "header" Content. - - There are different headers and payload properties based on the "type". - - The "init" type\: - Supports the following headers: "action", "length", "status", and "type". - - Only a single "action" may be provided and must exist for request and response packets. - Only a single "status" may be provided and must exist for response packets. - - The "payload" is dependent on the "action". diff --git a/documents/standards/controller/rule.txt b/documents/standards/controller/rule.txt deleted file mode 100644 index d02f601..0000000 --- a/documents/standards/controller/rule.txt +++ /dev/null @@ -1,96 +0,0 @@ -# fss-0002 -# -# license: open-standard-license-1.0 -# - -Rule Specification: - The Rule files follow the FSS-000D (Basic Rule) format with IKI-0000 (Unrestricted). - - A Rule file name is expected to have the file extension ".rule". - - For each Rule file\: - - The outer most part is a FSS-0002 (Basic List). - - The Basic List Object is considered the "Rule Type". - - The Basic List Content is determined by the specific "Rule Type". - - The Content for each "Rule Type" is called the "Item". - - Each Item Object is the "Item Name". - - Each Item Content is either the "Action" or the "Setting". - - Each Action Object is the "Action Name". - - Each Action Content are the "Action Parameters". - - Each Setting Object is the "Setting Name". - - Each Setting Content are the "Setting Values". - - The Rule Types\: - - "command": Follows either FSS-0003 (Extended List) or FSS-0001 (Extended). - - "script": Follows either FSS-0003 (Extended List) or FSS-0001 (Extended). - - "service": Follows either FSS-0003 (Extended List) or FSS-0001 (Extended). - - "settings": Is required and follows either FSS-0001 (Extended). - - "utility": Follows either FSS-0003 (Extended List) or FSS-0001 (Extended). - - For the above Rule Types, "settings" may be specified only once whereas the others may be specifed multiple times. - The "settings" Rule Type is always processed first, regardless of position. - The other Rule Types are processed top-down. - - The "settings" Rule Type has the following FSS-0001 (Extended)\: - - "affinity": One or more Content, each must be a 0 or greater whole number. - - "capability": One Content representing capabilities. - - "cgroup": Two or more Content, the first Content being either "existing" or "new" and the remaining representing a valid cgroup (control group) name, must have at least 1 graph character (non white space printing character) (leading and trailing white space are trimmed off). - - "define": Two Content, the first Content must be a case-sensitive valid environment variable name (alpha-numeric or underscore, but no leading digits). - - "engine": One or more Content representing a valid program name or path (such as "bash" or "/bin/bash") and any optional arguments. - - "environment": Zero or more Content, each must be a case-sensitive valid environment variable name (alpha-numeric or underscore, but no leading digits). - - "group": One or more Content representing group names or group ids. - - "limit": Three Content, with the first representing a valid resource type and the second and third being a valid resource limit number (positive whole number or 0). - - "name": One Content, must have at least 1 graph character (non white space printing character) (leading and trailing white space are trimmed off). - - "nice": One Content, must be a valid number for process "niceness" (Any whole number inclusively between -20 to 19). - - "on": Four Content, the first being a Rule Action, the second being "need", "want", or "wish", the third being a partial path, and the fourth being a Rule file name without ".rule" extension. - - "parameter": Two Content, the first Content must be a case-sensitive valid IKI name and the second being an IKI value. - - "path": One Content representing a valid PATH environment string (such as "/bin:/sbin:/usr/bin"). - - "scheduler": One or two Content representing a scheduler name and the optional numeric priority (Any whole number inclusively between 0 and 99). - - "timeout": One or two content with the first being one of "exit", "start", "stop", or "kill" and the (optional) second Content being a positive whole number or 0. - - "user": One Content representing a user name or user id. - - The "command" and "script" Rule Types allow the following the FSS-0001 (Extended)\: - - "freeze": One or more Content representing a program being executed and its arguments. - - "kill": One or more Content representing a program being executed and its arguments. - - "pause": One or more Content representing a program being executed and its arguments. - - "reload": One or more Content representing a program being executed and its arguments. - - "rerun": Two or more Content representing a Rule type that executes and its properties. - - "restart": One or more Content representing a program being executed and its arguments. - - "resume": One or more Content representing a program being executed and its arguments. - - "start": One or more Content representing a program being executed and its arguments. - - "stop": One or more Content representing a program being executed and its arguments. - - "thaw": One or more Content representing a program being executed and its arguments. - - "with": One or more Content representing special options for the Rule Type. - - The "service" and "utility" Rule Types allow the following the FSS-0001 (Extended)\: - - "pid_file": One Content representing the path to a PID file. - - "rerun": Two or more Content representing a Rule type that executes and its properties. - - "with": One or more Content being one of "full_path", "session_new", or "session_same". - - The "command" and "service" Rule Types allow the following the FSS-0003 (Extended List)\: - - "freeze": A list repesenting multiple programs and their respective arguments to execute. - - "kill": A list repesenting multiple programs and their respective arguments to execute. - - "pause": A list repesenting multiple programs and their respective arguments to execute. - - "reload": A list repesenting multiple programs and their respective arguments to execute. - - "restart": A list repesenting multiple programs and their respective arguments to execute. - - "resume": A list repesenting multiple programs and their respective arguments to execute. - - "start": A list repesenting multiple programs and their respective arguments to execute. - - "stop": A list repesenting multiple programs and their respective arguments to execute. - - "thaw": A list repesenting multiple programs and their respective arguments to execute. - - The "script" and "utility" Rule Types allow the following the FSS-0003 (Extended List)\: - - "freeze": A list repesenting the contents of a script, such as a GNU Bash shell. - - "kill": A list repesenting the contents of a script, such as a GNU Bash shell. - - "pause": A list repesenting the contents of a script, such as a GNU Bash shell. - - "reload": A list repesenting the contents of a script, such as a GNU Bash shell. - - "restart": A list repesenting the contents of a script, such as a GNU Bash shell. - - "resume": A list repesenting the contents of a script, such as a GNU Bash shell. - - "start": A list repesenting the contents of a script, such as a GNU Bash shell. - - "stop": A list repesenting the contents of a script, such as a GNU Bash shell. - - "thaw": A list repesenting the contents of a script, such as a GNU Bash shell. - - The "rerun" Rule Type Content has the following structure\: - The first Content represents one of: "freeze", "kill", "pause", "reload", "restart", "resume", "start", "stop", or "thaw". - The second Content represents one of: "success" or "failure". - The third and more Content represents one of: "delay", "max", or "reset". - Where "delay" and "max" must be followed by a positive number or the number 0. diff --git a/documents/standards/controller/specifications/entry.txt b/documents/standards/controller/specifications/entry.txt new file mode 100644 index 0000000..ef38cdf --- /dev/null +++ b/documents/standards/controller/specifications/entry.txt @@ -0,0 +1,145 @@ +# fss-0002 iki-0000 +# +# license: open-standard-license-1.0 +# +# This file (assumed to be named entry.txt) can be more easily read using the following iki_read commands: +# iki_read entry.txt +Q -w -W code '"' '"' +# +# To read the "Entry Specification" section of this file, use this command sequence: +# fss_basic_list_read entry.txt +Q -cn "Entry Specification" | iki_read +Q -w -W code '"' '"' +# + +Entry Specification: + The Entry files follow the code:"FSS-0005 (Somewhat Basic List)" format. + + An Entry file name is expected to have the file extension code:".entry". + + For each Entry file\: + - The outer most part is a code:"FSS-0002 (Basic List)". + - The Basic List Object is considered the code:"Item". + - The Basic List Content are considered the code:"Actions". + - The code:"Actions" are code:"FSS-0001 (Extended)". + - Each Action Object is the code:"Action Name". + - Each Action Content are the code:"Action Parameters". + + The Items\: + - code:"main": required. + + - code:"settings": optional, Actions may be one of\: + - code:"control": One to two Content. + The first Content is a relative or absolute path to a socket file. + The second Content an optional code:"readonly". + - code:"control_group": Exactly one Content that is a group name or group id. + - code:"control_mode": Exactly one Content that is a valid file mode. + - code:"control_user": Exactly one Content that is a user name or user id. + - code:"define": Two Content, the first Content must be a case-sensitive valid environment variable name (alpha-numeric or underscore, but no leading digits). + - code:"mode": Exactly one Content that is one of code:"program" or code:"service". + - code:"parameter": Two Content, the first Content must be a case-sensitive valid IKI name and the second being an IKI value. + - code:"pid": Exactly one Content that is one of code:"disable", code:"require", or code:"ready". + - code:"pid_file": Exactly one Content that is a relative or absolute path to a pid file. + - code:"session": Exactly one Content that is one of code:"new" or code:"same". + - code:"show": Exactly one Content that is one of code:"normal" or code:"init". + - code:"timeout": One or two content with the first being one of code:"exit", code:"start", code:"stop", or code:"kill" and the (optional) second Content being a positive whole number or 0. + + The Entry file may have any other valid Item Objects, but only the above are reserved. + + The Actions\: + - code:"consider": One or more Content. + The first Content is the relative file path (without any leading/trailing slashes and without file extension). + The second Content is the basename for a rule file. + The third and beyond may only be one of\: + - code:"asynchronous" + - code:"require" + - code:"wait" + + - code:"execute": One or more Content. + The first Content is the program name or full path to the program (the program may be a script). + All remaining Content are passed as parameters to the program being executed. + + - code:"failsafe": One Content that is a valid Object name, except for the reserved code:"main". + + - code:"freeze": Two or more Content. + The first Content that is the relative directory path (without any leading/trailing slashes). + The second Content that is the basename for a rule file. + The third and beyond may only be one of\: + - code:"asynchronous" + - code:"require" + - code:"wait" + + - code:"item": One Content that is a valid Object name, except for the reserved code:"main". + + - code:"kill": Two or more Content. + The first Content that is the relative directory path (without any leading/trailing slashes). + The second Content that is the basename for a rule file. + The third and beyond may only be one of\: + - code:"asynchronous" + - code:"require" + - code:"wait" + + - code:"pause": Two or more Content. + The first Content that is the relative directory path (without any leading/trailing slashes). + The second Content that is the basename for a rule file. + The third and beyond may only be one of\: + - code:"asynchronous" + - code:"require" + - code:"wait" + + - code:"ready": Zero or One Content. + The first may only be one of\: + - code:"wait" + + - code:"reload": Two or more Content. + The first Content that is the relative directory path (without any leading/trailing slashes). + The second Content that is the basename for a rule file. + The third and beyond may only be one of\: + - code:"asynchronous" + - code:"require" + - code:"wait" + + - code:"restart": Two or more Content. + The first Content that is the relative directory path (without any leading/trailing slashes). + The second Content that is the basename for a rule file. + The third and beyond may only be one of\: + - code:"asynchronous" + - code:"require" + - code:"wait" + + - code:"resume": Two or more Content. + The first Content that is the relative directory path (without any leading/trailing slashes). + The second Content that is the basename for a rule file. + The third and beyond may only be one of\: + - code:"asynchronous" + - code:"require" + - code:"wait" + + - code:"start": Two or more Content. + The first Content that is the relative directory path (without any leading/trailing slashes). + The second Content that is the basename for a rule file. + The third and beyond may only be one of\: + - code:"asynchronous" + - code:"require" + - code:"wait" + + - code:"stop": Two or more Content. + The first Content that is the relative directory path (without any leading/trailing slashes). + The second Content that is the basename for a rule file. + The third and beyond may only be one of\: + - code:"asynchronous" + - code:"require" + - code:"wait" + + - code:"thaw": Two or more Content. + The first Content that is the relative directory path (without any leading/trailing slashes). + The second Content that is the basename for a rule file. + The third and beyond may only be one of\: + - code:"asynchronous" + - code:"require" + - code:"wait" + + - code:"timeout": One or two Content. + The first being one of\: + - code:"exit" + - code:"start" + - code:"stop" + - code:"kill" + The (optional) second Content being a positive whole number or 0. diff --git a/documents/standards/controller/specifications/exit.txt b/documents/standards/controller/specifications/exit.txt new file mode 100644 index 0000000..83ab08f --- /dev/null +++ b/documents/standards/controller/specifications/exit.txt @@ -0,0 +1,131 @@ +# fss-0002 iki-0000 +# +# license: open-standard-license-1.0 +# +# This file (assumed to be named exit.txt) can be more easily read using the following iki_read commands: +# iki_read exit.txt +Q -w -W code '"' '"' +# +# To read the "Exit Specification" section of this file, use this command sequence: +# fss_basic_list_read exit.txt +Q -cn "Exit Specification" | iki_read +Q -w -W code '"' '"' +# + +Exit Specification: + The Exit files follow the code:"FSS-0005 (Somewhat Basic List)" format. + + An Exit file name is expected to have the file extension code:".exit". + + For each Exit file\: + - The outer most part is a code:"FSS-0002 (Basic List)". + - The Basic List Object is considered the code:"Item". + - The Basic List Content are considered the code:"Actions". + - The code:"Actions" are code:"FSS-0001 (Extended)". + - Each Action Object is the code:"Action Name". + - Each Action Content are the code:"Action Parameters". + + The Items\: + - code:"main": required. + + - code:"settings": optional, Actions may be one of\: + - code:"pid": Exactly one Content that is one of code:"disable", code:"require", or code:"ready". + - code:"session": Exactly one Content that is one of code:"new" or code:"same". + - code:"show": Exactly one Content that is one of code:"normal" or code:"init". + - code:"timeout": One or Two content with the first being one of code:"exit", code:"start", code:"stop", or code:"kill" and the (optional) second Content being a positive whole number or 0. + + The Exit file may have any other valid Item Objects, but only the above are reserved. + + The Actions\: + - code:"consider": One or more Content. + The first Content that is the relative file path (without any leading/trailing slashes and without file extension). + The second Content that is the basename for a rule file. + The third and beyond may only be one of\: + - code:"asynchronous" + - code:"require" + - code:"wait" + + - code:"failsafe": One Content that is a valid Object name, except for the reserved code:"main". + + - code:"freeze": Two or more Content. + The first Content that is the relative directory path (without any leading/trailing slashes). + The second Content that is the basename for a rule file. + The third and beyond may only be one of\: + - code:"asynchronous" + - code:"require" + - code:"wait" + + - code:"item": One Content that is a valid Object name, except for the reserved code:"main". + + - code:"kill": Two or more Content. + The first Content that is the relative directory path (without any leading/trailing slashes). + The second Content that is the basename for a rule file. + The third and beyond may only be one of\: + - code:"asynchronous" + - code:"require" + - code:"wait" + + - code:"pause": Two or more Content. + The first Content that is the relative directory path (without any leading/trailing slashes). + The second Content that is the basename for a rule file. + The third and beyond may only be one of\: + - code:"asynchronous" + - code:"require" + - code:"wait" + + - code:"ready": Zero or One Content. + The first may only be one of\: + - code:"wait" + + - code:"reload": Two or more Content. + The first Content that is the relative directory path (without any leading/trailing slashes). + The second Content that is the basename for a rule file. + The third and beyond may only be one of\: + - code:"asynchronous" + - code:"require" + - code:"wait" + + - code:"restart": Two or more Content. + The first Content that is the relative directory path (without any leading/trailing slashes). + The second Content that is the basename for a rule file. + The third and beyond may only be one of\: + - code:"asynchronous" + - code:"require" + - code:"wait" + + - code:"resume": Two or more Content. + The first Content that is the relative directory path (without any leading/trailing slashes). + The second Content that is the basename for a rule file. + The third and beyond may only be one of\: + - code:"asynchronous" + - code:"require" + - code:"wait" + + - code:"start": Two or more Content. + The first Content that is the relative directory path (without any leading/trailing slashes). + The second Content that is the basename for a rule file. + The third and beyond may only be one of\: + - code:"asynchronous" + - code:"require" + - code:"wait" + + - code:"stop": Two or more Content. + The first Content that is the relative directory path (without any leading/trailing slashes). + The second Content that is the basename for a rule file. + The third and beyond may only be one of\: + - code:"asynchronous" + - code:"require" + - code:"wait" + + - code:"thaw": Two or more Content. + The first Content that is the relative directory path (without any leading/trailing slashes). + The second Content that is the basename for a rule file. + The third and beyond may only be one of\: + - code:"asynchronous" + - code:"require" + - code:"wait" + + - code:"timeout": Two Content. + The first being one of\: + - code:"exit" + - code:"start" + - code:"stop" + - code:"kill" + The (optional) second Content being a positive whole number or 0. diff --git a/documents/standards/controller/specifications/packet.txt b/documents/standards/controller/specifications/packet.txt new file mode 100644 index 0000000..91d2bb6 --- /dev/null +++ b/documents/standards/controller/specifications/packet.txt @@ -0,0 +1,61 @@ +# fss-0002 iki-0000 +# +# license: open-standard-license-1.0 +# +# This file (assumed to be named packet.txt) can be more easily read using the following iki_read commands: +# iki_read packet.txt +Q -w -W code '"' '"' +# +# To read the "Packet Specification" section of this file, use this command sequence: +# fss_basic_list_read packet.txt +Q -cn "Packet Specification" | iki_read +Q -w -W code '"' '"' +# + +Packet Specification: + The controller program communicates use the code:"FSS-000F (Packet)". + This specification declares how the Payload Block, which is in code:"FSS-000E (Payload)" format, is required to be used. + + Only a single code:"header" is allowed. + Only a single code:"payload" is allowed. + + Packet Structure\: + Packet is grouped into the following blocks\: + - code:"control": A single 1-byte block representing control codes. + - code:"size": A single 4-byte block representing the size of the entire packet, including the control block. + + The code:"header" Object contains the following code:"FSS-0001 (Extended)" Objects (depending on code:"type")\: + - code:"action": A valid action type: code:"freeze", code:"kexec", code:"kill", code:"pause", code:"reboot", code:"reload", code:"rerun", code:"restart", code:"resume", code:"shutdown", code:"start", code:"stop", or code:"thaw". + - code:"length": A positive whole number inclusively between 0 and 4294965248 representing the length of the code:"payload" (may be in binary, octal, decimal, duodecimal, or hexidecimal). + - code:"status": The status code name or number representing an FSS status code, such as F_none, F_failure, or 200 (where a number may have error and warning bits and may be in binary, octal, decimal, duodecimal, or hexidecimal). + - code:"type": The packet type that is one of code:"controller", code:"error", or code:"init". + + When there are multiple Objects of the same name inside the code:"header"\: + - code:"action": The order represents the order in which the actions are performed. + - code:"length": There may only be one length Object, all others after the first are ignored (may be in binary, octal, decimal, duodecimal, or hexidecimal). + - code:"status": A status for each action, in the same order as the order of the action, such as F_none, F_failure, or 200 (where a number may have error and warning bits and may be in binary, octal, decimal, duodecimal, or hexidecimal). + - code:"type": The first represent the type and all others represents a sub-type. + + There are different headers and payload properties based on the code:"type". + + The code:"controller" type\: + Supports the following headers: code:"action", code:"length", code:"status", and code:"type". + + Only a single code:"action" may be provided and must exist for request and response packets. + Only a single code:"status" may be provided and must exist for response packets. + + The code:"payload" is dependent on the code:"action". + + The code:"error" type\: + Supports the following headers: code:"length", code:"status", and code:"type". + + Only a single code:"status" may be provided and must exist for request and response packets. + + The code:"payload" is a NULL terminated string whose length is defined by the code:"length" code:"header" Content. + + There are different headers and payload properties based on the code:"type". + + The code:"init" type\: + Supports the following headers: code:"action", code:"length", code:"status", and code:"type". + + Only a single code:"action" may be provided and must exist for request and response packets. + Only a single code:"status" may be provided and must exist for response packets. + + The code:"payload" is dependent on the code:"action". diff --git a/documents/standards/controller/specifications/rule.txt b/documents/standards/controller/specifications/rule.txt new file mode 100644 index 0000000..8ea846e --- /dev/null +++ b/documents/standards/controller/specifications/rule.txt @@ -0,0 +1,102 @@ +# fss-0002 iki-0000 +# +# license: open-standard-license-1.0 +# +# This file (assumed to be named rule.txt) can be more easily read using the following iki_read commands: +# iki_read rule.txt +Q -w -W code '"' '"' +# +# To read the "Rule Specification" section of this file, use this command sequence: +# fss_basic_list_read rule.txt +Q -cn "Rule Specification" | iki_read +Q -w -W code '"' '"' +# + +Rule Specification: + The Rule files follow the code:"FSS-000D (Basic Rule)" format with bold:"IKI-0000 (Unrestricted)". + + A Rule file name is expected to have the file extension code:".rule". + + For each Rule file\: + - The outer most part is a code:"FSS-0002 (Basic List)". + - The Basic List Object is considered the code:"Rule Type". + - The Basic List Content is determined by the specific code:"Rule Type". + - The Content for each code:"Rule Type" is called the code:"Item". + - Each Item Object is the code:"Item Name". + - Each Item Content is either the code:"Action" or the code:"Setting". + - Each Action Object is the code:"Action Name". + - Each Action Content are the code:"Action Parameters". + - Each Setting Object is the code:"Setting Name". + - Each Setting Content are the code:"Setting Values". + + The Rule Types\: + - code:"command": Follows either code:"FSS-0003 (Extended List)" or code:"FSS-0001 (Extended)". + - code:"script": Follows either code:"FSS-0003 (Extended List)" or code:"FSS-0001 (Extended)". + - code:"service": Follows either code:"FSS-0003 (Extended List)" or code:"FSS-0001 (Extended)". + - code:"settings": Is required and follows either code:"FSS-0001 (Extended)". + - code:"utility": Follows either code:"FSS-0003 (Extended List)" or code:"FSS-0001 (Extended)". + + For the above Rule Types, code:"settings" may be specified only once whereas the others may be specifed multiple times. + The code:"settings" Rule Type is always processed first, regardless of position. + The other Rule Types are processed top-down. + + The code:"settings" Rule Type has the following code:"FSS-0001 (Extended)"\: + - code:"affinity": One or more Content, each must be a 0 or greater whole number. + - code:"capability": One Content representing capabilities. + - code:"cgroup": Two or more Content, the first Content being either code:"existing" or code:"new" and the remaining representing a valid cgroup (control group) name, must have at least 1 graph character (non white space printing character) (leading and trailing white space are trimmed off). + - code:"define": Two Content, the first Content must be a case-sensitive valid environment variable name (alpha-numeric or underscore, but no leading digits). + - code:"engine": One or more Content representing a valid program name or path (such as code:"bash" or code:"/bin/bash") and any optional arguments. + - code:"environment": Zero or more Content, each must be a case-sensitive valid environment variable name (alpha-numeric or underscore, but no leading digits). + - code:"group": One or more Content representing group names or group ids. + - code:"limit": Three Content, with the first representing a valid resource type and the second and third being a valid resource limit number (positive whole number or 0). + - code:"name": One Content, must have at least 1 graph character (non white space printing character) (leading and trailing white space are trimmed off). + - code:"nice": One Content, must be a valid number for process code:"niceness" (Any whole number inclusively between -20 to 19). + - code:"on": Four Content, the first being a Rule Action, the second being code:"need", code:"want", or code:"wish", the third being a partial path, and the fourth being a Rule file name without code:".rule" extension. + - code:"parameter": Two Content, the first Content must be a case-sensitive valid IKI name and the second being an IKI value. + - code:"path": One Content representing a valid code:"PATH" environment string (such as code:"/bin:/sbin:/usr/bin"). + - code:"scheduler": One or two Content representing a scheduler name and the optional numeric priority (Any whole number inclusively between 0 and 99). + - code:"timeout": One or two content with the first being one of code:"exit", code:"start", code:"stop", or code:"kill" and the (optional) second Content being a positive whole number or 0. + - code:"user": One Content representing a user name or user id. + + The code:"command" and code:"script" Rule Types allow the following the code:"FSS-0001 (Extended)"\: + - code:"freeze": One or more Content representing a program being executed and its arguments. + - code:"kill": One or more Content representing a program being executed and its arguments. + - code:"pause": One or more Content representing a program being executed and its arguments. + - code:"reload": One or more Content representing a program being executed and its arguments. + - code:"rerun": Two or more Content representing a Rule type that executes and its properties. + - code:"restart": One or more Content representing a program being executed and its arguments. + - code:"resume": One or more Content representing a program being executed and its arguments. + - code:"start": One or more Content representing a program being executed and its arguments. + - code:"stop": One or more Content representing a program being executed and its arguments. + - code:"thaw": One or more Content representing a program being executed and its arguments. + - code:"with": One or more Content representing special options for the Rule Type. + + The code:"service" and code:"utility" Rule Types allow the following the code:"FSS-0001 (Extended)"\: + - code:"pid_file": One Content representing the path to a PID file. + - code:"rerun": Two or more Content representing a Rule type that executes and its properties. + - code:"with": One or more Content being one of code:"full_path", code:"session_new", or code:"session_same". + + The code:"command" and code:"service" Rule Types allow the following the code:"FSS-0003 (Extended List)"\: + - code:"freeze": A list repesenting multiple programs and their respective arguments to execute. + - code:"kill": A list repesenting multiple programs and their respective arguments to execute. + - code:"pause": A list repesenting multiple programs and their respective arguments to execute. + - code:"reload": A list repesenting multiple programs and their respective arguments to execute. + - code:"restart": A list repesenting multiple programs and their respective arguments to execute. + - code:"resume": A list repesenting multiple programs and their respective arguments to execute. + - code:"start": A list repesenting multiple programs and their respective arguments to execute. + - code:"stop": A list repesenting multiple programs and their respective arguments to execute. + - code:"thaw": A list repesenting multiple programs and their respective arguments to execute. + + The code:"script" and code:"utility" Rule Types allow the following the code:"FSS-0003 (Extended List)"\: + - code:"freeze": A list repesenting the contents of a script, such as a GNU Bash shell. + - code:"kill": A list repesenting the contents of a script, such as a GNU Bash shell. + - code:"pause": A list repesenting the contents of a script, such as a GNU Bash shell. + - code:"reload": A list repesenting the contents of a script, such as a GNU Bash shell. + - code:"restart": A list repesenting the contents of a script, such as a GNU Bash shell. + - code:"resume": A list repesenting the contents of a script, such as a GNU Bash shell. + - code:"start": A list repesenting the contents of a script, such as a GNU Bash shell. + - code:"stop": A list repesenting the contents of a script, such as a GNU Bash shell. + - code:"thaw": A list repesenting the contents of a script, such as a GNU Bash shell. + + The code:"rerun" Rule Type Content has the following structure\: + The first Content represents one of: code:"freeze", code:"kill", code:"pause", code:"reload", code:"restart", code:"resume", code:"start", code:"stop", or code:"thaw". + The second Content represents one of: code:"success" or code:"failure". + The third and more Content represents one of: code:"delay", code:"max", or code:"reset". + Where code:"delay" and code:"max" must be followed by a positive number or the number 0. diff --git a/documents/standards/controller/specifications/task.txt b/documents/standards/controller/specifications/task.txt new file mode 100644 index 0000000..8175aa4 --- /dev/null +++ b/documents/standards/controller/specifications/task.txt @@ -0,0 +1,14 @@ +# fss-0002 iki-0000 +# +# license: open-standard-license-1.0 +# +# This file (assumed to be named task.txt) can be more easily read using the following iki_read commands: +# iki_read task.txt +Q -w -W code '"' '"' +# +# To read the "Task Specification" section of this file, use this command sequence: +# fss_basic_list_read task.txt +Q -cn "Task Specification" | iki_read +Q -w -W code '"' '"' +# +# A "Task" is not fully implemented but is provided as a proposal for consideration and is subject to completion or removal. +# + +Task Specification: diff --git a/documents/standards/controller/time.txt b/documents/standards/controller/specifications/time.txt similarity index 100% rename from documents/standards/controller/time.txt rename to documents/standards/controller/specifications/time.txt diff --git a/documents/standards/controller/task.txt b/documents/standards/controller/task.txt deleted file mode 100644 index 5c974ae..0000000 --- a/documents/standards/controller/task.txt +++ /dev/null @@ -1,7 +0,0 @@ -# fss-0002 -# -# license: open-standard-license-1.0 -# -# A "Task" is not fully implemented but is provided as a proposal for consideration and is subject to completion or removal. - -Task Specification: diff --git a/documents/standards/fake/documents/fakefile.txt b/documents/standards/fake/documents/fakefile.txt new file mode 100644 index 0000000..017bbf8 --- /dev/null +++ b/documents/standards/fake/documents/fakefile.txt @@ -0,0 +1,627 @@ +# fss-0002 iki-0000 +# +# license: open-standard-license-1.0 +# +# This file (assumed to be named fakefile.txt) can be more easily read using the following iki_read commands: +# iki_read fakefile.txt +Q -w -rrr ASCII ASCII GCC GCC HTML HTML -WW character "'" "'" code '"' '"' +# +# To read the "Fakefile Documentation" section of this file, use this command sequence: +# fss_basic_list_read fakefile.txt +Q -cn "Fakefile Documentation" | iki_read +Q -w -rrr ASCII ASCII GCC GCC HTML HTML -WW character "'" "'" code '"' '"' +# + +Fakefile Documentation: + This describes intent and purposes of the file:"fakefile" file settings. + For specific details on the allowed formatting, see the file:"fakefile.txt" under the specifications folder. + + All files specified are relative to the project root. + + The reserved Section Names are defined as follows\: + - code:"settings"\: + Any configuration specific to this file:"fakefile" is stored here. + This includes the declaration of define and parameter IKI variable substitution values. + + The build settings may also be specified in the bold:"Settings Section". + + The following settings are available (in addition to the build settings)\: + - code:"compiler"\: + This represents the name of the compiler program to use, such as code:"gcc". + + The programs code:"gcc" and code:"clang" are known to work. + Many of the parameters in the settings file can be changed if not using GCC:"GNU Compiler Collection", but there may be certain hard-coded functionality that may need to be changed. + + When specified and code:"load_build" is code:"true", then this will override the code:"build_compiler" specified in the loaded build settings. + + - code:"define"\: + This represents an environment variable to define on run. + The environment variable name is case-sensitive. + This replaces the value of any existing environment variable with this name. + + - code:"environment"\: + This represents all environment variables that are exposed when executing sub-programs. + This is not auto-populated for environment variables defined in the code:"define" setting. + + When defined with no bold:"Content", then this means that no environment variables are exposed. + When not defined at all, then all environment variables are exposed. + Environment variables may still be exposed if code:"load_build" is code:"true" and the build setting file defines any environment variable names. + + - code:"fail"\: + Designates the fail mode when running external programs, such as through the code:"run" or code:"shell" operations. + + There are three options\: + - code:"exit": Designates to exit the program on failure, printing an error message. + - code:"warn": Designates to continue on and if in verbose mode then print a warning. + - code:"ignore": Designates to do nothing. + + The return code for programs can still be retrieved through using the reserved bold:"IKI" variable code:"return". + + - code:"import"\: + Load this file:"fakefile". + The code:"settings" section data from the imported file:"fakefile" is treated as if it were appended to the end of the current file:"fakefile" code:"setting" section. + Each section in the imported file:"fakefile" is treated as if it were appended to either the end of a matching section, if found, or appended at the end of the file:"fakefile", if no matches are found. + This a non-recursive operation and the imported file itself cannot perform an import. + Relative paths are relative to the importing file. + Absolute paths that start with code:"./" are relative to the project root rather than the importing file. + Absolute paths that start with code:"/" are treated normally. + + This is neither implemented nor supported by Featureless Make 0.6.x and earlier. + + - code:"indexer"\: + This represents the name of the indexer program to use, such as code:"ar". + An indexer is often called a linker. + + Similar to code:"build_compiler", any linker that supports the code:"ar" program parameters is effectively supported. + + When specified and code:"load_build" is code:"true", then this will override the code:"build_indexer" specified in the loaded build settings. + + - code:"indexer_arguments"\: + This represents arguments needed to build an archive file from object files, such as code:"rcs". + These arguments are placed immediately before the object files passed to the code:"indexer" program. + + - code:"load_build"\: + This represents whether or not to load the load the build settings file. + The first Content value may be code:"true" to load the build settings and code:"false" to not load the build settings file. + + - code:"parameter"\: + This defines an IKI variable name to substitute with the value. + This replaces the value of any existing environment variable with this name. + + The first bold:"Content" value represents the bold:"IKI" variable name. + All bold:"Content" values after the first represent the values the matching bold:"IKI" variable is replaced with. + + The parameter variable name code:"return" is used to store the return result of a code:"run" or code:"shell" operation. + Setting this here only sets the default code:"return" parameter variable value. + + - code:"main"\: + This is the main entry point when processing the file:"fakefile". + This is processed top-down until the end of the list is reached. + + The following operations are available\: + - code:"and"\: + A special type of an code:"if" operation. + May only be specified following a valid code:"if", code:"and", or code:"or" operation. + This is executed only if the previous code:"if" operation result is true. + + When executed, this performs the test and returns true or false as appropriate. + When not executed, this passes through the result of the previous code:"if", code:"and", or code:"or" operation. + + - code:"build"\: + Run the fake build operation as if code:"fake build" was run instead of code:"fake make". + Command line arguments are automatically passed to the fake build operation. + + Accepts an optional bold:"Content" that is a file name to a build settings file to use instead of the default. + This file name is relative to the data build directory (which can be changed by code:"-D/--data" parameter). + + If the optional file name Content is specified, then it also supports additional modes to use instead of the default mode. + + When no additional bold:"Content" after the code:"build" is specified, then the default (or program supplied) settings file and modes are used. + When the first bold:"Content" after the code:"build" is specified as an empty string, then the default (or program supplied) settings file is used. + When the second bold:"Content" after the code:"build" (and there is no third bold:"Content"), then no modes are used. + + - code:"break"\: + Perform an exit from the current make operation. + This only exists the current depth. + If the depth is at the top (aka: 0), then this is identical to the code:"exit" section operation. + The second bold:"Content" may be either code:"succeed" or code:"failure" to designate on whether or not to exit as a success or as a failure. + When set to code:"failure" this will trigger any failure (with message), depending on the current fail state. + + - code:"clean"\: + Run the fake clean operation as if code:"fake clean" was run instead of code:"fake make". + Command line arguments are automatically passed to the build operation. + + - code:"clone"\: + Copy all files (and directories), preserving all properties, into the last content. + If there are more than one file (or directory) being copied, then the final path must be a directory. + + All bold:"Content", except last, represents the files to clone. + The last bold:"Content" represents the destination file (or directory) to clone to. + + - code:"compile"\: + Execute the compiler program, such as code:"gcc". + + All bold:"Content" are passed as arguments to the respective code:"gcc" program. + + - code:"copy"\: + Copy all files (and directories) into the last content. + If there are more than one file (or directory) being copied, then the final path must be a directory. + + All bold:"Content", except last, represents the files to copy. + The last bold:"Content" represents the destination file (or directory) to copy to. + + - code:"define"\: + This represents an environment variable to define on run. + The environment variable name is case-sensitive. + This replaces the value of any existing environment variable with this name. + + - code:"delete"\: + Delete one or more files or directories. + + All bold:"Content" must be the file or directory to be deleted. + + If the path is a directory and is not empty, then this will not delete the directory. + + - code:"deletes"\: + Identical to code:"delete", except that when the path is a directory and is not empty, then this will delete the directory. + + - code:"else"\: + Performs a programmatic code:"else" condition. + Must be specified following a valid if operation (and the operation it affects). + + This has no bold:"Content". + + An else operation may not follow this. + An if operation may immediately follow to represent an code:"else if" condition. + + - code:"exit"\: + Perform an exit from the entire make operation. + This always exits completely, regardless of the operation depth. + The second bold:"Content" may be either code:"success" or code:"failure" to designate on whether or not to exit as success or failure. + + When set to code:"failure" this will trigger a failure message. + When set to code:"failure", the fail state will be forcibly changed to code:"failure" regardless of the current fail state. + + - code:"fail"\: + Toggle how the to handle an operation failure. + + The first bold:"Content" may be one of the following\: + code:"exit": Set failure handler to exit on failure. + code:"warn": Set failure handler to print a warning on failure but continue on. + code:"ignore": Set failure handler to continue on regardless of failure. + + - code:"group"\: + Change the group role for a given file. + + The first bold:"Content" represents the group to assign. + The second bold:"Content" represents the file to assign the group to. + + - code:"groups"\: + Identical to group operation, except this will recursively apply the mode to all files within the given file, if that file is a directory file path. + + - code:"if"\: + Performs a programmatic code:"if" condition. + May be specified following a valid code:"else" operation. + + The bold:"Content" represents a set of conditions to perform. + + The code:"if" operation may be used in conjunction with the code:"and", code:"or", and the code:"else" operations. + + The conditional logic is different from normal logic found in most software programs. + There is only one order of operation, a top-down design where the current operation relates to the previous operation. + This is mostly relevant when code:"if" operation is followed by an code:"and" or an code:"or" operation. + + Consider the following\: + code:"if parameter xxx + or parameter yyy + and parameter zzz + print first + else + if parameter www + print second + else + print third" + + The resulting logic is as follows\: + 1) If code:"xxx" is defined, then... + 2) If result from (1) is TRUE or if code:"yyy" is defined, then... + 3) If result from (2) is TRUE and if code:"zzz" is defined, then... + 4) If result from (3) is FALSE, then... + 5) If result from (4) is TRUE, then... + 6) If result from (5) is FALSE, then... + + For all conditions that rely on numbers, only whole numbers are (currently) supported. + + conditions\: + - code:"== \"left\" \"right\""\: + Compare all parameters to be equal. + Requires 2 or more after the code:"==". + For example, code:"if == 'a' 'b' 'c' 'd'" would test: code:"'a' == 'b' && 'b' == 'c' && 'c' == 'd'". + This performs only string-based comparisons. + + - code:"> \"left string\" \"right string\""\: + Compare code:"left" to code:"right" for greater than. + Requires 2 or more after the code:">". + For example, code:"if > 0 1 2 3" would test: code:"0 > 1 && 1 > 2 && 2 > 3". + This performs only number-based comparisons. + + - code:"< \"left string\" \"right string\""\: + Compare code:"left" to code:"right" for less than. + Requires 2 or more after the code:">". + For example, code:"if < 0 1 2 3" would test: code:"0 < 1 && 1 < 2 && 2 < 3". + This performs only number-based comparisons. + + - code:">= \"left string\" \"right string\""\: + Compare code:"left" to code:"right" for greater than or equal to. + Requires 2 or more after the code:">=". + For example, code:"if >= 0 1 2 3" would test: code:"0 >= 1 && 1 >= 2 && 2 >= 3". + This performs only number-based comparisons. + + - code:"<= \"left string\" \"right string\""\: + Compare code:"left" to code:"right" for less than or equal to. + Requires 2 or more after the code:">=". + For example, code:"if <= 0 1 2 3" would test: code:"0 <= 1 && 1 <= 2 && 2 <= 3". + This performs only number-based comparisons. + + - code:"<> \"left\" \"right\""\: + Compare all parameters to be not equal. + Requires 2 or more after the code:"==". + For example, code:"if <> 'a' 'b' 'c'" would test: code:"'a' <> 'b' && 'b' <> 'c' && 'a' <> 'c'". + This performs only string-based comparisons. + + - code:"define \"some define name\""\: + Test if one or more names are defined as an environment variable. + For example, code:"if define PWD SHELL" would test if both the code:"PWD" and the code:"SHELL" variables are defined via the environment variables. + + - code:"exist \"file path\""\: + Test if file exists. + For example, code:"if exist \"a.txt\" \"b.txt\"" would test if both the file code:"a.txt" and code:"b.txt" exist. + + - code:"failure"\: + Test if the previous section operation failed. + + - code:"group \"some mode\" \"some file\""\: + For example, code:"if group friends a.txt b.txt" would test if both file code:"a.txt" and code:"b.txt" have a group named code:"we". + + - code:"is block character directory fifo link regular socket for \"file path\""\: + Test if one or more files exist and if each file is any of the given types. + The given types must be followed by code:"for" to designate where the the file paths begin. + For example, code:"if is regular directory for \"a.txt\" \"b.txt\"" would test if both the file code:"a.txt" and code:"b.txt" exist and are either of type code:"regular" or type code:"directory". + + - code:"mode is/has \"some mode\" \"some file\""\: + Test if one or more files has the exact mode (code:"is") or has at least the given modes (code:"has"). + For example, code:"if mode is u+r a.txt b.txt" would test if both file code:"a.txt" and code:"b.txt" only have owner set to read. + For example, code:"if mode has u+r a.txt b.txt" would test if both file code:"a.txt" and code:"b.txt" has owner set to read, and all other modes can be anything. + + - code:"not"\: + Perform the test expecting a false result rather than a true result. + This is to be immediately followed by a valid if condition as well as all appropriate valid content associated with that if condition. + + Only the following if conditions are supported\: + - code:"define". + - code:"exist". + - code:"group". + - code:"is". + - code:"mode". + - code:"owner". + - code:"parameter". + + Examples\: + - code:"if not parameter work" + - code:"if not exist documentation.txt" + + - code:"owner \"some mode\" \"some file\""\: + Test if one or more files has the given owner. + For example, code:"if owner me a.txt b.txt" would test if both file code:"a.txt" and code:"b.txt" have an owner named code:"me". + + - code:"parameter \"some parameter name\""\: + Test if one or more names are defined as a code:"parameter" variable. + For example, code:"if parameter verbose silent" would test if both the code:"verbose" and the code:"silent" variables are defined via the code:"parameter" setting. + + Reserved parameters that represent program arguments, three forms are available. + For example, the program argument code:"-w/--work" has the reserved word code:"work" and has three forms\: + 1) code:"work". + 2) code:"work:option". + 3) code:"work:value". + + In the case of form 1, the code:"if parameter work" would be true if the argument is passed to the program or a default is provided. + In the case of form 2, the code:"if parameter work:option" would be true if the argument is passed to the program. + In the case of form 3, the code:"if parameter work:value" would be true if the argument is passed to the program and has a non-zero value. + + Some reserved parameters, such as the code:"verbosity", has no code:"value" and in this case would always return false for code:"if parameter verbosity:value". + + Multi-valued reserved parameters expand into multiple parameters (such as when using multiple code:"-m/--mode"). + Avoid this behavior by wrapping the the bold:"IKI" variable in quotes. + + The following are reserved parameters\: + - code:"build": Associated with code:"-b/--build" parameter. + - code:"color": Associated with code:"+d/++dark", code:"+l/++light", and code:"+n/++no_color" parameters. + - code:"current": The absolute path to the current working directory (present working directory) (Always has a trailing forward slash). + - code:"data": Associated with code:"-D/--data" parameter. + - code:"define": Associated with code:"-d/--define" parameter. + - code:"fakefile": Associated with code:"-f/--fakefile" parameter. + - code:"mode": Associated with code:"-m/--mode" parameter and possibly with the build settings default mode code:"modes_default". + - code:"process": Associated with code:"-p/--process" parameter. + - code:"return": Contains the return value of a previous operation that produces a return code. + - code:"settings": Associated with code:"-s/--settings" parameter. + - code:"sources": Associated with code:"-S/--sources" parameter. + - code:"top": The absolute path to the code:"top" directory, which is the base project directory (Always has a trailing forward slash). + - code:"verbosity": Associated with code:"+Q/++quiet", code:"+E/++error", code:"+N/++normal", code:"+V/++verbose", and code:"+D/++debug" parameters. + - code:"work": Associated with code:"-w/--work" parameter. + + - code:"succeed"\: + Test if the previous section operation succeeded. + + - code:"index"\: + Execute the linker program, such as code:"ar". + + All bold:"Content" are passed as arguments to the respective code:"ar" program. + + - code:"link"\: + Create a symbolic link from some point to some target. + + The first bold:"Content", when there are more than 2 arguments, may be either code:"force" or code:"strict". + The second to last bold:"Content" represents the target file. + The last bold:"Content" represents the point file. + + The code:"force" bold:"Content" designates that the point file will be overwritten if the file already exists. + The code:"strict" bold:"Content" requires that the target file already exists. + + - code:"mode"\: + Change the mode permissions for a given file. + + The first bold:"Content" represents the mode to assign. + The second bold:"Content" represents the file to assign the mode to. + + - code:"modes"\: + Identical to mode operation, except this will recursively apply the mode to all files within the given file, if that file is a directory file path. + + - code:"move"\: + Move all files (and directories) into the last content. + If there are more than one file (or directory) being copied, then the final path must be a directory. + + All bold:"Content", except last, represents the files to move. + The last bold:"Content" represents the destination file (or directory) to move to. + + - code:"operate"\: + Begin execution of another Section. + + The first bold:"Content" represents the name of the Section Object to execute. + This may be neither the code:"settings" Section no the code:"main" Section. + Recursion is prohibited, a Section that is already on the operation stack may not be called again. + Once the operation is off the stack, it can then be called again. + + - code:"or"\: + A special type of an code:"if" operation. + May only be specified following a valid code:"if", code:"and", or code:"or" operation. + This is executed only if the previous code:"if" operation result is false. + + When executed, this performs the test and returns true or false as appropriate. + When not executed, this passes through the result of the previous code:"if", code:"and", or code:"or" operation. + + - code:"owner"\: + Change the owner role for a given file. + + The first bold:"Content" represents the role to assign. + The second bold:"Content" represents the file to assign the role to. + + - code:"owners"\: + Identical to owner operation, except this will recursively apply the mode to all files within the given file, if that file is a directory file path. + + - code:"parameter"\: + This represents a variable defined within the scope of the file:"fakefile". + This is not exported as an environment variable and is therefore not visible to any executed programs or scripts. + This replaces the value of any existing parameter variable with this name. + The reserved parameter variable names (see IKI vocabulary context section below) may not be changed by this. + + - code:"pop"\: + Pop a directory path of the path stack, thereby changing to the previous directory on the stack. + This is a change directory command similar to a back button in a browser. + + This has no bold:"Content". + + This does not generate an error if the path stack is empty. + If the directory popping to no longer exists, then an error occurs. + + - code:"print"\: + Print the content to the output screen. + This always prints a newline at the end. + + All bold:"Content" is printed, and if no bold:"Content" is provided, an empty line is printed. + + The following escape sequences are supported for printing special characters\: + - character:"\f": Form Feed. + - character:"\n": New Line. + - character:"\r": Carriage Return. + - character:"\t": Tab. + - character:"\v": Vertical Tab. + - character:"\\": Backslash Character (may require additional slashes in certain circumstances.) + - character:"\0": NULL Character. + - character:"\U+": Unicode Sequence (followed by a valid Unicode sequence with a minimum 4 hexidecimal digits and a maximum of 6 hexidecimal digits). + - character:"\!": Non-printing separator, allowing for code:"\U+000A\!5" to be equivalent to code:"\n5". + + If the Unicode is invalid, then nothing is printed for that character (the invalid character is skipped when printing). + Example Unicodes\: + - code:"\U+000A": Prints a new line, equivalent to character:"\n". + - code:"\U+2E19": Prints the Unicode feather-like character character:"⸙". + + Only ASCII:"American Standard Code for Information Interchange" alpha-numeric hexidecimal digits are allowed in the Unicode sequence (upper or lower case). + + Invalid or unknown escape sequences are not printed. + + - code:"run"\: + Manually execute a remote program or script. + This program must be in the appropriate code:"PATH" environment or otherwise automatically detected when calling without a specific path to the program or script. + + The first bold:"Content" represents the program or script name. + All bold:"Content" after the first are passed to the program or script when running. + + After this executes the return result is made available via the code:"return" parameter variable name. + Any existing value associated with code:"return" gets replaced. + + - code:"shell"\: + Manually execute a remote program or script using a specific path to the program or script. + This does not require the program to exist in code:"PATH", but the path to the program or script must be relative to the project path. + + The first bold:"Content" represents the program or script name. + All bold:"Content" after the first are passed to the program or script when running. + + After this executes the return result is made available via the code:"return" parameter variable name. + Any existing value associated with code:"return" gets replaced. + + - code:"skeleton"\: + Run the fake skeleton operation as if code:"fake skeleton" was run instead of code:"fake make". + Command line arguments are automatically passed to the fake skeleton operation. + + - code:"to"\: + Change to the directory within the project root path tree, pushing the previous directory onto the path stack. + The previous path is saved onto the path stack and may later be code:"popped" off. + + The first bold:"Content" represents the path to change directory into. + + - code:"top"\: + Change to the project root path, clearing the directory path stack. + + This has no bold:"Content". + If the project root path no longer exists, then an error occurs. + + - code:"touch"\: + Manually create a new file or a directory within the project root or update its last changed timestamp if the file already exists. + + The first bold:"Content" must be either code:"file" or code:"directory". + The remaining bold:"Content" must be a path to the file. + + - code:"write"\: + Write strings to a file within the project root. + The bold:"Content" after the first bold:"Content" is appended to the file. + + The first bold:"Content" represents the file to write to. + If there is no bold:"Content" beyond the first, then the file is truncated (all content within the file is deleted). + + In all cases, if the file does not exist, the file is created. + + When only the first bold:"Content" exists, this acts similar to the code:"touch" operation. + The major difference between the two is that the code:"touch" operation does not alter the content within the file. + This does alter the content within the file. + + A single space is printed between each argument. + To preserve spaces, wrap the message in quotes (single or double). + + The following escape sequences are supported for printing special characters\: + - character:"\f": Form Feed. + - character:"\n": New Line. + - character:"\r": Carriage Return. + - character:"\t": Tab. + - character:"\v": Vertical Tab. + - character:"\\": Backslash Character (may require additional slashes in certain circumstances.) + - character:"\0": NULL Character. + - character:"\U+": Unicode Sequence (followed by a valid Unicode sequence with a minimum 4 hexidecimal digits and a maximum of 6 hexidecimal digits). + - character:"\!": Non-printing separator, allowing for code:"\U+000A\!5" to be equivalent to code:"\n5". + + If the Unicode is invalid, then nothing is printed for that character (the invalid character is skipped when printing). + Example Unicodes\: + - code:"\U+000A": Prints a new line, equivalent to character:"\n". + - code:"\U+2E19": Prints the Unicode feather-like character character:"⸙". + + Only ASCII:"American Standard Code for Information Interchange" alpha-numeric hexidecimal digits are allowed in the Unicode sequence (upper or lower case). + + Invalid or unknown escape sequences are not printed. + + The IKI vocabulary context is supported and is further clarified as follows\: + - code:"context"\: + The context Object represents a name representing simple context or complex combination of context. + Context should wrap some text such that if some text begins with some context, the context should be reset at the end. + The most basic context is color context, such as: code:"context:\"notice\" This is emphasized text context:\"reset\"". + + The use of IKI in this way is acceptable but it is not perfect. + IKI is not designed to be a replacement to markup. + The markup code:"Example" vs the IKI code:"context:\"notable\" Example context:\"notable\"" has obvious differences in the spaces. + The IKI by design cannot be used like this: code:"context:\"notable\"Examplecontext:\"notable\"" because the word code:"Example" and the word code:"context" collide. + + This context will respect the programs code:"++light", code:"++dark", and code:"++no_color" parameters. + + The following context are available\: + - code:"error": Designate as an error, often printed in red. + - code:"important": Designate as important. + - code:"normal": Explicitly designate normal text. + - code:"notable": Designate as notable (similar to code:"strong" or code:"bold" in HTML:"Hyper Text Markup Language"). + - code:"reset": Remove the context. + - code:"standout": Designate to make notable (similar to code:"italic" or code:"emphasis" in HTML:"Hyper Text Markup Language"). + - code:"success": Designate as a success, often printed in bright green. + - code:"title": Designate as a title. + - code:"warning": Designate as a warning, often printed in some shade of orange. + + - code:"define"\: + The define Object represents environment variables passed to the program or created by the program. + The value represents the environment variable name and is case-sensitive. + This IKI variable gets substituted with the environment variable's value or NULL if not defined. + The code:"settings" list supports declaring custom environment variables (which overwrite any existing environment variable with the same name). + + - code:"parameter"\: + The parameter Object represents a variable that is to be substituted. + The value represents the variable name and is case-sensitive. + This IKI variable gets substituted with the value defined in the code:"settings" list or NULL if not defined. + The value may contain an additional code:":option" or code:":value" at the end of the name to designate getting only part of the parameter. + + The following are reserved parameter variable names\: + - code:"build"\: + This variable holds the code:"build" program parameters, such as code:"-b build/". + This supports both code:":option" and code:":value". + + - code:"color"\: + This variable holds the color related program parameters, such as code:"+n". + This supports both code:":option" and code:":value" (value is always an empty string). + + - code:"data"\: + This variable holds the code:"data" program parameters, such as code:"-D data/". + This supports both code:":option" and code:":value". + + - code:"define"\: + This variable holds the code:"data" program parameters, such as code:"-d define/". + This supports both code:":option" and code:":value". + + - code:"fakefile"\: + This variable holds the code:"fakefile" program parameters, such as code:"-f fakefile". + This supports both code:":option" and code:":value". + + - code:"mode"\: + This variable holds the code:"fakefile" program parameters, such as code:"-m monolithic". + This supports both code:":option" and code:":value". + + - code:"process"\: + This variable holds the code:"process" program parameters, such as code:"-p process_name". + This supports both code:":option" and code:":value". + + - code:"return"\: + This variable holds the return status from a previously run user-space applications, which happens with the code:"run" and code:"shell" section operations. + This does not represent the return code for each line, just only those lines that run user-space applications. + + - code:"settings"\: + This variable holds the code:"settings" program parameters, such as code:"-s settings". + This supports both code:":option" and code:":value". + + - code:"sources"\: + This variable holds the code:"data" program parameters, such as code:"-S sources/". + This supports both code:":option" and code:":value". + + - code:"verbosity"\: + This variable holds the verbosity related program parameters, such as code:"+V". + This supports both code:":option" and code:":value" (value is always an empty string). + + - code:"work"\: + This variable holds the code:"work" program parameters, such as code:"-w work/". + This supports both code:":option" and code:":value". + + An example of getting just the code:":option" or code:":value" part of a parameter for the code:"work" parameters\: + - code:"work:option"\: + This variable holds the option part of the code:"work" program parameters, such as code:"-w". + + - code:"work:value"\: + This variable holds the value part of the code:"work" program parameters, such as code:"work/". + + The bold:"Content" code:"no_dereference" may be specified in certain cases relating to files. + These cases operate on a file that can be a link itself or the link target. + The default behavior is normally to dereference the link target. + + For example, consider a symbolic link, called code:"some_file", that points to a file that does not exist (which means that the link in question is a broken link). + The Operation code:"if exist some_file" would return false. + The Operation code:"if no_dereference exist some_file" would return true. + This is because the symbolic link itself, code:"some_file", does exist but the file it is pointing to does not. + The code:"no_dereference" is ignored for conditions that do not need it. diff --git a/documents/standards/fake/documents/settings.txt b/documents/standards/fake/documents/settings.txt new file mode 100644 index 0000000..b8818da --- /dev/null +++ b/documents/standards/fake/documents/settings.txt @@ -0,0 +1,573 @@ +# fss-0002 iki-0000 +# +# license: open-standard-license-1.0 +# +# This file (assumed to be named settings.txt) can be more easily read using the following iki_read commands: +# iki_read settings.txt +Q -w -rrr ASCII ASCII FLL FLL GCC GCC -WW character "'" "'" code '"' '"' +# +# To read the "Settings Documentation" section of this file, use this command sequence: +# fss_basic_list_read settings.txt +Q -cn "Settings Documentation" | iki_read +Q -w -rr ASCII ASCII FLL FLL -WW character "'" "'" code '"' '"' +# + +Settings Documentation: + This describes intent and purposes of the build bold:"settings" file bold:"settings". + The bold:"settings" file is designed for very simple compilations that represent a single named program and/or a single named library. + For specific details on the allowed formatting, see the file:"settings.txt" under the specifications folder. + + - code:"build_compiler"\: + This represents the name of the compiler program to use, such as code:"gcc". + + This defaults to code:"gcc" (the bold:"GNU C Compiler"). + + The programs code:"gcc" and code:"clang" are known to work. + Many of the parameters in the bold:"settings" file can be changed if not using GCC:"GNU Compiler Collection", but there may be certain hard-coded functionality that may need to be changed. + + - code:"build_indexer"\: + This represents the name of the indexer program to use, such as code:"ar". + An indexer is often called a linker. + + This defaults to code:"ar" (the GNU code:"ar" program). + Similar to code:"build_compiler", any linker that supports the code:"ar" program parameters is effectively supported. + + - code:"build_indexer_arguments"\: + This represents arguments needed to build an archive file from object files, such as code:"rcs". + These arguments are placed immediately before the object files passed to the code:"indexer" program. + + - code:"build_language"\: + The programming language to build with. + The languages code:"c" and code:"c++" are supported (with code:"bash" as a consideration for support). + The code:"bash" language is not currently implemented and needs some consideration because there is nothing to compile. + The code:"bash" language will likely build a set of individual scripts, and perhaps script dependencies, into a single Bash script. + + - code:"build_libraries"\: + A collection of libraries to be linked against. + This should include the compiler specific parameter parts, such as the code:"-l" prefix in code:"-lc". + The order of these may matter if the compiler (such as GCC:"GNU Compiler Collection" or a linker via GCC:"GNU Compiler Collection") is order sensitive. + + - code:"build_libraries_shared"\: + A collection of libraries to be linked against. + This should include the compiler specific parameter parts, such as the code:"-l" prefix in code:"-lc". + The order of these may matter if the compiler (such as GCC:"GNU Compiler Collection" or a linker via GCC:"GNU Compiler Collection") is order sensitive. + These are applied to only shared builds. + + - code:"build_libraries_static"\: + A collection of libraries to be linked against. + This should include the compiler specific parameter parts, such as the code:"-l" prefix in code:"-lc". + The order of these may matter if the compiler (such as GCC:"GNU Compiler Collection" or a linker via GCC:"GNU Compiler Collection") is order sensitive. + These are applied to only static builds. + + - code:"build_objects_library"\: + A collection of object files to be compile with when building libraries. + These are intended to represent already compiled object files. + These paths are relative to the code:"path_object_script", code:"path_object_shared", or code:"path_object_static". + The order of these may matter if the compiler (such as GCC:"GNU Compiler Collection" or a linker via GCC:"GNU Compiler Collection") is order sensitive. + + - code:"build_objects_library_shared"\: + A collection of object files to be compile with when building shared libraries. + These are intended to represent already compiled object files. + These paths are relative to the code:"path_object_shared". + The order of these may matter if the compiler (such as GCC:"GNU Compiler Collection" or a linker via GCC:"GNU Compiler Collection") is order sensitive. + These are applied to only shared builds. + + - code:"build_objects_library_static"\: + A collection of object files to be compile with when building static libraries. + These are intended to represent already compiled object files. + These paths are relative to the code:"path_object_static". + The order of these may matter if the compiler (such as GCC:"GNU Compiler Collection" or a linker via GCC:"GNU Compiler Collection") is order sensitive. + These are applied to only static builds. + + - code:"build_objects_program"\: + A collection of object files to be compile with when building programs. + These are intended to represent already compiled object files. + These paths are relative to the code:"path_object_script", code:"path_object_shared", or code:"path_object_static". + The order of these may matter if the compiler (such as GCC:"GNU Compiler Collection" or a linker via GCC:"GNU Compiler Collection") is order sensitive. + + - code:"build_objects_program_shared"\: + A collection of object files to be compile with when building shared programs. + These are intended to represent already compiled object files. + These paths are relative to the code:"path_object_shared". + The order of these may matter if the compiler (such as GCC:"GNU Compiler Collection" or a linker via GCC:"GNU Compiler Collection") is order sensitive. + These are applied to only shared builds. + + - code:"build_objects_program_static"\: + A collection of object files to be compile with when building static programs. + These are intended to represent already compiled object files. + These paths are relative to the code:"path_object_static". + The order of these may matter if the compiler (such as GCC:"GNU Compiler Collection" or a linker via GCC:"GNU Compiler Collection") is order sensitive. + These are applied to only static builds. + + - code:"build_name"\: + The name of the build, which often represent the project name. + If program sources are specified, then this will be used as the program name. + If library sources are specified, then this will be used in the library name, such as code:"libX.so" where code:"X" would be the code:"build_name" value. + + - code:"build_script"\: + When code:"yes", the build process will build any scripts, such as a Bash script. + + This is neither implemented nor supported by Featureless Make 0.6.x and earlier. + + - code:"build_shared"\: + When code:"yes", the build process will compile any source code for any supported language that supports shared library linking. + + - code:"build_sources_documentation"\: + A collection of documentation files. + These are documentation files used by the project and are simply copied over to the build directory. + Unless a pre-process script (or in theory post-process script) is configured to alter these, they are not modified. + + - code:"build_sources_headers"\: + A collection of header files. + May include a relative sub-path to each individual header (such as: code:"level_0/a.h level_0/b.h level_1/c.h"). + The order of these may matter if the compiler (such as GCC:"GNU Compiler Collection" or a linker via GCC:"GNU Compiler Collection") is order sensitive. + + - code:"build_sources_headers_shared"\: + A collection of header files. + May include a relative sub-path to each individual header (such as: code:"level_0/a.h level_0/b.h level_1/c.h"). + The order of these may matter if the compiler (such as GCC:"GNU Compiler Collection" or a linker via GCC:"GNU Compiler Collection") is order sensitive. + Be careful not to have any conflicting names between this and build_sources_headers_static in case of when static and shared builds are both enabled. + These are applied to only shared builds. + + - code:"build_sources_headers_static"\: + A collection of header files. + May include a relative sub-path to each individual header (such as: code:"level_0/a.h level_0/b.h level_1/c.h"). + The order of these may matter if the compiler (such as GCC:"GNU Compiler Collection" or a linker via GCC:"GNU Compiler Collection") is order sensitive. + These files are used when compiling the library. + Be careful not to have any conflicting names between this and build_sources_headers_shared in case of when static and shared builds are both enabled. + These are applied to only static builds. + + - code:"build_sources_library"\: + A collection of library related source files. + May include a relative sub-path to each individual source file (such as: code:"level_0/a.c level_0/b.c level_1/c.c"). + The order of these may matter if the compiler (such as GCC:"GNU Compiler Collection" or a linker via GCC:"GNU Compiler Collection") is order sensitive. + + - code:"build_sources_library_shared"\: + A collection of library related source files. + May include a relative sub-path to each individual source file (such as: code:"level_0/a.c level_0/b.c level_1/c.c"). + The order of these may matter if the compiler (such as GCC:"GNU Compiler Collection" or a linker via GCC:"GNU Compiler Collection") is order sensitive. + These are applied to only shared builds. + + - code:"build_sources_library_static"\: + A collection of library related source files. + May include a relative sub-path to each individual source file (such as: code:"level_0/a.c level_0/b.c level_1/c.c"). + The order of these may matter if the compiler (such as GCC:"GNU Compiler Collection" or a linker via GCC:"GNU Compiler Collection") is order sensitive. + These are applied to only static builds. + + - code:"build_sources_object"\: + A single source file used for generating an object file. + The source file is located within the path designated by code:"path_sources_object". + The built object does not get linked and therefore no linker arguments apply. + The built object file is named using the code:"build_name" with the code:".o" extension. + May include a relative sub-path to each individual source file (such as: code:"level_0/a.c"). + + - code:"build_sources_object_shared"\: + A single source file used for generating an object file. + The source file is located within the path designated by code:"path_sources_object". + The built object does not get linked and therefore no linker arguments apply. + The built object file is named using the code:"build_name" with the code:".o" extension. + May include a relative sub-path to each individual source file (such as: code:"level_0/a.c"). + These are applied to only shared builds. + + - code:"build_sources_object_static"\: + A single source file used for generating an object file. + The source file is located within the path designated by code:"path_sources_object". + The built object does not get linked and therefore no linker arguments apply. + The built object file is named using the code:"build_name" with the code:".o" extension. + May include a relative sub-path to each individual source file (such as: code:"level_0/a.c"). + These are applied to only static builds. + + - code:"build_sources_program"\: + A collection of program related source files. + May include a relative sub-path to each individual source file (such as: code:"level_0/a.c level_0/b.c level_1/c.c"). + The order of these may matter if the compiler (such as GCC:"GNU Compiler Collection" or a linker via GCC:"GNU Compiler Collection") is order sensitive. + These files are used when compiling the program. + + - code:"build_sources_program_shared"\: + A collection of program related source files. + May include a relative sub-path to each individual source file (such as: code:"level_0/a.c level_0/b.c level_1/c.c"). + The order of these may matter if the compiler (such as GCC:"GNU Compiler Collection" or a linker via GCC:"GNU Compiler Collection") is order sensitive. + These files are used when compiling the program for shared builds. + + - code:"build_sources_program_static"\: + A collection of program related source files. + May include a relative sub-path to each individual source file (such as: code:"level_0/a.c level_0/b.c level_1/c.c"). + The order of these may matter if the compiler (such as GCC:"GNU Compiler Collection" or a linker via GCC:"GNU Compiler Collection") is order sensitive. + These files are used when compiling the program for static builds. + + - code:"build_sources_script"\: + A collection of script files. + These are script files used by the project and are simply copied over to the build directory. + Unless a pre-process script (or in theory post-process script) is configured to alter these, they are not modified. + Unlike the code:"compile_language" setting code:"bash", this is not for built Bash script, but is instead for any valid scripting language (including Bash). + These could be in any language. + + - code:"build_sources_setting"\: + A collection of settings files. + These are settings files used by the project and are simply copied over to the build directory. + Unless a pre-process script (or in theory post-process script) is configured to alter these, they are not modified. + + - code:"build_static"\: + When code:"yes", the build process will compile any source code for any supported language that supports static library linking. + + - code:"defines"\: + A collection of macro names. + This includes the any compiler specific parameters required by the code:"build_compiler", such as the code:"-D" used by code:"gcc" and code:"clang". + These will be appended to the compiler for compiled languages such as code:"C" and code:"C++". + These are applied to both shared and static builds. + + - code:"defines_library"\: + A collection of macro names. + This includes the any compiler specific parameters required by the code:"build_compiler", such as the code:"-D" used by code:"gcc" and code:"clang". + These will be appended to the compiler for compiled languages such as code:"C" and code:"C++". + These are applied to only library builds. + + - code:"defines_library_shared"\: + A collection of macro names. + This includes the any compiler specific parameters required by the code:"build_compiler", such as the code:"-D" used by code:"gcc" and code:"clang". + These will be appended to the compiler for compiled languages such as code:"C" and code:"C++". + These are applied to only shared library builds. + + - code:"defines_library_static"\: + A collection of macro names. + This includes the any compiler specific parameters required by the code:"build_compiler", such as the code:"-D" used by code:"gcc" and code:"clang". + These will be appended to the compiler for compiled languages such as code:"C" and code:"C++". + These are applied to only static library builds. + + - code:"defines_object"\: + A collection of macro names. + This includes the any compiler specific parameters required by the code:"build_compiler", such as the code:"-D" used by code:"gcc" and code:"clang". + These will be appended to the compiler for compiled languages such as code:"C" and code:"C++". + These are applied to only object builds. + + - code:"defines_object_shared"\: + A collection of macro names. + This includes the any compiler specific parameters required by the code:"build_compiler", such as the code:"-D" used by code:"gcc" and code:"clang". + These will be appended to the compiler for compiled languages such as code:"C" and code:"C++". + These are applied to only shared object builds. + + - code:"defines_object_static"\: + A collection of macro names. + This includes the any compiler specific parameters required by the code:"build_compiler", such as the code:"-D" used by code:"gcc" and code:"clang". + These will be appended to the compiler for compiled languages such as code:"C" and code:"C++". + These are applied to only static object builds. + + - code:"defines_program"\: + A collection of macro names. + This includes the any compiler specific parameters required by the code:"build_compiler", such as the code:"-D" used by code:"gcc" and code:"clang". + These will be appended to the compiler for compiled languages such as code:"C" and code:"C++". + These are applied to only program builds. + + - code:"defines_program_shared"\: + A collection of macro names. + This includes the any compiler specific parameters required by the code:"build_compiler", such as the code:"-D" used by code:"gcc" and code:"clang". + These will be appended to the compiler for compiled languages such as code:"C" and code:"C++". + These are applied to only shared program builds. + + - code:"defines_program_static"\: + A collection of macro names. + This includes the any compiler specific parameters required by the code:"build_compiler", such as the code:"-D" used by code:"gcc" and code:"clang". + These will be appended to the compiler for compiled languages such as code:"C" and code:"C++". + These are applied to only shared program builds. + + - code:"defines_shared"\: + A collection of macro names. + This includes the any compiler specific parameters required by the code:"build_compiler", such as the code:"-D" used by code:"gcc" and code:"clang". + These will be appended to the compiler for compiled languages such as code:"C" and code:"C++". + These are applied to only shared builds. + + - code:"defines_static"\: + A collection of macro names. + This includes the any compiler specific parameters required by the code:"build_compiler", such as the code:"-D" used by code:"gcc" and code:"clang". + These will be appended to the compiler for compiled languages such as code:"C" and code:"C++". + These are applied to only static builds. + + - code:"environment"\: + A collection of environment names to pass from the callers environment into the executed programs environment. + When provided, all environment variables are removed when calling user-space programs, such as code:"gcc". + To remove all environment variables define this with no bold:"Content". + When not provided, all environment variables are loaded. + + - code:"flags"\: + A collection of any flag supported by the code:"build_compiler", such as code:"gcc". + This includes the any compiler specific parameters to defined this, such as the code:"-f" used by code:"gcc" and code:"clang". + These are applied to both shared and static builds. + + - code:"flags_library"\: + A collection of any flag supported by the code:"build_compiler", such as code:"gcc". + This includes the any compiler specific parameters to defined this, such as the code:"-f" used by code:"gcc" and code:"clang". + These are applied when building a library. + + - code:"flags_library_shared"\: + A collection of any flag supported by the code:"build_compiler", such as code:"gcc". + This includes the any compiler specific parameters to defined this, such as the code:"-f" used by code:"gcc" and code:"clang". + These are applied to only library shared builds. + + - code:"flags_library_static"\: + A collection of any flag supported by the code:"build_compiler", such as code:"gcc". + This includes the any compiler specific parameters to defined this, such as the code:"-f" used by code:"gcc" and code:"clang". + These are applied to only library static builds. + + - code:"flags_object"\: + A collection of any flag supported by the code:"build_compiler", such as code:"gcc". + This includes the any compiler specific parameters to defined this, such as the code:"-f" used by code:"gcc" and code:"clang". + These are applied when building an object. + + - code:"flags_object_shared"\: + A collection of any flag supported by the code:"build_compiler", such as code:"gcc". + This includes the any compiler specific parameters to defined this, such as the code:"-f" used by code:"gcc" and code:"clang". + These are applied to only object shared builds. + + - code:"flags_object_static"\: + A collection of any flag supported by the code:"build_compiler", such as code:"gcc". + This includes the any compiler specific parameters to defined this, such as the code:"-f" used by code:"gcc" and code:"clang". + These are applied to only object static builds. + + - code:"flags_program"\: + A collection of any flag supported by the code:"build_compiler", such as code:"gcc". + This includes the any compiler specific parameters to defined this, such as the code:"-f" used by code:"gcc" and code:"clang". + These are applied when building a program. + + - code:"flags_program_shared"\: + A collection of any flag supported by the code:"build_compiler", such as code:"gcc". + This includes the any compiler specific parameters to defined this, such as the code:"-f" used by code:"gcc" and code:"clang". + These are applied to only program shared builds. + + - code:"flags_program_static"\: + A collection of any flag supported by the code:"build_compiler", such as code:"gcc". + This includes the any compiler specific parameters to defined this, such as the code:"-f" used by code:"gcc" and code:"clang". + These are applied to only program static builds. + + - code:"flags_shared"\: + A collection of any flag supported by the code:"build_compiler", such as code:"gcc". + This includes the any compiler specific parameters to defined this, such as the code:"-f" used by code:"gcc" and code:"clang". + These are applied to only shared builds. + + - code:"flags_static"\: + A collection of any flag supported by the code:"build_compiler", such as code:"gcc". + This includes the any compiler specific parameters to defined this, such as the code:"-f" used by code:"gcc" and code:"clang". + These are applied to only static builds. + + - code:"has_path_standard"\: + When code:"yes", the sources path will be built using the sources path with the language, such as code:"sources/c/". + When code:"no", the default sources path structure is not used and instead code:"path_sources" is used. + When the parameter code:"-S/--sources" is specified, such as code:"-S xxx", then when this is set to code:"yes" is used then the path would be code:"xxx/c/" and when this is set to code:"no" then the path would be code:"xxx/". + + This defaults to code:"yes". + + - code:"import"\: + Load this bold:"settings" file at this point in the bold:"settings" file. + This can be an absolute or a relative path. + This is intended to reduce repition and likely should be placed at the top of the bold:"settings" file. + This a non-recursive operation and the imported file itself cannot perform an import. + Loaded values are processed as if they are in the file at the spot where the import setting is specified. + Relative paths are relative to the importing file. + Absolute paths that start with "./" are relative to the project root rather than the importing file. + Absolute paths that start with "/" are treated normally. + + This is neither implemented nor supported by Featureless Make 0.6.x and earlier. + + - code:"modes"\: + A collection of available build modes. + Build modes provide custom variants of the build process where certain bold:"settings" are appended onto others. + See the file:"settings.txt" specification for a list of which setting names this applies to. + + - code:"modes_default"\: + The name of the default mode to use when no mode is specified. + This must be one of the modes specified in the code:"modes" setting. + + - code:"path_headers"\: + A sub-path in which headers are to be installed under. + For example, the FLL:"Featureless Linux Library" project might use the code:"level_0", code:"level_1", etc.. headers without requiring that structure within the source. + A resulting build destination for a code:"path_headers" of code:"level_0" would be something like code:"build/includes/level_0/". + If code:"path_headers" is code:"level_0", code:"preserve_path_headers" is code:"yes", and code:"build_sources_headers" has code:"xxx/a.h yyy/zzz/b.h", then the headers would be at: code:"build/includes/level_0/xxx/a.h build/includes/level_0/yyy/zzz/b.h" + + - code:"path_language"\: + A sub-path in which to find the source files for the currently defined language. + If the code:"build_language" is changed, it is recommended to change this as well to match. + + - code:"path_library_script"\: + A sub-path representing the destination where the built library script files are placed. + + This defaults to code:"script". + + This is neither implemented nor supported by Featureless Make 0.6.x and earlier. + + - code:"path_library_shared"\: + A sub-path representing the destination where the built shared library files are placed. + + This defaults to code:"shared". + + - code:"path_library_static"\: + A sub-path representing the destination where the built shared library files are placed. + + This defaults to code:"static". + + - code:"path_object_script"\: + A sub-path representing the destination where the built object script files are placed. + + This defaults to code:"script". + + This is neither implemented nor supported by Featureless Make 0.6.x and earlier. + + - code:"path_object_shared"\: + A sub-path representing the destination where the built object library files are placed. + + This defaults to code:"shared". + + - code:"path_object_static"\: + A sub-path representing the destination where the built object library files are placed. + + This defaults to code:"static". + + - code:"path_program_script"\: + A sub-path representing the destination where the built program script files are placed. + + This defaults to code:"script". + + This is neither implemented nor supported by Featureless Make 0.6.x and earlier. + + - code:"path_program_shared"\: + A sub-path representing the destination where the built shared program files are placed. + + This defaults to code:"shared". + + - code:"path_program_static"\: + A sub-path representing the destination where built shared program files are placed. + + This defaults to code:"static". + + - code:"path_sources"\: + A sub-path representing where the source files are found. + + This defaults to code:"sources". + + - code:"path_sources_object"\: + A sub-path representing where the object source files are found. + This is used by code:"build_sources_object". + + This defaults to code:"sources". + + - code:"preserve_path_headers"\: + When this is code:"yes", then the relative directory structure in the source (as defined in code:"build_sources_headers") is preserved. + If the code:"build_sources_headers" has the header files code:"xxx/a.h yyy/zzz/b.h" and this is code:"yes", then the directories code:"xxx/" and code:"yyy/zzz/" are created and the files are stored within them. + If the code:"build_sources_headers" has the header files code:"xxx/a.h yyy/zzz/b.h" and this is code:"no", then the directories code:"xxx/" and code:"yyy/zzz/" are stripped before installing. + When this is code:"no" and the code:"build_sources_headers" has header files code:"xxx/a.h yyy/a.h", then one of the code:"a.h" files will be overwritten, depending on order they were supplied. + + - code:"process_post"\: + The filename (relative to the file:"data/build/" directory) of a script to execute after the code:"build" operation successfully completes. + A small subset of parameters from the main execution are passed to this script during execution as parameters (using short parameter codes)\: + Color context parameters, such as: code:"+l", code:"+n", and code:"+d". + Operation mode, such as: code:"build", code:"clean", code:"make", or code:"skeleton". + Verbosity parameters, such as: code:"+q", code:"+D", or code:"+V". + Define parameters, such as code:"-d X" or code:"-d Y", whereas code:"X" or code:"Y" are any valid argument associated with code:"-d". + Process parameter, such as code:"-p X", whereas code:"X" is any valid argument associated with code:"-p". + Settings parameter, such as code:"-s X', whereas code:"X" is any valid argument associated with code:"-s". + Build Path parameter, such as code:"-b X', whereas code:"X" is any valid argument associated with code:"-b". + Data Path parameter, such as code:"-D X', whereas code:"X" is any valid argument associated with code:"-D". + Sources Path parameter, such as code:"-S X', whereas code:"X" is any valid argument associated with code:"-S". + Work Path parameter, such as code:"-w X', whereas code:"X" is any valid argument associated with code:"-w". + + - code:"process_pre"\: + The filename (relative to the file:"data/build/" directory) of a script to execute before the code:"build" operation is executed. + A small subset of parameters from the main execution are passed to this script during execution as parameters (using short parameter codes)\: + Color context parameters, such as: code:"+l", code:"+n", and code:"+d". + Operation mode, such as: code:"build", code:"clean", code:"make", or code:"skeleton". + Verbosity parameters, such as: code:"+q", code:"+D", or code:"+V". + Define parameters, such as code:"-d X" or code:"-d Y", whereas code:"X" or code:"Y" are any valid argument associated with code:"-d". + Process parameter, such as code:"-p X", whereas code:"X" is any valid argument associated with code:"-p". + Settings parameter, such as code:"-s X', whereas code:"X" is any valid argument associated with code:"-s". + Build Path parameter, such as code:"-b X', whereas code:"X" is any valid argument associated with code:"-b". + Data Path parameter, such as code:"-D X', whereas code:"X" is any valid argument associated with code:"-D". + Sources Path parameter, such as code:"-S X', whereas code:"X" is any valid argument associated with code:"-S". + Work Path parameter, such as code:"-w X', whereas code:"X" is any valid argument associated with code:"-w". + + - code:"search_exclusive"\: + When code:"yes", the search path during compile for shared libraries will only include shared library paths. + When code:"no", the search path during compile time for shared libraries will include shared library paths followed by static library paths. + Setting this to code:"yes" helps prevent static libraries from ending up in shared libraries (very useful when bootstrapping a system). + Setting this to code:"no" allows for including static libraries if no shared libraries are found but static are. + This does not alter search paths introduced automatically by the code:"build_compiler" or code:"build_indexer", so it is still possible for static libraries to end up even when this is set to code:"yes". + + - code:"search_shared"\: + When code:"yes", shared library paths are searched during compile. + Both this and code:"search_static" cannot be code:"no" at the same time. + + This defaults to code:"yes". + + - code:"search_shared"\: + When code:"yes", static library paths are searched during compile. + Both this and search_shared cannot be code:"no" at the same time. + + - code:"version_file"\: + Designates which version should be used when building the symbolic links. + Any version prefixes are used as defined. + A Symbolic link is created against this created file such that code:"libX.so" is a link to code:"libX.so.A". + For all files other than when file is code:"major", another symbolic link is created against this such that code:"libX.so.A" is a link to code:"libX.so.A.X" such that X is the respective code:"B", code:"B.C', or code:"B.C.D" as described below. + The default file is code:"major". + When code:"major" is used, the file created is code:"libX.so.A", whereas code:"X" is the code:"build_name" and code:"A" is the major version. + When code:"minor" is used, the file created is code:"libX.so.A.B", whereas code:"X" is the code:"build_name" and code:"A.B" is the major and minor versions, respectively. + When code:"micro" is used, the file created is code:"libX.so.A.B.C", whereas code:"X" is the code:"build_name" and code:"A.B.C" is the major, minor, and micro versions, respectively. + When code:"nano" is used, the file created is code:"libX.so.A.B.C.D", whereas code:"X" is the code:"build_name" and code:"A.B.C.D" is the major, minor, micro, and nano versions, respectively. + + - code:"version_major"\: + The major version number (or in theory any characters allowed in a filename). + This should generally be a positive number or 0. + Anything else is currently untested but allowed. + With a structure of code:"A.B.C", the major version would be the character:"A". + + - code:"version_major_prefix"\: + The version major prefix is the character used to designate the start of the major version. + This can zero or more characters. + With a structure of code:"A.B.C", the major version prefix would be before the character:"A". + This is only added if code:"version_major" is not empty. + + This defaults to the ASCII:"American Standard Code for Information Interchange" period character character:".". + + - code:"version_minor"\: + The minor version number (or in theory any characters allowed in a filename). + This should generally be a positive number or 0. + Anything else is currently untested but allowed. + With a structure of code:"A.B.C", the minor version would be the character:"B". + + - code:"version_minor_prefix"\: + The version minor prefix is the character used to separate the major from the minor. + This can zero or more characters. + With a structure of code:"A.B.C", the minor version prefix would be the character:"." before the character:"B". + This is only added if code:"version_minor" is not empty. + + This defaults to the ASCII:"American Standard Code for Information Interchange" period character character:".". + + - code:"version_micro"\: + The micro version number (or in theory any characters allowed in a filename). + This should generally be a positive number or 0. + Anything else is currently untested but allowed. + With a structure of code:"A.B.C", the micro version would be the character:"C". + + - code:"version_micro_prefix"\: + The version micro prefix is the character used to separate the minor from the micro. + This can zero or more characters. + With a structure of code:"A.B.C", the micro version prefix would be the character:"." before the character:"C". + This is only added if code:"version_micro" is not empty. + + This defaults to the ASCII:"American Standard Code for Information Interchange" period character character:".". + + - code:"version_nano"\: + The nano version number (or in theory any characters allowed in a filename). + This should generally be a positive number or 0. + Anything else is currently untested but allowed. + With a structure of code:"A.B.C.D", the micro version prefix would be the character:"." before the character:"D". + + - code:"version_nano_prefix"\: + The version nano prefix is the character used to separate the micro from the nano. + This can zero or more characters. + With a structure of code:"A.B.C.D", the minor version would be the character:"." before the character:"D". + This is only added if code:"version_nano" is not empty. + + This defaults to the ASCII:"American Standard Code for Information Interchange" period character character:".". + + - code:"version_target"\: + Designates which version should be used when linking the shared library. + Any version prefixes are used as defined. + The default target is code:"micro". + When code:"major" is used, a shared library is generated with code:"-Wl,-soname,libX.so.A", whereas code:"X" is the code:"build_name" and code:"A" is the major version. + When code:"minor" is used, a shared library is generated with code:"-Wl,-soname,libX.so.A.B", whereas code:"X" is the code:"build_name" and code:"A.B" is the major and minor versions, respectively. + When code:"micro" is used, a shared library is generated with code:"-Wl,-soname,libX.so.A.B.C", whereas code:"X" is the code:"build_name" and code:"A.B.C" is the major, minor, and micro versions, respectively. + When code:"nano" is used, a shared library is generated with code:"-Wl,-soname,libX.so.A.B.C.D", whereas code:"X" is the code:"build_name" and code:"A.B.C.D" is the major, minor, micro, and nano versions, respectively. diff --git a/documents/standards/fake/defines.txt b/documents/standards/fake/specifications/defines.txt similarity index 100% rename from documents/standards/fake/defines.txt rename to documents/standards/fake/specifications/defines.txt diff --git a/documents/standards/fake/dependencies.txt b/documents/standards/fake/specifications/dependencies.txt similarity index 94% rename from documents/standards/fake/dependencies.txt rename to documents/standards/fake/specifications/dependencies.txt index 19f9f05..ad4266f 100644 --- a/documents/standards/fake/dependencies.txt +++ b/documents/standards/fake/specifications/dependencies.txt @@ -10,7 +10,7 @@ # Dependencies Specification: - The build settings bold:"dependencies" file follows the code:"FSS-0001 (Extended)" format. + The build settings file:"dependencies" file follows the code:"FSS-0001 (Extended)" format. Each Object represents a specific project name as it would be linked against. Each Content represents associated information, such as a version number. diff --git a/documents/standards/fake/fakefile.txt b/documents/standards/fake/specifications/fakefile.txt similarity index 99% rename from documents/standards/fake/fakefile.txt rename to documents/standards/fake/specifications/fakefile.txt index 6cb340e..a6b2f0c 100644 --- a/documents/standards/fake/fakefile.txt +++ b/documents/standards/fake/specifications/fakefile.txt @@ -13,7 +13,7 @@ Fakefile Specification: The file:"fakefile" file follows the code:"FSS-0005 (Somewhat Basic List)" format with a sub-format of code:"IKI-0002 (Simple Script)". A file:"fakefile" is broken up into multiple bold:"Basic Lists", referred to as bold:"Sections", with two special purpose reserved bold:"Sections". - The bold:"Sections" are broken up into multiple bold:"Extended Objects" and their respective bold:"Contents", referred to as bold"Section Operations". + The bold:"Sections" are broken up into multiple bold:"Extended Objects" and their respective bold:"Contents", referred to as bold:"Section Operations". Each of these non-reserved Sections acts as a set to perform some set of bold:"Section Operations". Each of these bold:"Section Operations" perform a single command or action based on a set of reserved bold:"Section Operation" types. diff --git a/documents/standards/fake/settings.txt b/documents/standards/fake/specifications/settings.txt similarity index 99% rename from documents/standards/fake/settings.txt rename to documents/standards/fake/specifications/settings.txt index b6969e7..5afe3e9 100644 --- a/documents/standards/fake/settings.txt +++ b/documents/standards/fake/specifications/settings.txt @@ -35,6 +35,7 @@ Settings Specification: - code:"build_objects_program_static": Must only contain any number of valid object file names relative to the code:"path_object_static" path. - code:"build_script": Must only one of: code:"yes" or code:"no". - code:"build_shared": Must only one of: code:"yes" or code:"no". + - code:"build_sources_documentation": Must only contain any number of valid filenames. - code:"build_sources_headers": Must only contain any number of valid filenames. - code:"build_sources_headers_shared": Must only contain any number of valid filenames. - code:"build_sources_headers_static": Must only contain any number of valid filenames. diff --git a/documents/standards/fll/fss-0000.txt b/documents/standards/fll/specifications/fss-0000.txt similarity index 100% rename from documents/standards/fll/fss-0000.txt rename to documents/standards/fll/specifications/fss-0000.txt diff --git a/documents/standards/fll/fss-0001.txt b/documents/standards/fll/specifications/fss-0001.txt similarity index 100% rename from documents/standards/fll/fss-0001.txt rename to documents/standards/fll/specifications/fss-0001.txt diff --git a/documents/standards/fll/fss-0002.txt b/documents/standards/fll/specifications/fss-0002.txt similarity index 96% rename from documents/standards/fll/fss-0002.txt rename to documents/standards/fll/specifications/fss-0002.txt index 550e9f5..fbbca1a 100644 --- a/documents/standards/fll/fss-0002.txt +++ b/documents/standards/fll/specifications/fss-0002.txt @@ -18,7 +18,7 @@ Featureless Settings Specification: 0002 - Basic List: Any Content that could be interpreted as a valid Object must have the colon delimited. There is no single-quote, double-quote, or backtick delimitation in this specification. - Only the colon that would result in a valid Object can be delimited. + Only a colon character:":" (unicode:"U+003A") that would result in a valid Object can be delimited. Empty Objects are allowed, that is, the length of the object may be zero. diff --git a/documents/standards/fll/fss-0003.txt b/documents/standards/fll/specifications/fss-0003.txt similarity index 72% rename from documents/standards/fll/fss-0003.txt rename to documents/standards/fll/specifications/fss-0003.txt index f8a436c..f48c26d 100644 --- a/documents/standards/fll/fss-0003.txt +++ b/documents/standards/fll/specifications/fss-0003.txt @@ -13,20 +13,20 @@ Featureless Settings Specification: 0003 - Extended List: Each Object starts at the beginning of a line and white space to the left of the Object is not treated as an object. An open-brace character:"{" (unicode:"U+007B") followed by any white space until a newline terminates a possible valid Object. An Object is not considered fully valid until a valid close-brace character:"}" (unicode:"U+007D") is found, designating the end of the Content. - Non-white space printable characters may not follow the open-brace of a valid Object. + Non-white space printable characters may not follow the open-brace character:"{" (unicode:"U+007B") of a valid Object. - Content is represented as a single Content column of every line following a valid object until the end of file (or string) or until a non-delimited close-brace character:"}". + Content is represented as a single Content column of every line following a valid object until the end of file (or string) or until a non-delimited close-brace character:"}" (unicode:"U+007D"). Any Content column that could be interpreted as an end of Content must be delimited if it should be part of the Content. - White space may follow a valid close-brace but a terminating newline must be present to designate a valid end of Content. + White space may follow a valid close-brace character:"}" (unicode:"U+007D") but a terminating newline must be present to designate a valid end of Content. There is no single-quote, double-quote, or backtick delimitation in this specification. - Only the open-brace that would result in a valid Object or the close-brace that would terminate valid Content can be delimited. - When inside potentially valid Content (which follows a valid Object) the open-brace cannot be delimited because this standard is not-recursive. + Only an open-brace character:"{" (unicode:"U+007B") that would result in a valid Object or the close-brace character:"}" (unicode:"U+007D") that would terminate valid Content can be delimited. + When inside potentially valid Content (which follows a valid Object) the open-brace character:"{" (unicode:"U+007B") cannot be delimited because this standard is not-recursive. When not inside any potentially valid Content (that is, there is no previous unclosed Object), then the Object may be delimited. - Likewise, the close-brace may only be delimited if it is within any potentially valid Content. + Likewise, the close-brace character:"}" (unicode:"U+007D") may only be delimited if it is within any potentially valid Content. - Each delimit slash in a delimitable open-brace is treated as a potential delimit such that two slashes represents a single delimited slash (code:"\\{" would represent code:"\{"). - Only the first delimit slash in a delimitable close-brace is treated as a potential delimit (code:"\\\}" would represent code:"\\}"). + Each delimit slash in a delimitable open-brace character:"{" (unicode:"U+007B") is treated as a potential delimit such that two slashes represents a single delimited slash (code:"\\{" would represent code:"\{"). + Only the first delimit slash in a delimitable close-brace character:"}" (unicode:"U+007D") is treated as a potential delimit (code:"\\\}" would represent code:"\\}"). Empty Objects are allowed, that is, the length of the object may be zero. diff --git a/documents/standards/fll/fss-0004.txt b/documents/standards/fll/specifications/fss-0004.txt similarity index 100% rename from documents/standards/fll/fss-0004.txt rename to documents/standards/fll/specifications/fss-0004.txt diff --git a/documents/standards/fll/fss-0005.txt b/documents/standards/fll/specifications/fss-0005.txt similarity index 100% rename from documents/standards/fll/fss-0005.txt rename to documents/standards/fll/specifications/fss-0005.txt diff --git a/documents/standards/fll/fss-0006.txt b/documents/standards/fll/specifications/fss-0006.txt similarity index 100% rename from documents/standards/fll/fss-0006.txt rename to documents/standards/fll/specifications/fss-0006.txt diff --git a/documents/standards/fll/fss-0007.txt b/documents/standards/fll/specifications/fss-0007.txt similarity index 100% rename from documents/standards/fll/fss-0007.txt rename to documents/standards/fll/specifications/fss-0007.txt diff --git a/documents/standards/fll/fss-0008.txt b/documents/standards/fll/specifications/fss-0008.txt similarity index 100% rename from documents/standards/fll/fss-0008.txt rename to documents/standards/fll/specifications/fss-0008.txt diff --git a/documents/standards/fll/fss-0009.txt b/documents/standards/fll/specifications/fss-0009.txt similarity index 100% rename from documents/standards/fll/fss-0009.txt rename to documents/standards/fll/specifications/fss-0009.txt diff --git a/documents/standards/fll/fss-000a.txt b/documents/standards/fll/specifications/fss-000a.txt similarity index 100% rename from documents/standards/fll/fss-000a.txt rename to documents/standards/fll/specifications/fss-000a.txt diff --git a/documents/standards/fll/fss-000b.txt b/documents/standards/fll/specifications/fss-000b.txt similarity index 100% rename from documents/standards/fll/fss-000b.txt rename to documents/standards/fll/specifications/fss-000b.txt diff --git a/documents/standards/fll/fss-000c.txt b/documents/standards/fll/specifications/fss-000c.txt similarity index 100% rename from documents/standards/fll/fss-000c.txt rename to documents/standards/fll/specifications/fss-000c.txt diff --git a/documents/standards/fll/fss-000d.txt b/documents/standards/fll/specifications/fss-000d.txt similarity index 100% rename from documents/standards/fll/fss-000d.txt rename to documents/standards/fll/specifications/fss-000d.txt diff --git a/documents/standards/fll/fss-000e.txt b/documents/standards/fll/specifications/fss-000e.txt similarity index 100% rename from documents/standards/fll/fss-000e.txt rename to documents/standards/fll/specifications/fss-000e.txt diff --git a/documents/standards/fll/fss-000f.txt b/documents/standards/fll/specifications/fss-000f.txt similarity index 100% rename from documents/standards/fll/fss-000f.txt rename to documents/standards/fll/specifications/fss-000f.txt diff --git a/documents/standards/fll/fss.txt b/documents/standards/fll/specifications/fss.txt similarity index 100% rename from documents/standards/fll/fss.txt rename to documents/standards/fll/specifications/fss.txt diff --git a/documents/standards/fll/iki-0000.txt b/documents/standards/fll/specifications/iki-0000.txt similarity index 100% rename from documents/standards/fll/iki-0000.txt rename to documents/standards/fll/specifications/iki-0000.txt diff --git a/documents/standards/fll/iki-0001.txt b/documents/standards/fll/specifications/iki-0001.txt similarity index 100% rename from documents/standards/fll/iki-0001.txt rename to documents/standards/fll/specifications/iki-0001.txt diff --git a/documents/standards/fll/iki-0002.txt b/documents/standards/fll/specifications/iki-0002.txt similarity index 100% rename from documents/standards/fll/iki-0002.txt rename to documents/standards/fll/specifications/iki-0002.txt diff --git a/documents/standards/fll/iki.txt b/documents/standards/fll/specifications/iki.txt similarity index 100% rename from documents/standards/fll/iki.txt rename to documents/standards/fll/specifications/iki.txt diff --git a/documents/standards/fll/time.txt b/documents/standards/fll/specifications/time.txt similarity index 100% rename from documents/standards/fll/time.txt rename to documents/standards/fll/specifications/time.txt -- 1.8.3.1