From f84821f117e187e4d906680d3d7f40d048e92213 Mon Sep 17 00:00:00 2001 From: Kevin Day Date: Sat, 10 Aug 2024 16:10:20 -0500 Subject: [PATCH] Update: Documentation and specifications. Update the raw documentation and specifications with a recent copy. This updates some pages, such as adding the "stage" to the fakefile and settings file. --- documentation/fake/specifications/fakefile.html | 22 +- documentation/fake/specifications/settings.html | 16 + .../standards/controller/documents/actions.txt | 1 + documents/standards/controller/documents/entry.txt | 5 +- documents/standards/controller/documents/exit.txt | 5 +- .../standards/controller/documents/packet.txt | 1 + .../controller/documents/readme.build.txt | 335 +++++++++++++++++++++ .../standards/controller/documents/readme.txt | 28 ++ documents/standards/controller/documents/rule.txt | 1 + .../standards/controller/documents/simulate.txt | 1 + .../standards/controller/specifications/entry.txt | 1 + .../standards/controller/specifications/exit.txt | 1 + .../standards/controller/specifications/packet.txt | 1 + .../standards/controller/specifications/rule.txt | 1 + .../standards/controller/specifications/task.txt | 1 + documents/standards/fake/documents/fakefile.txt | 25 +- documents/standards/fake/documents/settings.txt | 17 +- .../standards/fake/specifications/dependencies.txt | 2 +- .../standards/fake/specifications/fakefile.txt | 11 +- .../standards/fake/specifications/settings.txt | 21 +- .../standards/fll/specifications/fss-0004.txt | 2 +- .../standards/fll/specifications/fss-0005.txt | 2 +- .../standards/fll/specifications/fss-0006.txt | 2 +- .../standards/fll/specifications/fss-0007.txt | 2 +- .../standards/fll/specifications/fss-0008.txt | 2 +- .../standards/fll/specifications/fss-000b.txt | 2 +- .../standards/fll/specifications/fss-000c.txt | 2 +- .../standards/fll/specifications/fss-000d.txt | 2 +- .../standards/fll/specifications/fss-000f.txt | 2 +- .../standards/fll/specifications/fss-0010.txt | 2 +- .../standards/fll/specifications/iki-0000.txt | 2 +- .../standards/fll/specifications/iki-0001.txt | 2 +- .../standards/fll/specifications/iki-0002.txt | 2 +- documents/standards/fll/specifications/iki.txt | 8 +- documents/standards/fll/specifications/time.txt | 2 +- 35 files changed, 478 insertions(+), 54 deletions(-) create mode 100644 documents/standards/controller/documents/readme.build.txt create mode 100644 documents/standards/controller/documents/readme.txt diff --git a/documentation/fake/specifications/fakefile.html b/documentation/fake/specifications/fakefile.html index d35143b..2d81d5e 100644 --- a/documentation/fake/specifications/fakefile.html +++ b/documentation/fake/specifications/fakefile.html @@ -156,13 +156,14 @@

