--- /dev/null
+# 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.
--- /dev/null
+# 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.
--- /dev/null
+# 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.
--- /dev/null
+# 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.
--- /dev/null
+# 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".
--- /dev/null
+# 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.
--- /dev/null
+# 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.
+++ /dev/null
-# 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.
+++ /dev/null
-# 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.
+++ /dev/null
-# 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".
+++ /dev/null
-# 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.
--- /dev/null
+# 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.
--- /dev/null
+# 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.
--- /dev/null
+# 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".
--- /dev/null
+# 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.
--- /dev/null
+# 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:
+++ /dev/null
-# 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:
--- /dev/null
+# 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:"<strong>Example</strong>" 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.
--- /dev/null
+# 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.
#
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.
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.
- 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.
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.
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.
projects / kevux.org-website / commitdiff