The build settings may also be specified in the Settings Section. @@ -438,6 +439,23 @@ +

  • +
    stage:
    + +
  • main:
    diff --git a/documentation/fake/specifications/settings.html b/documentation/fake/specifications/settings.html index 608e996..8c27e6f 100644 --- a/documentation/fake/specifications/settings.html +++ b/documentation/fake/specifications/settings.html @@ -199,6 +199,7 @@
  • search_exclusive: Must only one of: yes or no.
  • search_shared: Must only one of: yes or no.
  • search_static: Must only one of: yes or no.
    • +
  • stage: Only zero or one Content, which represents the build stage name (case-sensitive) (no slashes allowed).
  • version_file: Must only be one of: major, minor, micro, or nano.
  • version_major: Must only be a single value containing valid filename characters.
  • version_major_prefix: Must be zero or more valid filename characters.
    • @@ -1299,6 +1300,21 @@

  • +
    stage:
    +

    + This defines a name that is added to the build stage files to help uniquely identify build stages associated with this file. +

    +

    + This name must only have valid characters for a particular file system. +

    +

    + The variables allowed are different from file system to file system and so special characters should generally be avoided. +

    +

    + To help prevent problems with paths, slashes (forward slash and backward slash) are not allowed in the stage name. +

    +
    • +
  • version_file:

    Designates which version should be used when building the symbolic links. diff --git a/documents/standards/controller/documents/actions.txt b/documents/standards/controller/documents/actions.txt index 9cad634..dac5c63 100644 --- a/documents/standards/controller/documents/actions.txt +++ b/documents/standards/controller/documents/actions.txt @@ -1,6 +1,7 @@ # fss-0002 iki-0000 # # license: open-standard-license-1.0-or-later +# version 2024/07/02 # # 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 '"' '"' diff --git a/documents/standards/controller/documents/entry.txt b/documents/standards/controller/documents/entry.txt index 7a1983f..5292125 100644 --- a/documents/standards/controller/documents/entry.txt +++ b/documents/standards/controller/documents/entry.txt @@ -1,6 +1,7 @@ # fss-0002 iki-0000 # # license: open-standard-license-1.0-or-later +# version 2024/07/10 # # 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 '"' '"' @@ -172,8 +173,8 @@ Entry Documentation: - 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. + For example, the controller program may be used as a full blown code:"init" replacement and therefore may need to mount the /run/ directory. + If the PID:"Process Identifier" file is created at program start, then the /run/controller.pid would be written before the /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. diff --git a/documents/standards/controller/documents/exit.txt b/documents/standards/controller/documents/exit.txt index 1d287b6..499991f 100644 --- a/documents/standards/controller/documents/exit.txt +++ b/documents/standards/controller/documents/exit.txt @@ -1,6 +1,7 @@ # fss-0002 iki-0000 # # license: open-standard-license-1.0-or-later +# version 2024/07/10 # # 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 '"' '"' @@ -116,8 +117,8 @@ Exit Documentation: - 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. + For example, the controller program may be used as a full blown code:"init" replacement and therefore may need to mount the /run/ directory. + If the PID:"Process Identifier" file is created at program start, then the /run/controller.pid would be written before the /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. diff --git a/documents/standards/controller/documents/packet.txt b/documents/standards/controller/documents/packet.txt index a78f9fa..ef83b03 100644 --- a/documents/standards/controller/documents/packet.txt +++ b/documents/standards/controller/documents/packet.txt @@ -1,6 +1,7 @@ # fss-0002 iki-0000 # # license: open-standard-license-1.0-or-later +# version 2024/07/02 # # 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 '"' '"' diff --git a/documents/standards/controller/documents/readme.build.txt b/documents/standards/controller/documents/readme.build.txt new file mode 100644 index 0000000..bf994f8 --- /dev/null +++ b/documents/standards/controller/documents/readme.build.txt @@ -0,0 +1,335 @@ +# fss-0002 iki-0000 +# +# license: cc-by-sa-4.0 +# version 2024/07/10 +# +# This file (assumed to be named readme.build.txt) can be more easily read using the following iki_read commands: +# iki_read readme.build.txt +Q -w -rr FLL FLL FSS FSS -W code '"' '"' +# +# To read the "Build Readme Documentation" section of this file, use this command sequence: +# fss_basic_list_read readme.build.txt +Q -cn "Build Readme Documentation" | iki_read +Q -w -rr FLL FLL FSS FSS -W code '"' '"' +# + +Build Readme Documentation: + The bold:"Featureless Make", or code:"fake", is a build system opposing the bold:"GNU Make" build (and install) system. + See the code:"fake" project for further details regarding that build system. + + Use the code:"make" operation from the code:"fake" program to build this project\: + code:"fake" + + If the project has already been built before, alternative consider performing both a code:"clean" and an explicit code:"make" operation\: + code:"fake clean make" + + After building, either run the helper file:"install.sh" script or manually install the build files. + + Install Example\: + code:"./install.sh" + + Manual Install Example\: + code:"cp -vR build/documentation/* /usr/share/" + code:"cp -vR build/includes/* /usr/include/" + code:"cp -vR build/libaries/shared/* /usr/lib/" + code:"cp -vR build/programs/shared/* /usr/bin/" + code:"cp -vR build/settings/* /etc/" + + Build Tree Structure Example (using an early code:"controller-0.7.0" project structure)\: + block:" + build/ + ├── documentation + │   └── man + │   ├── man1 + │   │   └── controller.1 + │   └── man5 + │   ├── controller-actions.5 + │   ├── controller-entry.5 + │   ├── controller-exit.5 + │   ├── controller-packet.5 + │   └── controller-rule.5 + ├── documents + ├── includes + │   └── program + │   └── controller + │   ├── controller + │   │   ├── controller.h + │   │   └── string.h + │   ├── init + │   │   ├── init.h + │   │   └── string.h + │   └── main + │   ├── common + │   │   ├── define + │   │   │   ├── control.h + │   │   │   ├── entry.h + │   │   │   ├── rule.h + │   │   │   └── thread.h + │   │   ├── define.h + │   │   ├── enumeration + │   │   │   ├── control.h + │   │   │   ├── entry.h + │   │   │   ├── instance.h + │   │   │   ├── process.h + │   │   │   ├── rule.h + │   │   │   └── thread.h + │   │   ├── enumeration.h + │   │   ├── print.h + │   │   ├── string + │   │   │   ├── general.h + │   │   │   └── rule.h + │   │   ├── string.h + │   │   ├── type + │   │   │   ├── cache.h + │   │   │   ├── control.h + │   │   │   ├── defs.h + │   │   │   ├── entry.h + │   │   │   ├── execute.h + │   │   │   ├── instance.h + │   │   │   ├── interrupt.h + │   │   │   ├── lock.h + │   │   │   ├── process.h + │   │   │   ├── rule.h + │   │   │   └── thread.h + │   │   └── type.h + │   ├── common.h + │   ├── controller.h + │   ├── convert.h + │   ├── entry + │   │   ├── action.h + │   │   ├── preprocess.h + │   │   ├── process.h + │   │   └── setting.h + │   ├── entry.h + │   ├── file.h + │   ├── instance + │   │   ├── prepare.h + │   │   └── wait.h + │   ├── instance.h + │   ├── lock.h + │   ├── path.h + │   ├── perform.h + │   ├── print + │   │   ├── data.h + │   │   ├── debug + │   │   │   ├── perform + │   │   │   │   ├── control.h + │   │   │   │   └── pid.h + │   │   │   └── rule + │   │   │   ├── action.h + │   │   │   └── execute.h + │   │   ├── debug.h + │   │   ├── error + │   │   │   ├── entry + │   │   │   │   ├── action.h + │   │   │   │   ├── item.h + │   │   │   │   └── setting.h + │   │   │   ├── entry.h + │   │   │   ├── lock.h + │   │   │   ├── perform + │   │   │   │   └── pid.h + │   │   │   ├── rule + │   │   │   │   ├── action.h + │   │   │   │   ├── item.h + │   │   │   │   └── setting.h + │   │   │   └── rule.h + │   │   ├── error.h + │   │   ├── lock.h + │   │   ├── message + │   │   │   ├── entry + │   │   │   │   ├── action.h + │   │   │   │   └── item.h + │   │   │   └── entry.h + │   │   ├── message.h + │   │   ├── output + │   │   │   ├── entry + │   │   │   │   └── setting.h + │   │   │   └── rule + │   │   │   ├── execute.h + │   │   │   ├── setting.h + │   │   │   └── validate.h + │   │   ├── verbose.h + │   │   ├── warning + │   │   │   ├── entry + │   │   │   │   ├── action.h + │   │   │   │   ├── item.h + │   │   │   │   └── setting.h + │   │   │   └── rule + │   │   │   ├── action.h + │   │   │   ├── item.h + │   │   │   └── setting.h + │   │   └── warning.h + │   ├── process.h + │   ├── rule + │   │   ├── action.h + │   │   ├── execute.h + │   │   ├── expand.h + │   │   ├── instance.h + │   │   ├── is.h + │   │   ├── item.h + │   │   ├── parameter.h + │   │   ├── read.h + │   │   ├── setting.h + │   │   └── wait.h + │   ├── rule.h + │   ├── signal.h + │   ├── status.h + │   ├── thread + │   │   ├── cleanup.h + │   │   ├── control.h + │   │   ├── entry.h + │   │   ├── instance.h + │   │   ├── is.h + │   │   ├── rule.h + │   │   └── signal.h + │   ├── thread.h + │   ├── time.h + │   └── validate.h + ├── libraries + │   ├── script + │   ├── shared + │   │   ├── libcontroller.so -> libcontroller.so.0 + │   │   ├── libcontroller.so.0 -> libcontroller.so.0.7 + │   │   ├── libcontroller.so.0.7 -> libcontroller.so.0.7.0 + │   │   └── libcontroller.so.0.7.0 + │   └── static + ├── objects + │   ├── script + │   ├── shared + │   └── static + ├── programs + │   ├── script + │   ├── shared + │   │   ├── controller + │   │   └── init + │   └── static + ├── settings + │   └── controller + │   ├── entries + │   │   ├── default.entry + │   │   └── maintenance.entry + │   ├── example + │   │   ├── cgroup_example + │   │   │   ├── entries + │   │   │   │   ├── chromium.entry + │   │   │   │   ├── eclipse.entry + │   │   │   │   ├── firefox.entry + │   │   │   │   └── setup_cgroups.entry + │   │   │   └── rules + │   │   │   ├── program + │   │   │   │   ├── chromium.rule + │   │   │   │   ├── eclipse.rule + │   │   │   │   └── firefox.rule + │   │   │   └── setup + │   │   │   └── cgroups.rule + │   │   ├── entries + │   │   │   ├── asynchronous.entry + │   │   │   ├── asynchronous-serial.entry + │   │   │   ├── delay-program.entry + │   │   │   ├── delay-service.entry + │   │   │   ├── environment.entry + │   │   │   ├── htop-alternate.entry + │   │   │   ├── htop-command.entry + │   │   │   ├── htop.entry + │   │   │   ├── iki.entry + │   │   │   ├── serial-alternate.entry + │   │   │   ├── serial.entry + │   │   │   ├── sshd.entry + │   │   │   ├── test.entry + │   │   │   ├── up.entry + │   │   │   └── utility.entry + │   │   ├── exits + │   │   │   ├── htop-alternate.exit + │   │   │   ├── serial.exit + │   │   │   └── sshd.exit + │   │   └── rules + │   │   ├── asynchronous + │   │   │   ├── sleep_10.rule + │   │   │   ├── sleep_1.rule + │   │   │   ├── sleep_2.rule + │   │   │   ├── sleep_3.rule + │   │   │   ├── sleep_5.rule + │   │   │   └── sleep_8.rule + │   │   ├── command + │   │   │   ├── htop.rule + │   │   │   └── multiple.rule + │   │   ├── delay + │   │   │   ├── long.rule + │   │   │   └── short.rule + │   │   ├── environment + │   │   │   ├── default.rule + │   │   │   ├── empty.rule + │   │   │   ├── exported.rule + │   │   │   ├── exporting.rule + │   │   │   ├── fake-nothing.rule + │   │   │   └── fake-something.rule + │   │   ├── maintenance + │   │   │   └── boom.rule + │   │   ├── print + │   │   │   └── newline.rule + │   │   ├── script + │   │   │   ├── create_socket_path.rule + │   │   │   ├── fail.rule + │   │   │   ├── iki.rule + │   │   │   ├── php.rule + │   │   │   ├── python.rule + │   │   │   ├── require_me.rule + │   │   │   └── succeed.rule + │   │   ├── serial + │   │   │   ├── s_1.rule + │   │   │   ├── s_2.rule + │   │   │   ├── s_3.rule + │   │   │   ├── s_4.rule + │   │   │   ├── s_5.rule + │   │   │   └── s_6.rule + │   │   ├── service + │   │   │   └── sshd.rule + │   │   └── utility + │   │   ├── sleeper_1.rule + │   │   ├── sleeper_2.rule + │   │   └── sleeper_3.rule + │   └── rules + │   ├── boot + │   │   ├── devices.rule + │   │   ├── file_system.rule + │   │   ├── modules.rule + │   │   ├── proc.rule + │   │   └── root.rule + │   ├── maintenance + │   │   └── console.rule + │   ├── net + │   │   ├── all.rule + │   │   └── loopback.rule + │   ├── service + │   │   ├── dbus.rule + │   │   ├── logger.rule + │   │   └── mouse.rule + │   ├── task + │   │   ├── clock.rule + │   │   ├── keyboard.rule + │   │   └── ntpdate.rule + │   └── terminal + │   ├── four.rule + │   ├── one.rule + │   ├── three.rule + │   └── two.rule + └── stage + ├── library_shared-settings.built + ├── program_shared-settings.controller.built + ├── program_shared-settings.init.built + ├── skeleton-settings.built + ├── skeleton-settings.controller.built + ├── skeleton-settings.init.built + ├── sources_documentation-settings.built + ├── sources_documentation-settings.controller.built + ├── sources_documentation-settings.init.built + ├── sources_headers-settings.built + ├── sources_headers-settings.controller.built + ├── sources_headers-settings.init.built + ├── sources_script-settings.built + ├── sources_script-settings.controller.built + ├── sources_script-settings.init.built + ├── sources_settings-settings.built + ├── sources_settings-settings.controller.built + └── sources_settings-settings.init.built + " + + See: FLL:"Featureless Linux Library" code:"fake" project documents and specifications for further details on how to use the bold:"Featureless Make" system. + See: FLL:"Featureless Linux Library" project documentation and specifications for how to configure the bold:"Featureless Make" FSS:"Featureless Settings Specification" files. diff --git a/documents/standards/controller/documents/readme.txt b/documents/standards/controller/documents/readme.txt new file mode 100644 index 0000000..63d0a26 --- /dev/null +++ b/documents/standards/controller/documents/readme.txt @@ -0,0 +1,28 @@ +# fss-0002 iki-0000 +# +# license: cc-by-sa-4.0 +# version 2024/07/10 +# +# This file (assumed to be named readme.build.txt) can be more easily read using the following iki_read commands: +# iki_read readme.txt +Q -w -r FLL FLL +# +# To read the "Readme Documentation" section of this file, use this command sequence: +# fss_basic_list_read readme.txt +Q -cn "Readme Documentation" | iki_read +Q -w -r FLL FLL +# + +Readme Documentation: + The Controller program utilizes the FLL:"Featureless Linux Library" and is designed to be used for bold:"Linux" systems. + + This project follows many of the FLL:"Featureless Linux Library" project practices and the documentation provided by that project should be consulted for further details in this regard. + + The purpose of this project is to provide a tool to help facilitate controlled execution of processes. + This behavior is strongly correlated with how a basic system initializer works, alsa called an bold:"init" program. + An bold:"init" program is therefore provided as another alternative to the different bold:"init" programs out there. + + This project follows bold:"Specification Driven Development" and details of the configuration files are defined in the directory:"specifications/" and in the directory:"documents/". + + To facilitate building of this project, these build systems are provided\: + - The bold:"Featureless Make", which is a level 3 project provided by FLL:"Featureless Linux Library". + + See: file:"data/build/dependencies" for specific dependencies of this project. + See: file:"documents/readme.build.txt" for bold:"Featureless Make" compiling and notes on installing. diff --git a/documents/standards/controller/documents/rule.txt b/documents/standards/controller/documents/rule.txt index 5d9805a..d305198 100644 --- a/documents/standards/controller/documents/rule.txt +++ b/documents/standards/controller/documents/rule.txt @@ -1,6 +1,7 @@ # fss-0002 iki-0000 # # license: open-standard-license-1.0-or-later +# version 2024/07/02 # # 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 '"' '"' diff --git a/documents/standards/controller/documents/simulate.txt b/documents/standards/controller/documents/simulate.txt index a7d003d..f9e6e06 100644 --- a/documents/standards/controller/documents/simulate.txt +++ b/documents/standards/controller/documents/simulate.txt @@ -1,6 +1,7 @@ # fss-0002 iki-0000 # # license: open-standard-license-1.0-or-later +# version 2024/07/02 # # 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 '"' '"' diff --git a/documents/standards/controller/specifications/entry.txt b/documents/standards/controller/specifications/entry.txt index 54f9aff..95c1cf6 100644 --- a/documents/standards/controller/specifications/entry.txt +++ b/documents/standards/controller/specifications/entry.txt @@ -1,6 +1,7 @@ # fss-0002 iki-0000 # # license: open-standard-license-1.0-or-later +# version 2024/07/02 # # 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 '"' '"' diff --git a/documents/standards/controller/specifications/exit.txt b/documents/standards/controller/specifications/exit.txt index 1d2b842..476687b 100644 --- a/documents/standards/controller/specifications/exit.txt +++ b/documents/standards/controller/specifications/exit.txt @@ -1,6 +1,7 @@ # fss-0002 iki-0000 # # license: open-standard-license-1.0-or-later +# version 2024/07/02 # # 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 '"' '"' diff --git a/documents/standards/controller/specifications/packet.txt b/documents/standards/controller/specifications/packet.txt index 59ee6c1..f5dc07b 100644 --- a/documents/standards/controller/specifications/packet.txt +++ b/documents/standards/controller/specifications/packet.txt @@ -1,6 +1,7 @@ # fss-0002 iki-0000 # # license: open-standard-license-1.0-or-later +# version 2024/07/02 # # 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 '"' '"' diff --git a/documents/standards/controller/specifications/rule.txt b/documents/standards/controller/specifications/rule.txt index db45a2e..0648378 100644 --- a/documents/standards/controller/specifications/rule.txt +++ b/documents/standards/controller/specifications/rule.txt @@ -1,6 +1,7 @@ # fss-0002 iki-0000 # # license: open-standard-license-1.0-or-later +# version 2024/07/02 # # 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 '"' '"' diff --git a/documents/standards/controller/specifications/task.txt b/documents/standards/controller/specifications/task.txt index 5158361..b409917 100644 --- a/documents/standards/controller/specifications/task.txt +++ b/documents/standards/controller/specifications/task.txt @@ -1,6 +1,7 @@ # fss-0002 iki-0000 # # license: open-standard-license-1.0-or-later +# version 2024/07/02 # # 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 '"' '"' diff --git a/documents/standards/fake/documents/fakefile.txt b/documents/standards/fake/documents/fakefile.txt index 0d1eb2a..aa57bae 100644 --- a/documents/standards/fake/documents/fakefile.txt +++ b/documents/standards/fake/documents/fakefile.txt @@ -1,7 +1,7 @@ # fss-0002 iki-0000 # # license: open-standard-license-1.0-or-later -# version 2024/03/23 +# version 2024/07/30 # # 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 '"' '"' @@ -11,14 +11,14 @@ # Fakefile Documentation: - This describes intent and purposes of the fakefile file settings. - For specific details on the allowed formatting, see the fakefile.txt under the specifications folder. + 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 fakefile is stored here. + Any configuration specific to this file:"fakefile" is stored here. This includes the declaration of define and parameter IKI variable substitution values. If multiple bold:"Objects" of the same name exist and that bold:"Object" only supports a single value, then only the bold:"Content" from the last same named bold:"Object" is used. @@ -58,9 +58,9 @@ Fakefile Documentation: The return code for programs can still be retrieved through using the reserved bold:"IKI" variable code:"return". - code:"import"\: - Load this fakefile. - The code:"settings" section data from the imported fakefile is treated as if it were appended to the end of the current fakefile code:"setting" section. - Each section in the imported 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 fakefile, if no matches are found. + 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. @@ -92,8 +92,15 @@ Fakefile Documentation: 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:"stage"\: + This defines a name that is added to the build stage files to help uniquely identify build stages associated with this file. + This name must only have valid characters for a particular file system. + The variables allowed are different from file system to file system and so special characters should generally be avoided. + + To help prevent problems with paths, slashes (forward slash and backward slash) are not allowed in the stage name. + - code:"main"\: - This is the main entry point when processing the fakefile. + 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\: @@ -410,7 +417,7 @@ Fakefile Documentation: 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 fakefile. + 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. diff --git a/documents/standards/fake/documents/settings.txt b/documents/standards/fake/documents/settings.txt index 64c3e7f..e764d32 100644 --- a/documents/standards/fake/documents/settings.txt +++ b/documents/standards/fake/documents/settings.txt @@ -1,7 +1,7 @@ # fss-0002 iki-0000 # # license: open-standard-license-1.0-or-later -# version 2024/03/23 +# version 2024/07/30 # # 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 '"' '"' @@ -13,7 +13,7 @@ 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 settings.txt under the specifications folder. + 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". @@ -368,7 +368,7 @@ Settings Documentation: - 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 settings.txt specification for a list of which setting names this applies to. + 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. @@ -474,7 +474,7 @@ Settings Documentation: 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 data/build/ directory) of a script to execute after the code:"build" operation successfully completes. + 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". @@ -488,7 +488,7 @@ Settings Documentation: 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 data/build/ directory) of a script to execute before the code:"build" operation is executed. + 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". @@ -518,6 +518,13 @@ Settings Documentation: When code:"yes", static library paths are searched during compile. Both this and search_shared cannot be code:"no" at the same time. + - code:"stage"\: + This defines a name that is added to the build stage files to help uniquely identify build stages associated with this file. + This name must only have valid characters for a particular file system. + The variables allowed are different from file system to file system and so special characters should generally be avoided. + + To help prevent problems with paths, slashes (forward slash and backward slash) are not allowed in the stage name. + - code:"version_file"\: Designates which version should be used when building the symbolic links. Any version prefixes are used as defined. diff --git a/documents/standards/fake/specifications/dependencies.txt b/documents/standards/fake/specifications/dependencies.txt index a3aa4ed..abb9ed7 100644 --- a/documents/standards/fake/specifications/dependencies.txt +++ b/documents/standards/fake/specifications/dependencies.txt @@ -11,7 +11,7 @@ # Dependencies Specification: - The build settings dependencies file follows the code:"FSS-0001 (Extended)" format. + The build settings file:"dependencies" file follows the code:"FSS-0001 (Extended)" format. Each Object represents a specific project name as it would be linked against. Each Content represents associated information, such as a version number. diff --git a/documents/standards/fake/specifications/fakefile.txt b/documents/standards/fake/specifications/fakefile.txt index 9339d31..7a8134e 100644 --- a/documents/standards/fake/specifications/fakefile.txt +++ b/documents/standards/fake/specifications/fakefile.txt @@ -1,7 +1,7 @@ # fss-0002 iki-0000 # # license: open-standard-license-1.0-or-later -# version 2024/03/23 +# version 2024/07/30 # # 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 -WW character "'" "'" code '"' '"' @@ -11,9 +11,9 @@ # Fakefile Specification: - The fakefile file follows the code:"FSS-0005 (Somewhat Basic List)" format with a sub-format of code:"IKI-0002 (Simple Script)". + The file:"fakefile" file follows the code:"FSS-0005 (Somewhat Basic List)" format with a sub-format of code:"IKI-0002 (Simple Script)". - A fakefile is broken up into multiple bold:"Basic Lists", referred to as bold:"Sections", with two special purpose reserved bold:"Sections". + 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". Each of these non-reserved Sections acts as a set to perform some set of bold:"Section Operations". @@ -38,14 +38,15 @@ Fakefile Specification: The bold:"Settings Objects" are\: - code:"compiler": Only one bold:"Content", which must only be a valid filename. - - code:"define": First bold:"Content" represents variable name (case-sensitive), remaining bold:"Content" represents the value. + - code:"define": First bold:"Content" represents the variable name (case-sensitive), remaining bold:"Content" represents the value. - code:"environment": Zero or more bold:"Content" representing valid environment variable names (alpha-numeric with underscore, but cannot begin with a number). - code:"fail": Only one bold:"Content", which must be either code:"exit", code:"warn" or code:"ignore" (quotes not required) (case-sensitive). - code:"import": Only one bold:"Content", which must only be a valid filename. - code:"indexer": Only one bold:"Content", which must only be a valid filename. - code:"indexer_arguments: Zero or more arguments supported by the indexer specified in code:"build_indexer". - code:"load_build": Only one bold:"Content", which must be either code:"yes" or code:"no" (quotes not required) (case-sensitive). - - code:"parameter": First bold:"Content" represents variable name (case-sensitive), remaining bold:"Content" represents the value. + - code:"parameter": First bold:"Content" represents the variable name (case-sensitive), remaining bold:"Content" represents the value. + - code:"stage": Zero or one bold:"Content", which represents the build stage name (case-sensitive) (no slashes allowed). The build settings may also be specified in the bold:"Settings Section". diff --git a/documents/standards/fake/specifications/settings.txt b/documents/standards/fake/specifications/settings.txt index 5fd1e63..9a94ef2 100644 --- a/documents/standards/fake/specifications/settings.txt +++ b/documents/standards/fake/specifications/settings.txt @@ -1,7 +1,7 @@ # fss-0002 iki-0000 # # license: open-standard-license-1.0-or-later -# version 2024/03/23 +# version 2024/07/30 # # 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 -WW character "'" "'" code '"' '"' @@ -27,7 +27,7 @@ Settings Specification: - code:"build_libraries": Must only contain any number of valid library include arguments that are valid for the compiler defined in "build_compiler" bold:"Object". - code:"build_libraries_shared": Must only contain any number of valid library include arguments that are valid for the compiler defined in "build_compiler" bold:"Object". - code:"build_libraries_static": Must only contain any number of valid library include arguments that are valid for the compiler defined in "build_compiler" bold:"Object". - - code:"build_name": Must only contain characters allowed in a filename. + - code:"build_name": Must only contain characters allowed in a filename (no slashes allowed). - code:"build_objects_library": Must only contain any number of valid object file names relative to the appropriate code:"path_object_*" path. - code:"build_objects_library_shared": Must only contain any number of valid object file names relative to the code:"path_object_shared" path. - code:"build_objects_library_static": Must only contain any number of valid object file names relative to the code:"path_object_static" path. @@ -104,15 +104,16 @@ Settings Specification: - code:"search_exclusive": Must only one of: code:"yes" or code:"no". - code:"search_shared": Must only one of: code:"yes" or code:"no". - code:"search_static": Must only one of: code:"yes" or code:"no". + - code:"stage": Only zero or one bold:"Content", which represents the build stage name (case-sensitive) (no slashes allowed). - code:"version_file": Must only be one of: code:"major", code:"minor", code:"micro", or code:"nano". - - code:"version_major": Must only be a single value containing valid filename characters. - - code:"version_major_prefix": Must be zero or more valid filename characters. - - code:"version_micro": Must only be a single value containing valid filename characters. - - code:"version_micro_prefix": Must be zero or more valid filename characters. - - code:"version_minor": Must only be a single value containing valid filename characters. - - code:"version_minor_prefix": Must be zero or more valid filename characters. - - code:"version_nano": Must only be a single value containing valid filename characters. - - code:"version_nano_prefix": Must be zero or more valid filename characters. + - code:"version_major": Must only be a single value containing valid filename characters (no slashes allowed). + - code:"version_major_prefix": Must be zero or more valid filename characters (no slashes allowed). + - code:"version_micro": Must only be a single value containing valid filename characters (no slashes allowed). + - code:"version_micro_prefix": Must be zero or more valid filename characters (no slashes allowed). + - code:"version_minor": Must only be a single value containing valid filename characters (no slashes allowed). + - code:"version_minor_prefix": Must be zero or more valid filename characters (no slashes allowed). + - code:"version_nano": Must only be a single value containing valid filename characters (no slashes allowed). + - code:"version_nano_prefix": Must be zero or more valid filename characters (no slashes allowed). - code:"version_target": Must only be one of: code:"major", code:"minor", code:"micro", or code:"nano". All bold:"Object" names support having a code:"-" and a code:"mode" name, such as code:"build_libraries-individual" for a mode called code:"individual", except for the code:"modes" and the code:"modes_default" bold:"Object" names. diff --git a/documents/standards/fll/specifications/fss-0004.txt b/documents/standards/fll/specifications/fss-0004.txt index 5e04dbd..32adee4 100644 --- a/documents/standards/fll/specifications/fss-0004.txt +++ b/documents/standards/fll/specifications/fss-0004.txt @@ -15,7 +15,7 @@ Featureless Settings Specification: 0004 - Very Basic List: All code:"FSS-0002 (Basic List)" escapes are applied before any code:"FSS-0000 (Basic)" is identified. - See the fss-0000.txt and fss-0002.txt specification files for details on the syntax rules. + See the file:"fss-0000.txt" and file:"fss-0002.txt" specification files for details on the syntax rules. Example\: # fss-0004 diff --git a/documents/standards/fll/specifications/fss-0005.txt b/documents/standards/fll/specifications/fss-0005.txt index 760cc9e..deaed3d 100644 --- a/documents/standards/fll/specifications/fss-0005.txt +++ b/documents/standards/fll/specifications/fss-0005.txt @@ -15,7 +15,7 @@ Featureless Settings Specification: 0005 - Somewhat Basic List: All code:"FSS-0002 (Basic List)" escapes are applied before any code:"FSS-0001 (Extended)" is identified. - See the fss-0001.txt and fss-0002.txt specification files for details on the syntax rules. + See the file:"fss-0001.txt" and file:"fss-0002.txt" specification files for details on the syntax rules. Example\: # fss-0005 diff --git a/documents/standards/fll/specifications/fss-0006.txt b/documents/standards/fll/specifications/fss-0006.txt index fdeceb8..417a4c7 100644 --- a/documents/standards/fll/specifications/fss-0006.txt +++ b/documents/standards/fll/specifications/fss-0006.txt @@ -15,7 +15,7 @@ Featureless Settings Specification: 0006 - Somewhat Extended List: All code:"FSS-0003 (Extended List)" escapes are applied before any code:"FSS-0000 (Basic)" is identified. - See the fss-0000.txt and fss-0003.txt specification files for details on the syntax rules. + See the file:"fss-0000.txt" and file:"fss-0003.txt" specification files for details on the syntax rules. Example\: # fss-0006 diff --git a/documents/standards/fll/specifications/fss-0007.txt b/documents/standards/fll/specifications/fss-0007.txt index 791a2ee..d420bca 100644 --- a/documents/standards/fll/specifications/fss-0007.txt +++ b/documents/standards/fll/specifications/fss-0007.txt @@ -15,7 +15,7 @@ Featureless Settings Specification: 0007 - Very Extended List: All code:"FSS-0003 (Extended List)" escapes are applied before any code:"FSS-0001 (Extended)" is identified. - See the fss-0001.txt and fss-0003.txt specification files for details on the syntax rules. + See the file:"fss-0001.txt" and file:"fss-0003.txt" specification files for details on the syntax rules. Example\: # fss-0007 diff --git a/documents/standards/fll/specifications/fss-0008.txt b/documents/standards/fll/specifications/fss-0008.txt index 9c6ea71..3409cf5 100644 --- a/documents/standards/fll/specifications/fss-0008.txt +++ b/documents/standards/fll/specifications/fss-0008.txt @@ -13,7 +13,7 @@ Featureless Settings Specification: 0008 - Embedded List: This is a code:"FSS-0003 (Extended List)" whose Content is then recursively processed as code:"FSS-0003 (Extended List)". - See the fss-0003.txt specification file for details on the syntax rules. + See the file:"fss-0003.txt" specification file for details on the syntax rules. Example\: # fss-0008 diff --git a/documents/standards/fll/specifications/fss-000b.txt b/documents/standards/fll/specifications/fss-000b.txt index a9ed921..55a53c1 100644 --- a/documents/standards/fll/specifications/fss-000b.txt +++ b/documents/standards/fll/specifications/fss-000b.txt @@ -13,7 +13,7 @@ Featureless Settings Specification: 000B - Simple List: This is similar to code:"FSS-0008 (Embedded List)", except that it is an code:"FSS-0003 (Extended List)" with a (non-recursive) code:"FSS-0002 (Basic List)" inside the Content. - See the fss-0002.txt and fss-0003.txt specification files for details on the syntax rules. + See the file:"fss-0002.txt" and file:"fss-0003.txt" specification files for details on the syntax rules. Example\: # fss-000b diff --git a/documents/standards/fll/specifications/fss-000c.txt b/documents/standards/fll/specifications/fss-000c.txt index 954089d..8180e61 100644 --- a/documents/standards/fll/specifications/fss-000c.txt +++ b/documents/standards/fll/specifications/fss-000c.txt @@ -17,7 +17,7 @@ Featureless Settings Specification: 000C - IKI Text: The IKI syntax may be used in any FSS:"Featureless Settings Specifications". The IKI format may be added to the. - See the iki.txt specification for details on the IKI specifications. + See the file:"iki.txt" specification for details on the IKI specifications. Example\: # fss-000c iki-0000 diff --git a/documents/standards/fll/specifications/fss-000d.txt b/documents/standards/fll/specifications/fss-000d.txt index 3359dcd..899a263 100644 --- a/documents/standards/fll/specifications/fss-000d.txt +++ b/documents/standards/fll/specifications/fss-000d.txt @@ -28,7 +28,7 @@ Featureless Settings Specification: 000D - Basic Rule: Anything implementing this specification may impose its own restrictions on when to determine if the Inner Content is what FSS:"Featureless Settings Specifications" format, based on Object names. - See the fss-0000.txt, fss-0001.txt, and fss-0003.txt specification files for details on the syntax rules. + See the file:"fss-0000.txt", file:"fss-0001.txt", and file:"fss-0003.txt" specification files for details on the syntax rules. Example\: # fss-000d diff --git a/documents/standards/fll/specifications/fss-000f.txt b/documents/standards/fll/specifications/fss-000f.txt index d5024d3..503f5f0 100644 --- a/documents/standards/fll/specifications/fss-000f.txt +++ b/documents/standards/fll/specifications/fss-000f.txt @@ -99,7 +99,7 @@ Featureless Settings Specification: 000f - Simple Packet: With this in mind, it is recommended that only a single italic:"header" be supported in the bold:"Payload Block". The italic:"payload" bold:"Content" may be in either a italic:"binary" or italic:"string" format regardless of the italic:"binary" bit in the bold:"Simple Packet" bold:"Header Block". - See the fss-000e.txt specification file for details on the syntax rules for the bold:"Payload Block". + See the file:"fss-000e.txt" specification file for details on the syntax rules for the bold:"Payload Block". Example Packet Structure\: code:" diff --git a/documents/standards/fll/specifications/fss-0010.txt b/documents/standards/fll/specifications/fss-0010.txt index 7f5ee47..8e52160 100644 --- a/documents/standards/fll/specifications/fss-0010.txt +++ b/documents/standards/fll/specifications/fss-0010.txt @@ -32,7 +32,7 @@ Featureless Settings Specification: 0010 - Encrypted Simple Packet: The 5 remaining control bits are left undefined. - See the fss-000f.txt specification file for details regarding the code:"FSS-000f (Simple Packet)" standard. + See the file:"fss-000f.txt" specification file for details regarding the code:"FSS-000f (Simple Packet)" standard. Example Packet Structure\: code:" diff --git a/documents/standards/fll/specifications/iki-0000.txt b/documents/standards/fll/specifications/iki-0000.txt index 6f147b1..68213c4 100644 --- a/documents/standards/fll/specifications/iki-0000.txt +++ b/documents/standards/fll/specifications/iki-0000.txt @@ -13,4 +13,4 @@ IKI Specification: 0000 - Unrestricted: This specification provides no restrictions on the vocabulary. - See the iki.txt specification file for details on the syntax rules. + See the file:"iki.txt" specification file for details on the syntax rules. diff --git a/documents/standards/fll/specifications/iki-0001.txt b/documents/standards/fll/specifications/iki-0001.txt index c1a62d0..df33095 100644 --- a/documents/standards/fll/specifications/iki-0001.txt +++ b/documents/standards/fll/specifications/iki-0001.txt @@ -24,4 +24,4 @@ IKI Specification: 0001 - Basic: - urn: Any valid URN:"Uniform Resource Name". - var: All text contained within represents some sort of variable. - See the iki.txt specification file for details on the syntax rules. + See the file:"iki.txt" specification file for details on the syntax rules. diff --git a/documents/standards/fll/specifications/iki-0002.txt b/documents/standards/fll/specifications/iki-0002.txt index 840ea17..21ed10f 100644 --- a/documents/standards/fll/specifications/iki-0002.txt +++ b/documents/standards/fll/specifications/iki-0002.txt @@ -25,4 +25,4 @@ IKI Specification: 0002 - Simple Script: - define: Intended to be used for global properties, much like a C/C++ code:"#define". - parameter: Intended to be used for parameters or variables. - See the iki.txt specification file for details on the syntax rules. + See the file:"iki.txt" specification file for details on the syntax rules. diff --git a/documents/standards/fll/specifications/iki.txt b/documents/standards/fll/specifications/iki.txt index c496915..92fe7a9 100644 --- a/documents/standards/fll/specifications/iki.txt +++ b/documents/standards/fll/specifications/iki.txt @@ -1,7 +1,7 @@ # fss-0002 iki-0000 # # license open-standard-license-1.0-or-later -# version 2024/06/11 +# version 2024/07/10 # # This file (assumed to be named iki.txt) can be more easily read using the following iki_read commands: # iki_read iki.txt +Q -w -WWW character "'" "'" code '"' '"' italic '"' '"' @@ -69,7 +69,7 @@ IKI Specifications: The following italic\:"is escaped to not be treated as IKI data". - The conditionally optional open and close brackets allow for putting a variable directly next to another word character like: [context]\:"strong"this[context]\:"strong".' + The conditionally optional open and close brackets allow for putting a variable directly next to another word character like: [context]\:"bold"this[context]\:"bold".' Objects (also called vocabulary or variable name) would be\: 1) italic @@ -86,8 +86,8 @@ IKI Specifications: 3.1) Featureless Settings Specification 4.1) const char *string = "My \"quoted\" C string."; 5.1) is escaped to not be treated as IKI data - 6.1) strong - 7.1) strong + 6.1) bold + 7.1) bold The following are core specifications (each with a common name associated with the specification number)\: - fss-0000: Unrestricted diff --git a/documents/standards/fll/specifications/time.txt b/documents/standards/fll/specifications/time.txt index 3a0ae79..5bc8514 100644 --- a/documents/standards/fll/specifications/time.txt +++ b/documents/standards/fll/specifications/time.txt @@ -21,7 +21,7 @@ Time Specification: This may have a negative value or be more than 64-bit digits long. This is simply not expected to be interpreted as a unit of time on a computer (but nothing stops it from being interpreted). - The technical forms are limit to 64-bit unsigned for technical use but should technology advance to a point where larger bits are needed then this allows for that. + The technical forms are limited to 64-bit unsigned for technical use but should technology advance to a point where larger bits are needed then this allows for that. The systems should expect 64-bit and larger bits would have to become common before something larger than 64-bit is the expected or assumed default. Negative signs can be allowed but they must not prevent the full use of the 64-bit. The implementation of how this is done is left to the implementer except that the signs are immediately to the left of the digit. -- 1.8.3.1