All of the documentation and specifications should now be IKI based.
I have finally decided on how I want abbreviations handled.
This removes the "abbreviation-" and "abbreviation:" from use.
The new behavior has the abbreviation followed by the expansion, such as FLL:"Featureless Linux Library".
have the block IKI structure identical in pattern to the script IKI structure.
Use "italic" instead of "emphasis" for such IKI vocabulary.
# license: cc-by-sa-4.0
#
# This file (assumed to be named readme.bootstrap.txt) can be more easily read using the following iki_read commands:
-# iki_read readme.bootstrap.txt +Q -w -rr abbreviation-FLL FLL abbreviation-FSS FSS -WW character "'" "'" code '"' '"'
+# iki_read readme.bootstrap.txt +Q -w -rr FLL FLL FSS FSS -WW character "'" "'" code '"' '"'
#
# To read the "Bootstrap Readme Documentation" section of this file, use this command sequence:
-# fss_basic_list_read readme.bootstrap.txt +Q -cn "Bootstrap Readme Documentation" | iki_read +Q -w -rr abbreviation-FLL FLL abbreviation-FSS FSS -WW character "'" "'" code '"' '"'
+# fss_basic_list_read readme.bootstrap.txt +Q -cn "Bootstrap Readme Documentation" | iki_read +Q -w -rr FLL FLL FSS FSS -WW character "'" "'" code '"' '"'
#
Bootstrap Readme Documentation:
- The abbreviation-FLL:"Featureless Linux Library" provides a special bootstrap script in case the bold:"Featureless Make" is not currently installed.
+ The FLL:"Featureless Linux Library" provides a special bootstrap script in case the bold:"Featureless Make" is not currently installed.
The bold:"GNU Bash" scripts, called file:"bootstrap.sh" and file:"install.sh", are provided to perform this bootstrap process.
If one of the build sub-directories, such as includes, libraries, programs, and settings, is empty or missing after a successful build, then there are no files of that type to install.
Build tree structure example (using the abbreviation-FLL:"Featureless Linux Library" code:"status_code-0.6.2" project)\:
- block:"build/
- ├── documents
- ├── includes
- │ └── program
- │ └── status_code
- │ ├── common.h
- │ └── status_code.h
- ├── libraries
- │ ├── script
- │ ├── shared
- │ │ ├── libstatus_code.so -> libstatus_code.so.0
- │ │ ├── libstatus_code.so.0 -> libstatus_code.so.0.6
- │ │ ├── libstatus_code.so.0.6 -> libstatus_code.so.0.6.2
- │ │ └── libstatus_code.so.0.6.2
- │ └── static
- │ └── libstatus_code.a
- ├── objects
- │ ├── common.o
- │ ├── private-common.o
- │ ├── private-status_code.o
- │ ├── script
- │ ├── shared
- │ ├── static
- │ └── status_code.o
- ├── programs
- │ ├── script
- │ ├── shared
- │ │ └── status_code
- │ └── static
- │ └── status_code
- ├── settings
- └── stage
- ├── library_shared-settings.built
- ├── library_static-settings.built
- ├── objects_static-settings.built
- ├── program_shared-settings.built
- ├── program_static-settings.built
- ├── skeleton-settings.built
- ├── sources_headers-settings.built
- ├── sources_script-settings.built
- └── sources_settings-settings.built"
+ block:"
+ build/
+ ├── documents
+ ├── includes
+ │ └── program
+ │ └── status_code
+ │ ├── common.h
+ │ └── status_code.h
+ ├── libraries
+ │ ├── script
+ │ ├── shared
+ │ │ ├── libstatus_code.so -> libstatus_code.so.0
+ │ │ ├── libstatus_code.so.0 -> libstatus_code.so.0.6
+ │ │ ├── libstatus_code.so.0.6 -> libstatus_code.so.0.6.2
+ │ │ └── libstatus_code.so.0.6.2
+ │ └── static
+ │ └── libstatus_code.a
+ ├── objects
+ │ ├── common.o
+ │ ├── private-common.o
+ │ ├── private-status_code.o
+ │ ├── script
+ │ ├── shared
+ │ ├── static
+ │ └── status_code.o
+ ├── programs
+ │ ├── script
+ │ ├── shared
+ │ │ └── status_code
+ │ └── static
+ │ └── status_code
+ ├── settings
+ └── stage
+ ├── library_shared-settings.built
+ ├── library_static-settings.built
+ ├── objects_static-settings.built
+ ├── program_shared-settings.built
+ ├── program_static-settings.built
+ ├── skeleton-settings.built
+ ├── sources_headers-settings.built
+ ├── sources_script-settings.built
+ └── sources_settings-settings.built
+ "
Work tree Structure example at file:"/tmp/work" (using the abbreviation-FLL:"Featureless Linux Library" code:"status_code-0.6.2" project)\:
- block:"/tmp/work/
- ├── includes
- │ └── program
- │ └── status_code
- │ ├── common.h
- │ └── status_code.h
- ├── libraries
- │ ├── shared
- │ │ ├── libstatus_code.so -> libstatus_code.so.0
- │ │ ├── libstatus_code.so.0 -> libstatus_code.so.0.6
- │ │ ├── libstatus_code.so.0.6 -> libstatus_code.so.0.6.2
- │ │ └── libstatus_code.so.0.6.2
- │ └── static
- │ └── libstatus_code.a
- └── programs
- ├── shared
- │ └── status_code
- └── static
- └── status_code"
+ block:"
+ /tmp/work/
+ ├── includes
+ │ └── program
+ │ └── status_code
+ │ ├── common.h
+ │ └── status_code.h
+ ├── libraries
+ │ ├── shared
+ │ │ ├── libstatus_code.so -> libstatus_code.so.0
+ │ │ ├── libstatus_code.so.0 -> libstatus_code.so.0.6
+ │ │ ├── libstatus_code.so.0.6 -> libstatus_code.so.0.6.2
+ │ │ └── libstatus_code.so.0.6.2
+ │ └── static
+ │ └── libstatus_code.a
+ └── programs
+ ├── shared
+ │ └── status_code
+ └── static
+ └── status_code
+ "
# license: cc-by-sa-4.0
#
# 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 abbreviation-FLL FLL abbreviation-FSS FSS -WW character "'" "'" code '"' '"'
+# iki_read readme.build.txt +Q -w -rr FLL FLL FSS FSS -WW character "'" "'" 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 abbreviation-FLL FLL abbreviation-FSS FSS -WW character "'" "'" code '"' '"'
+# fss_basic_list_read readme.build.txt +Q -cn "Build Readme Documentation" | iki_read +Q -w -rr FLL FLL FSS FSS -WW character "'" "'" code '"' '"'
#
Build Readme Documentation:
- Userspace execution calling is expensive, attempt to avoid such overhead by providing built-in functionality where reasonably possible.
- There should never need to be a code:"configure" script, like bold:"GNU Autoconf".
- The code:"fake" is designed to specifically build the abbreviation-FLL:"Featureless Linux Library" and encourages the use of code:"fake" to build abbreviation-FLL:"Featureless Linux Library".
+ The code:"fake" is designed to specifically build the FLL:"Featureless Linux Library" and encourages the use of code:"fake" to build FLL:"Featureless Linux Library".
The code:"fake" provides two main build operations\:
- - code:"build": a lean purely abbreviation-FSS:"Featureless Settings Specification" based build process, designed around specific but simple project designs (explicitly used by abbreviation-FLL:"Featureless Linux Library").
+ - code:"build": a lean purely FSS:"Featureless Settings Specification" based build process, designed around specific but simple project designs (explicitly used by FLL:"Featureless Linux Library").
- code:"make": a more powerful build process design to be more akin to bold:"GNU Make".
The code:"fake" supports custom development environments using the file:"work" directory concept, such as code:"fake build -w /tmp/work".
Build Example, explicitly using code:"make"\:
code:"fake make"
- Build Tree Structure Example (using the abbreviation-FLL:"Featureless Linux Library" code:"status_code-0.6.2" project)\:
- block:"build/
- ├── documents
- ├── includes
- │ └── program
- │ └── status_code
- │ ├── common.h
- │ └── status_code.h
- ├── libraries
- │ ├── script
- │ ├── shared
- │ │ ├── libstatus_code.so -> libstatus_code.so.0
- │ │ ├── libstatus_code.so.0 -> libstatus_code.so.0.6
- │ │ ├── libstatus_code.so.0.6 -> libstatus_code.so.0.6.2
- │ │ └── libstatus_code.so.0.6.2
- │ └── static
- │ └── libstatus_code.a
- ├── objects
- │ ├── common.o
- │ ├── private-common.o
- │ ├── private-status_code.o
- │ ├── script
- │ ├── shared
- │ ├── static
- │ └── status_code.o
- ├── programs
- │ ├── script
- │ ├── shared
- │ │ └── status_code
- │ └── static
- │ └── status_code
- ├── settings
- └── stage
- ├── library_shared-settings.built
- ├── library_static-settings.built
- ├── objects_static-settings.built
- ├── program_shared-settings.built
- ├── program_static-settings.built
- ├── skeleton-settings.built
- ├── sources_headers-settings.built
- ├── sources_script-settings.built
- └── sources_settings-settings.built"
+ Build Tree Structure Example (using the FLL:"Featureless Linux Library" code:"status_code-0.6.2" project)\:
+ block:"
+ build/
+ ├── documents
+ ├── includes
+ │ └── program
+ │ └── status_code
+ │ ├── common.h
+ │ └── status_code.h
+ ├── libraries
+ │ ├── script
+ │ ├── shared
+ │ │ ├── libstatus_code.so -> libstatus_code.so.0
+ │ │ ├── libstatus_code.so.0 -> libstatus_code.so.0.6
+ │ │ ├── libstatus_code.so.0.6 -> libstatus_code.so.0.6.2
+ │ │ └── libstatus_code.so.0.6.2
+ │ └── static
+ │ └── libstatus_code.a
+ ├── objects
+ │ ├── common.o
+ │ ├── private-common.o
+ │ ├── private-status_code.o
+ │ ├── script
+ │ ├── shared
+ │ ├── static
+ │ └── status_code.o
+ ├── programs
+ │ ├── script
+ │ ├── shared
+ │ │ └── status_code
+ │ └── static
+ │ └── status_code
+ ├── settings
+ └── stage
+ ├── library_shared-settings.built
+ ├── library_static-settings.built
+ ├── objects_static-settings.built
+ ├── program_shared-settings.built
+ ├── program_static-settings.built
+ ├── skeleton-settings.built
+ ├── sources_headers-settings.built
+ ├── sources_script-settings.built
+ └── sources_settings-settings.built
+ "
- Work Tree Structure Example at file:"/tmp/work" (using the abbreviation-FLL:"Featureless Linux Library" code:"status_code-0.6.2" project)\:
- block:"/tmp/work/
- ├── includes
- │ └── program
- │ └── status_code
- │ ├── common.h
- │ └── status_code.h
- ├── libraries
- │ ├── shared
- │ │ ├── libstatus_code.so -> libstatus_code.so.0
- │ │ ├── libstatus_code.so.0 -> libstatus_code.so.0.6
- │ │ ├── libstatus_code.so.0.6 -> libstatus_code.so.0.6.2
- │ │ └── libstatus_code.so.0.6.2
- │ └── static
- │ └── libstatus_code.a
- └── programs
- ├── shared
- │ └── status_code
- └── static
- └── status_code"
+ Work Tree Structure Example at file:"/tmp/work" (using the FLL:"Featureless Linux Library" code:"status_code-0.6.2" project)\:
+ block:"
+ /tmp/work/
+ ├── includes
+ │ └── program
+ │ └── status_code
+ │ ├── common.h
+ │ └── status_code.h
+ ├── libraries
+ │ ├── shared
+ │ │ ├── libstatus_code.so -> libstatus_code.so.0
+ │ │ ├── libstatus_code.so.0 -> libstatus_code.so.0.6
+ │ │ ├── libstatus_code.so.0.6 -> libstatus_code.so.0.6.2
+ │ │ └── libstatus_code.so.0.6.2
+ │ └── static
+ │ └── libstatus_code.a
+ └── programs
+ ├── shared
+ │ └── status_code
+ └── static
+ └── status_code
+ "
- See: abbreviation-FLL:"Featureless Linux Library" code:"fake" project documents for further details on how to use the bold:"Featureless Make" system.
- See: abbreviation-FLL:"Featureless Linux Library" code:"fake" project specifications for how to configure the build abbreviation-FSS:"Featureless Settings Specification" files and make abbreviation-FSS:"Featureless Settings Specification" files.
+ See: FLL:"Featureless Linux Library" code:"fake" project documents for further details on how to use the bold:"Featureless Make" system.
+ See: FLL:"Featureless Linux Library" code:"fake" project specifications for how to configure the build FSS:"Featureless Settings Specification" files and make FSS:"Featureless Settings Specification" files.
See: file:"readme.bootstrap.txt" for notes on installing.
# license: cc-by-sa-4.0
#
# 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 -rrrr abbreviation-API API abbreviation-FLL FLL abbreviation-FSS FSS abbreviation-KISS KISS -WW character "'" "'" code '"' '"'
+# iki_read readme.txt +Q -w -rrrr API API FLL FLL FSS FSS KISS KISS -WW character "'" "'" code '"' '"'
#
# 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 -rrrr abbreviation-API API abbreviation-FLL FLL abbreviation-FSS FSS abbreviation-KISS KISS -WW character "'" "'" code '"' '"'
+# fss_basic_list_read readme.txt +Q -cn "Readme Documentation" | iki_read +Q -w -rrrr API API FLL FLL FSS FSS KISS KISS -WW character "'" "'" code '"' '"'
#
Readme Documentation:
- The abbreviation-FLL:"Featureless Linux Library" is a set of projects designed to be used for bold:"Linux" programming.
+ The FLL:"Featureless Linux Library" is a set of projects designed to be used for bold:"Linux" programming.
- The abbreviation-FLL:"Featureless Linux Library" is design around the following concepts\:
- - abbreviation-API:"Application Programming Interface" designed around communicating to the programmer and maintaining unchanging consistency.
+ The FLL:"Featureless Linux Library" is design around the following concepts\:
+ - API:"Application Programming Interface" designed around communicating to the programmer and maintaining unchanging consistency.
- Hacker friendly, promote changing the project via its designed methodologies, implementations, standards, practices, and licenses.
- Add freedom back to computing, via the bold:"LGPL" license, because a library is a library.
- A standard is not a true standard if it is not freely available and cannot be freely used or followed.
- Avoid the bold:"feature" trap where projects keep adding things.
- Provide an explicit versioning system that is more than a number, it communicates the status in a very simple manner.
- Continue mantaining major versions, a project should be able to last 20, 30, or even 60 years without breaking changes.
- - Follow the abbreviation-KISS:"Keep It Simple Stupid", principles.
+ - Follow the KISS:"Keep It Simple Stupid", principles.
- Can be broken up into individual projects, and then further fine-tuned via custom define macros, so that only what is needed for specific situations need be used.
- The abbreviation-FLL:"Featureless Linux Library" versioning system has three parts: code:"major.minor.micro".
- - The bold:"Major" is the primary abbreviation-API:"Application Programming Interface" specification, changes to this number represent massive breaking changes and for all intents and purposes is a different project.
+ The FLL:"Featureless Linux Library" versioning system has three parts: code:"major.minor.micro".
+ - The bold:"Major" is the primary API:"Application Programming Interface" specification, changes to this number represent massive breaking changes and for all intents and purposes is a different project.
- The bold:"Minor" represents potential breaking changes, where odd numbers represent bold:"development status" and even numbers represent bold:"stable status".
- - The bold:"Micro" represents bug fixes and security fixes, these should never introduce neither abbreviation-API:"Application Programming Interface" breaking changes nor new functionality.
+ - The bold:"Micro" represents bug fixes and security fixes, these should never introduce neither API:"Application Programming Interface" breaking changes nor new functionality.
Development releases (as specified by bold:"Minor" version part) may introduce breaking changes and new functionality.
Stable releases (as specified by the bold:"Minor" version part) may not introduce breaking change, unless forced by some security or other difficult situation, and must not add new functionality.
- The abbreviation-FLL:"Featureless Linux Library" project is broken up into 3 different levels: code:"level_0", code:"level_1", and code:"level_2".
+ The FLL:"Featureless Linux Library" project is broken up into 3 different levels: code:"level_0", code:"level_1", and code:"level_2".
A third pseudo-level also exists for common programs built using this project, called code:"level_3".
With an exception of a few projects within code:"level_0", each level should only depend on a project from a lower level.
A few projects in code:"level_0" are essentially required by everything and are depended on by virtually all projects, regardless of the level.
These code:"level_0" projects are\:
- - code:"f_type": Provides core type definitions, code:"#define", and similar structures for the entire set of abbreviation-FLL:"Featureless Linux Library" projects.
- - code:"f_status": provides status codes and other status codes to be used by the entire set of abbreviation-FLL:"Featureless Linux Library" projects.
- - code:"f_memory": provides common memory allocation or deallocation to be used by the entire set of abbreviation-FLL:"Featureless Linux Library" projects.
- - code:"f_type_array": provides an extension on code:"f_type" that requires linking to code:"f_memory" to be used by the entire set of abbreviation-FLL:"Featureless Linux Library" projects.
- - code:"f_string": provides common string management to be used by the entire set of the abbreviation-FLL:"Featureless Linux Library" projects.
- - code:"f_utf": provides common UTF-8 related string management to be used by the entire set of the abbreviation-FLL:"Featureless Linux Library" projects.
+ - code:"f_type": Provides core type definitions, code:"#define", and similar structures for the entire set of FLL:"Featureless Linux Library" projects.
+ - code:"f_status": provides status codes and other status codes to be used by the entire set of FLL:"Featureless Linux Library" projects.
+ - code:"f_memory": provides common memory allocation or deallocation to be used by the entire set of FLL:"Featureless Linux Library" projects.
+ - code:"f_type_array": provides an extension on code:"f_type" that requires linking to code:"f_memory" to be used by the entire set of FLL:"Featureless Linux Library" projects.
+ - code:"f_string": provides common string management to be used by the entire set of the FLL:"Featureless Linux Library" projects.
+ - code:"f_utf": provides common UTF-8 related string management to be used by the entire set of the FLL:"Featureless Linux Library" projects.
The above projects should be installed first, and in the provided order (code:"f_type", then code:"f_status", then code:"f_memory", then code:"f_type_array", then code:"f_string", and finally code:"f_utf").
No other code:"level_0" project should depend on another and can be installed in any order.
To facilitate building of this project, two different build systems are provided\:
- The bootstrap, via the file:"bootstrap.sh" script.
- - The bold:"Featureless Make", which is a level_3 project provided by abbreviation-FLL:"Featureless Linux Library".
+ - The bold:"Featureless Make", which is a level_3 project provided by FLL:"Featureless Linux Library".
- An example bootstrap script is provided (file:"build/scripts/bootstrap-example.sh") is provided for to show how to build the abbreviation-FLL:"Featureless Linux Library" directly from source.
- Use it as an example or explicitly call it (such as: "bash build/scripts/bootstrap-example.sh monolithic 0.6.0").
+ An example bootstrap script is provided (file:"build/scripts/bootstrap-example.sh") is provided for to show how to build the FLL:"Featureless Linux Library" directly from source.
+ Use it as an example or explicitly call it (such as: code:"bash build/scripts/bootstrap-example.sh monolithic 0.6.0").
See: file:"dependencies" for specific dependencies of this project.
- See: file:"readme.bootstrap.txt" for bootstrap compiling (or just regular compiling) any part of the abbreviation-FLL:"Featureless Linux Library" and notes on installing.
+ See: file:"readme.bootstrap.txt" for bootstrap compiling (or just regular compiling) any part of the FLL:"Featureless Linux Library" and notes on installing.
See: file:"readme.build.txt" for bold:"Featureless Make" compiling and notes on installing.
-# fss-0002
+# fss-0002 iki-0000
#
# license: cc-by-sa-4.0
#
+# This file (assumed to be named cygwin.txt) can be more easily read using the following iki_read commands:
+# iki_read cygwin.txt +Q -w -r FLL FLL -WW character "'" "'" code '"' '"'
+#
+# To read the "Cygwin" section of this file, use this command sequence:
+# fss_basic_list_read cygwin.txt +Q -cn "Cygwin" | iki_read +Q -w -r FLL FLL -WW character "'" "'" code '"' '"'
+#
Cygwin:
- The following are a collection of informal notes on getting this to compile and run under Windows using Cygwin.
+ The following are a collection of informal notes on getting this to compile and run under bold:"Windows" using bold:"Cygwin".
I may formalize this at a later point in time.
- I have tested and was able to successfully (statically) compile and run FLL+Byte Dump under Cygwin.
- The resulting binary could be transfered to another machine and runs if the Cygwin.dll is copied with it (placed along the byte_dump.exe).
+ I have tested and was able to successfully (statically) compile and run FLL:"Featureless Linux Library" with bold:"Byte Dump" under bold:"Cygwin".
+ The resulting binary could be transfered to another machine and runs if the file:"Cygwin.dll" is copied with it (placed along the file:"byte_dump.exe").
- To compile the FLL, some functionality needs to be disabled.
- Fortunately, FLL is specifically designed to be hackable so the process is easier than it might otherwise be.
+ To compile the FLL:"Featureless Linux Library", some functionality needs to be disabled.
+ Fortunately, FLL:"Featureless Linux Library" is specifically designed to be hackable so the process is easier than it might otherwise be.
- For a monolithic build, compiled statically, add the following to "defines" in the "data/build/settings" file (of the packaged source).
- "-D_di_libcap_ -D_pthread_attr_unsupported_ -D_pthread_sigqueue_unsupported_ -D_di_f_thread_attribute_default_get_ -D_di_f_thread_attribute_default_set_ -D_di_compiler_attributes_ -DF_attribute_visibility_hidden_d -DF_attribute_visibility_internal_d -DF_attribute_visibility_protected_d -DF_attribute_visibility_public_d -DF_attribute_weak_d"
+ For a monolithic build, compiled statically, add the following to code:"defines" in the file:"data/build/settings" (of the packaged source files).
+ code:"-D_di_libcap_ -D_pthread_attr_unsupported_ -D_pthread_sigqueue_unsupported_ -D_di_f_thread_attribute_default_get_ -D_di_f_thread_attribute_default_set_ -D_di_compiler_attributes_ -DF_attribute_visibility_hidden_d -DF_attribute_visibility_internal_d -DF_attribute_visibility_protected_d -DF_attribute_visibility_public_d -DF_attribute_weak_d".
- The Cygwin system does not support special link modes, such as "-z now", so remove "-z now" from all build settings files.
+ The bold:"Cygwin" system does not support special link modes, such as code:"-z now", so remove code:"-z now" from all build settings files.
- Capabilities are likely unavailable, so remove "-lcap" from any build_libraries references.
+ Capabilities are likely unavailable, so remove code:"-lcap" from any code:"build_libraries" references.
- For thread support, it may be necessary to explicitly specify "-lpthread" in addition to "-pthread" in each of the build settings files.
+ For thread support, it may be necessary to explicitly specify code:"-lpthread" in addition to code:"-pthread" in each of the build settings files.
- Before packaging "data/build/settings", the build settings files are either found inside the individual projects or under the build directory at the root of the source repository.
+ Before packaging file:"data/build/settings", the build settings files are either found inside the individual projects or under the build directory at the root of the source repository.
- The file level_1/fl_control_group/c/control_group.c (for function fl_control_group_apply()) had to have the following changed from:
- if (unshare(CLONE_NEWCGROUP) < 0) {
- if (errno == EINVAL) return F_status_set_error(F_parameter);
- if (errno == ENOMEM) return F_status_set_error(F_memory_not);
- if (errno == ENOSPC) return F_status_set_error(F_space_not);
- if (errno == EPERM) return F_status_set_error(F_prohibited);
+ The file:"level_1/fl_control_group/c/control_group.c" (for function code:"fl_control_group_apply()") had to have the following changed from\:
+ block:
+ "if (unshare(CLONE_NEWCGROUP) < 0) {
+ if (errno == EINVAL) return F_status_set_error(F_parameter);
+ if (errno == ENOMEM) return F_status_set_error(F_memory_not);
+ if (errno == ENOSPC) return F_status_set_error(F_space_not);
+ if (errno == EPERM) return F_status_set_error(F_prohibited);
- return F_status_set_error(F_failure);
- }
- to:
- return F_status_set_error(F_supported_not);
+ return F_status_set_error(F_failure);
+ }
+ "
+ to\:
+ block:"
+ return F_status_set_error(F_supported_not);
+ "
- The file level_0/f_limit/c/limit.c (for function f_limit_process()) had to have the following changed from:
- if (prlimit(id, type, value_next, value_current) < 0) {
- if (errno == EFAULT) return F_status_set_error(F_address_not);
- if (errno == EINVAL) return F_status_set_error(F_parameter);
- if (errno == EPERM) return F_status_set_error(F_prohibited);
- if (errno == ESRCH) return F_status_set_error(F_found_not);
+ The file level_0/f_limit/c/limit.c (for function f_limit_process()) had to have the following changed from\:
+ block:"
+ if (prlimit(id, type, value_next, value_current) < 0) {
+ if (errno == EFAULT) return F_status_set_error(F_address_not);
+ if (errno == EINVAL) return F_status_set_error(F_parameter);
+ if (errno == EPERM) return F_status_set_error(F_prohibited);
+ if (errno == ESRCH) return F_status_set_error(F_found_not);
- return F_status_set_error(F_failure);
- }
+ return F_status_set_error(F_failure);
+ }
- return F_none;
- to:
- return F_status_set_error(F_supported_not);
+ return F_none;
+ "
+ to\:
+ block:"
+ return F_status_set_error(F_supported_not);
+ "
- These changes may be necessary if unshare() or prlimit() are unsupported.
+ These changes may be necessary if code:"unshare()" or code:"prlimit()" are unsupported.
There may have been other things to disable that I forgot to document.
- I do not believe I had to make any changes to compile byte_dump.
+ I do not believe I had to make any changes to compile file:"byte_dump".
- Compiling byte_dump statically against the FLL library is a bit inefficient in that it contains the entire FLL library.
- The byte_dump program only needs a portion of it.
- I may need to provide a list of everything that can be disabled to provide a smaller and more optimal byte_dump binary.
+ Compiling file:"byte_dump" statically against the FLL:"Featureless Linux Library" library is a bit inefficient in that it contains the entire FLL:"Featureless Linux Library" library.
+ The file:"byte_dump" program only needs a portion of it.
+ I may need to provide a list of everything that can be disabled to provide a smaller and more optimal file:"byte_dump" binary.
-# fss-0002
+# fss-0002 iki-0000
#
# license: cc-by-sa-4.0
#
+# This file (assumed to be named debugging.txt) can be more easily read using the following iki_read commands:
+# iki_read debugging.txt +Q -w -rrr FLL FLL GCC GCC GUI GUI -WW character "'" "'" code '"' '"'
+#
+# To read the "Debugging" section of this file, use this command sequence:
+# fss_basic_list_read debugging.txt +Q -cn "Debugging" | iki_read +Q -w -rrr FLL FLL GCC GCC GUI GUI -WW character "'" "'" code '"' '"'
+#
Debugging:
There are various tools out there to assist in investigating for problems and debugging the compiled code.
This documentation briefly touches on a small set of these used by this project.
The following are notable tools to consider when debugging\:
- - strace
- - gdb
- - valgrind
- - GCC's -fanalyzer (and CLang's equivalent)
- - massif-visualizer
- - valkyrie
+ - file:"strace".
+ - file:"gdb"
+ - file:"valgrind".
+ - GCC:"GNU Compile Collection"'s code:"-fanalyzer" (and bold:"CLang"'s equivalent).
+ - file:"massif-visualizer".
+ - file:"valkyrie".
Valgrind:
- The "valgrind" program has three important tools:
+ The file:"valgrind" program has three important tools\:
1) The default tool, which is to check for memory leaks.
- 2) The thread anyalzing tool called "helgrind".
- 3) The heap usage analyzing tool called "massif".
+ 2) The thread anyalzing tool called code:"helgrind".
+ 3) The heap usage analyzing tool called code:"massif".
- The default behavior shows memory leaks when run against a program (such as fake), a messages like the following are desired\:
- - "in use at exit: 0 bytes in 0 blocks".
- - "All heap blocks were freed -- no leaks are possible".
+ The default behavior shows memory leaks when run against a program (such as file:"fake"), a messages like the following are desired\:
+ - code:"in use at exit: 0 bytes in 0 blocks".
+ - code:"All heap blocks were freed -- no leaks are possible".
- The "..total heap usage" is just that a total heap usage throughout the lifespan of the program.
- This does not represent the total usage at any moment in time (for that look into massif).
+ The code:"..total heap usage" is just that a total heap usage throughout the lifespan of the program.
+ This does not represent the total usage at any moment in time (for that look into code:"massif").
Example execution\:
- valgrind fake make
+ block:"
+ valgrind fake make
+ "
- The thread analyzing tool called "helgrind" is described in the "threads.txt" documentation given that it is thread-focused.
+ The thread analyzing tool called code:"helgrind" is described in the file:"threads.txt" documentation given that it is thread-focused.
- The heap usage analyzing tool called "massif" is a helpful in identifying situations where the compiled code is using large amounts of memory.
- A massif file is generated on exit and a good tool for visualizng this is called "massif-visualizer".
+ The heap usage analyzing tool called code:"massif" is a helpful in identifying situations where the compiled code is using large amounts of memory.
+ A code:"massif" file is generated on exit and a good tool for visualizng this is called code:"massif-visualizer".
Example execution\:
- valgrind --tool=massif fake make
- massif-visualizer massif.out.1234
+ block:"
+ valgrind --tool=massif fake make
+ massif-visualizer massif.out.1234
+ "
- A GUI that is helpful in using valgrind is called "valkyrie".
- The "valkyrie" program does not support massif at the time of this writing but it eventually may.
- The "valkyrie" program does support the default valgrind tool and the helgrind tools.
+ A GUI:"Graphical User Interface" that is helpful in using valgrind is called file:"valkyrie".
+ The file:"valkyrie" program does not support code:"massif" at the time of this writing but it eventually may.
+ The file:"valkyrie" program does support the default file:"valgrind" tool and the helgrind tools.
- When working with valgrind's massif tool, several libc functions (or other functions external to this project) may get in the way of the analysis.
+ When working with code:"valgrind"'s code:"massif" tool, several libc functions (or other functions external to this project) may get in the way of the analysis.
These functions should be disabled.
- Example valgrind massif execution disabling some common GLibc functions:
- valgrind --tool=massif --ignore-fn=_IO_file_doallocate --ignore-fn=ftw_startup --ignore-fn=__alloc_dir fake clean build
+ Example code:"valgrind" code:"massif" execution disabling some common bold:"GLibc" functions\:
+ block:"
+ valgrind --tool=massif --ignore-fn=_IO_file_doallocate --ignore-fn=ftw_startup --ignore-fn=__alloc_dir fake clean build
+ "
-GCC's -fanalyzer (and CLang's equivalent):
- The code analyzer provided by GCC (and also CLang, through similar means) attempts to determine insecure or otherwise bad coding practices.
+GCC:"GNU Compile Collection"'s code:"-fanalyzer" (and bold:"CLang"'s equivalent)\:
+ The code analyzer provided by GCC:"GNU Compile Collection" (and also bold:"CLang", through similar means) attempts to determine insecure or otherwise bad coding practices.
- This focuses on the GCC -fanalyzer.
+ This focuses on the GCC:"GNU Compile Collection" code:"-fanalyzer".
- The analyzer is easily enabled by just appending "-fanalyzer" to the "flags" in data/build/settings or directly passing "-fanalyzer" to the gcc command.o
+ The analyzer is easily enabled by just appending code:"-fanalyzer" to the bold:"flags" in file:"data/build/settings" or directly passing code:"-fanalyzer" to the code:"gcc command.o".
-# fss-0002
+# fss-0002 iki-0000
#
# license: cc-by-sa-4.0
#
+# This file (assumed to be named disabling_functions.txt) can be more easily read using the following iki_read commands:
+# iki_read disabling_functions.txt +Q -w -rr API API FLL FLL -WW character "'" "'" code '"' '"'
+#
+# To read the "Disabling Functions" section of this file, use this command sequence:
+# fss_basic_list_read disabling_functions.txt +Q -cn "Disabling Functions" | iki_read +Q -w -rr API API FLL FLL -WW character "'" "'" code '"' '"'
+#
Disabling Functions:
- The Featureless Linux Library is designed in a modular fassion despite the primary language not being an object-oriented language.
- This is loosely refered to as emphasis:"functional-oriented programming".
+ The FLL:"Featureless Linux Library" is designed in a modular fassion despite the primary language not being an object-oriented language.
+ This is loosely refered to as italic:"functional-oriented programming".
The resulting library can, and should, be trimmed down to contain only what is needed.
There are two ways this is done\:
- 1) The abbreviation:"FLL" is broken up into individual projects and can be perceived as a conceptial emphasis:"class object".
+ 1) The FLL:"Featureless Linux Library" is broken up into individual projects and can be perceived as a conceptial italic:"class object".
2) Each individual public function within each project is wrapped in if-def logic to designate that this function is to be disabled.
- This approach allows for someone to override the existing function by easily replacing the abbreviation:"FLL" function with their own.
+ This approach allows for someone to override the existing function by easily replacing the FLL:"Featureless Linux Library" function with their own.
This also allows for removing, or disabling, functions entirely.
The focus of this is on the disabling of functions.
- Each public function has its abbreviation:"API" exposed via a header file.
+ Each public function has its API:"Application Programming Interface" exposed via a header file.
This header file describes the list of public functions that are available.
Looking at each header file, one can find each function is wrapped in special ifdef macros.
The macros are of the form code:"_di_XXX_" where code:"XXX" represents the function name.
The code:"-D_di_f_file_access_" can be added to the code:"data/build/settings" file like this: code:"defines -D_di_f_file_access_".
One good use of this is to disable all of the functions that are not needed for some environment.
- Lets say that only the Featureless Make program is needed.
- All other functions in the abbreviation:"FLL" can be removed.
+ Lets say that only the bold:"Featureless Make" program is needed.
+ All other functions in the FLL:"Featureless Linux Library" can be removed.
The compiled binaries should be analyzed and the dependencies can be extracted.
- Something like the following needs to be done to get the list of functions from the bold:"fake" program\:
+ Something like the following needs to be done to get the list of functions from the file:"fake" program\:
script:"
rm -f unsorted.txt ; nm -Dgu -f p libfake.so | grep -oP '^(f|fl|fll)_[^\s]+' | sed -e '/_s$/d' -e '/_c$/d' >> unsorted.txt
sort unsorted.txt | uniq > sorted.txt
-# fss-0002
+# fss-0002 iki-0000
#
# license: cc-by-sa-4.0
#
+# This file (assumed to be named lossy_allocation.txt) can be more easily read using the following iki_read commands:
+# iki_read lossy_allocation.txt +Q -w -r FLL FLL -WW character "'" "'" code '"' '"'
+#
+# To read the "Lossy Allocation" section of this file, use this command sequence:
+# fss_basic_list_read lossy_allocation.txt +Q -cn "Lossy Allocation" | iki_read +Q -w -r FLL FLL -WW character "'" "'" code '"' '"'
+#
Lossy Allocation:
- The Featureless Linux Library and related projects utilize what is called bold:"Lossy Allocation".
+ The FLL:"Featureless Linux Library" and related projects utilize what is called bold:"Lossy Allocation".
- One of the original theories behind the Featureless Linux Library (and Featureless Make) is that of memory allocations being expensive.
+ One of the original theories behind the FLL:"Featureless Linux Library" (and bold:"Featureless Make") is that of memory allocations being expensive.
The original theory asserted that performing three allocations when a single is requested can improve performance while maintaining a minimal amount of memory waste.
This behavior is termed bold:"Lossy Allocation".
Over time this theory has proven to not only be correct but also an understatement.
The project now chooses a default allocation size of eight rather than three.
This has a more significant cost in memory but the overall performance gain and resource usage appears to provide more benefits than the losses from over-allocating memory.
- The Featureless Linux Library attempts to only allocate memory when needed and this results in the memory footprint being as small as possible when ignoring the lossy aspects.
+ The FLL:"Featureless Linux Library" attempts to only allocate memory when needed and this results in the memory footprint being as small as possible when ignoring the lossy aspects.
There are cases where there is expected to be a large buffer allocated rather than a small buffer allocation.
This is often the case when loading and processing files.
-# fss-0002
+# fss-0002 iki-0000
#
# license: cc-by-sa-4.0
#
+# This file (assumed to be named private_functions.txt) can be more easily read using the following iki_read commands:
+# iki_read private_functions.txt +Q -w -rr FLL FLL GCC GCC -WW character "'" "'" code '"' '"'
+#
+# To read the "Private Functions" section of this file, use this command sequence:
+# fss_basic_list_read private_functions.txt +Q -cn "Private Functions" | iki_read +Q -w -rr FLL FLL GCC GCC -WW character "'" "'" code '"' '"'
+#
Private Functions:
One of the objectives of this project is to make as much, if not all, of the functions available for use.
One of those disadvantages is possible redundant code.
The c-programming language does not have private functions by any normal means.
- The use of the f_gcc_attribute_visibility_internal helps simulate private functions.
- Such functionality only works in supporting GCC compilers.
+ The use of the code:"f_gcc_attribute_visibility_internal" helps simulate private functions.
+ Such functionality only works in supporting GCC:"GNU Compiler Collection" compilers.
These synthetic private functions are implemented as an exception to the objectives for maintainability and redundancy purposes.
Such implementations should be kept to a bare minimum.
Functions defined as private will not be normally exposed through the public headers files.
- Such functions will be prefixed with 'private_'.
+ Such functions will be prefixed with code:"private_".
- The header files and source files for these private functions will be prefixed with "private-".
- Normally, this product uses underscores for names, but, as a special name, the dash "-" is used.
- Normally, the names begin with the project name (such as directory_type.h instead of type_directory.h), but as a special case to further separate private files, this is prefixed onto source files (such as private-directory.h).
+ The header files and source files for these private functions will be prefixed with code:"private-".
+ Normally, this product uses underscores character:"_" (unicode:"U+005F") for names, but, as a special name, the dash chararacter:"-" (unicode:"U+002D") is used.
+ Normally, the names begin with the project name (such as file:"directory_type.h" instead of file:"type_directory.h"), but as a special case to further separate private files, this is prefixed onto source files (such as file:"private-directory.h").
-# fss-0002
+# fss-0002 iki-0000
#
# license: cc-by-sa-4.0
#
+# This file (assumed to be named readme.txt) can be more easily read using the following iki_read commands:
+# iki_read readme.txt +Q -w -r FLL FLL -WW character "'" "'" code '"' '"'
+#
+# To read the "Installation" section of this file, use this command sequence:
+# fss_basic_list_read readme.txt +Q -cn "Installation" | iki_read +Q -w -r FLL FLL -WW character "'" "'" code '"' '"'
+#
# This readme file is inteded to provide a basic introduction to the Featureless Linux Library (FLL).
#
Installation:
- The FLL provides two installation types\:
+ The FLL:"Featureless Linux Library" provides two installation types\:
- The management scripts.
- The Featureless Make program.
The management scripts provide a way to manage the source code, such as updating dependencies, constructing the souce code for release, and bootstrap compiling the system.
- The bootstrap compiling provides a way to build and compile the entire FLL project, without the Featureless Make (Fake) program.
- This bootstrap process solves the problem where if you don't already have Fake installed, then you cannot install Fake.
- These bootstrap scripts are written in GNU Bash.
+ The bootstrap compiling provides a way to build and compile the entire FLL:"Featureless Linux Library" project, without the file:"fake" program (bold:"Featureless Make").
+ This bootstrap process solves the problem where if you don't already have bold:"Featureless Make" installed, then you cannot install bold:"Featureless Make".
+ These bootstrap scripts are written in bold:"GNU Bash".
- The source code needs to be packaged before it can be compiled by either the bootstrap scripts or by the Fake program.
+ The source code needs to be packaged before it can be compiled by either the bootstrap scripts or by the bold:"Featureless Make" program.
- The Fake program is neither intended nor designed to be used as an installer, so the bootstrap scripts also provide an install script written in GNU Bash.
- This install script is intended to be used only by the FLL.
- Future versions of the FLL may include an install equivalent to the Fake program (and there may possibly be a package generation equivalent as well).
+ The bold:"Featureless Make" program is neither intended nor designed to be used as an installer, so the bootstrap scripts also provide an install script written in bold:"GNU Bash".
+ This install script is intended to be used only by the FLL:"Featureless Linux Library".
+ Future versions of the FLL:"Featureless Linux Library" may include an install equivalent to the file:"fake" program (and there may possibly be a package generation equivalent as well).
The management scripts are as follows\:
- - bootstrap.sh
- - bootstrap-example.sh
- - install.sh
- - package.sh
+ - file:"bootstrap.sh".
+ - file:"bootstrap-example.sh".
+ - file:"install.sh".
+ - file:"package.sh".
- The bootstrap.sh script is intended to take the FLL source code and compile it into appropriate binaries on the system, particularly when the Fake program is not installed.
- This is analogous to the GNU Make program and the FLL Fake program.
+ The file:"bootstrap.sh" script is intended to take the FLL:"Featureless Linux Library" source code and compile it into appropriate binaries on the system, particularly when the file:"fake" program is not installed.
+ This is analogous to the bold:"GNU Make" program and the FLL:"Featureless Linux Library" bold:"Featureless Make" program.
- The bootstrap-example.sh script is intended to be a functional example of the command line arguments that should be used to generate, compile, and install the entire FLL.
+ The file:"bootstrap-example.sh" script is intended to be a functional example of the command line arguments that should be used to generate, compile, and install the entire FLL:"Featureless Linux Library".
- The install.sh script is intended to install the built and compiled FLL code onto the system.
+ The file:"install.sh" script is intended to install the built and compiled FLL:"Featureless Linux Library" code onto the system.
This script very loosely follows a small amount of the logic of the standard configure scripts.
- The package.sh script is intended to convert the FLL source code from the source code repository structure into a packaged or release.
- Of particular note is that there are multiple ways to package the FLL, such as each package as its own individual project, each package by level, or each package as a monolithic library.
+ The file:"package.sh" script is intended to convert the FLL:"Featureless Linux Library" source code from the source code repository structure into a packaged or release.
+ Of particular note is that there are multiple ways to package the FLL:"Featureless Linux Library", such as each package as its own individual project, each package by level, or each package as a monolithic library.
This script also provides management functions for ensuring the dependencies and configuration settings are accurate.
Other Readmes:
- Repository providers like Github and Gitlab utilize README.md, LICENSE, and other special files at the root project level.
- This practice is not supported by the FLL project structure and is not normally used.
+ Repository providers like bold:"Github" and bold:"Gitlab" utilize file:"README.md", file:"LICENSE", and other special files at the root project level.
+ This practice is not supported by the FLL:"Featureless Linux Library" project structure and is not normally used.
Instead, these are provided only on special branches intended exclusively to be used for the appropriate repository provider.
These readmes and related files are intended to document the project within the scope of the repository provider and usually a particular release version.
-# fss-0002
+# fss-0002 iki-0000
#
# license: cc-by-sa-4.0
#
+# This file (assumed to be named return_codes.txt) can be more easily read using the following iki_read commands:
+# iki_read return_codes.txt +Q -w -rr API API FLL FLL -WW character "'" "'" code '"' '"'
+#
+# To read the "Implicit Return Types for f_status_t" section of this file, use this command sequence:
+# fss_basic_list_read return_codes.txt +Q -cn "Implicit Return Types for f_status_t" | iki_read +Q -w -rr API API FLL FLL -WW character "'" "'" code '"' '"'
+#
Implicit Return Types for f_status_t:
- When f_status_t is used as the return type, there are a common set of status codes that should always be expected as a possible return value.
+ When code:"f_status_t" is used as the return type, there are a common set of status codes that should always be expected as a possible return value.
These are implicit expectations even if they are not explicitly documented.
Any function that doesn't support these must document the exceptional state.
- F_failure\:
+ code:"F_failure"\:
This may be returned for any general error.
This is often used as the failsafe error code so that an error code of some sort is always returned on error.
- F_parameter\:
+ code:"F_parameter"\:
This is always potentially returned for any function whose parameter requires a validity checked.
- Much of this functionality can be optionally disabled, but the client using the API need not be aware.
+ Much of this functionality can be optionally disabled, but the client using the API:"Application Programming Interface" need not be aware.
- F_implemented_not\:
+ code:"F_implemented_not"\:
This is used to designate that the function or some part of the function is not supported.
- This is primarily used by individuals altering the project but maintaing API compatibility.
- Any function must therefore support returning F_implemented_not.
+ This is primarily used by individuals altering the project but maintaing API:"Application Programming Interface" compatibility.
+ Any function must therefore support returning code:"F_implemented_not".
There are some projects that can be enabled/disabled such as f_capability and f_threads.
- These should explicitly document returning F_implemented_not.
+ These should explicitly document returning code:"F_implemented_not".
Common Return Types for f_status_t:
- There are some f_status_t return types that are not required to be returned but are used quite often that they might seem required.
+ There are some code:"f_status_t" return types that are not required to be returned but are used quite often that they might seem required.
- F_none\:
+ code:"F_none"\:
This general designates that no error occurred.
This is a generic status code used all over the place.
- F_memory_not\:
+ code:"F_memory_not"\:
This general designates that the operation ran out of memory.
This is a generic status code used all over the place.
-# fss-0002
+# fss-0002 iki-0000
#
# license: cc-by-sa-4.0
#
+# This file (assumed to be named style_guide.txt) can be more easily read using the following iki_read commands:
+# iki_read style_guide.txt +Q -w -rrr ABI ABI API API FLL FLL -WW character "'" "'" code '"' '"'
+#
+# To read the "Style Guide" section of this file, use this command sequence:
+# fss_basic_list_read style_guide.txt +Q -cn "Style Guide" | iki_read +Q -w -rrr ABI ABI API API FLL FLL -WW character "'" "'" code '"' '"'
+#
Style Guide:
- The Featureless Linux Library uses a set of styles and practices designed in hopes to communicate both explicitly and implicitly multiple meanings and contexts.
+ The FLL:"Featureless Linux Library" uses a set of styles and practices designed in hopes to communicate both explicitly and implicitly multiple meanings and contexts.
The idea is that code should be readable like a story rather than be a mash of characters jumbled together into as few lines as possible.
This design has a tendency to go against the norm given that longer lines (such as 120 characters or more) may be common.
All files, programs, functions, and comments that have specific meaning follow this general naming structure.
This structure may be similar to camel-casing or snake-casing, but it is not nor is it intended to match them.
- These special names may only contain word characters, underscore "_", and dash "-".
+ These special names may only contain word characters, underscore character:"_" (unicode:"U+005F"), and dash character:"-" (unicode:"U+002D").
- The underscore "_" and dash "-" are explicitly intended to communicate separation of context or not.
+ The underscore character:"_" (unicode:"U+005F") and dash character:"-" (unicode:"U+002D") are explicitly intended to communicate separation of context or not.
The underscore character represents a space separating multiple words, logic, concepts, or ideas represented by the previous words and should share meaning.
The dash character represents a break in the words, logic, concepts, or ideas.
- In the event that a dash cannot be used, fall back to an underscore.
- In the event that an underscore cannot be used, fall back to a dash.
- In the event that both underscore and dash cannot be used, it is fine to have neither.
- - For software that uses plus "+", it may become necessary to replace the dash with the plus, but this should be avoided.
+ - For software that uses plus character:"+" (unicode:"U+002B"), it may become necessary to replace the dash with the plus, but this should be avoided.
- Other language-specific (compiler languages, spoken languages, written languages, etc..) restrictions may apply that prevent or alter this style.
In general, these special names should always be lower case and this is encouraged.
The use of upper case is not forbidden and is encouraged to be used for special communication or language-specific purposes.
- Consider the following to better understand how and when to use the underscore and dash to implicitly communicate context\:
- Take the words "my", "red", "cat", "dog", and "apple".
+ Consider the following to better understand how and when to use the underscore character:"_" (unicode:"U+005F") and dash character:"-" (unicode:"U+002D") to implicitly communicate context\:
+ Take the words italic:"my", italic:"red", italic:"cat", italic:"dog", and italic:"apple".
- If you wanted to communicate that the structure of a document is focused on "my red X", then you can use the following naming structure to communicate this\:
- 1) my_red-cat, my_red-dog, my_red-apple.
+ If you wanted to communicate that the structure of a document is focused on code:"my red X", then you can use the following naming structure to communicate this\:
+ 1) code:"my_red-cat, my_red-dog, my_red-apple".
- If you wanted, instead, to communicate that the structure is focused on "my X", then you can use the following naming structure to communicate this\:
- 2) my-red_cat, my-red_dog, my-red_apple.
+ If you wanted, instead, to communicate that the structure is focused on code:"my X", then you can use the following naming structure to communicate this\:
+ 2) code:"my-red_cat, my-red_dog, my-red_apple".
By following this logic, another person can more easily identify your logic and make changes or fixes.
Let us say that somebody wants to add "happy" to the context\:
+ 1) This can become: code:"my_red-happy_cat, my_red-happy_dog, my_red-apple".
+ 2) This can become: code:"my-happy_cat, my-happy_dog, my-red_apple".
- 1) This can become: my_red-happy_cat, my_red-happy_dog, my_red-apple.
- 2) This can become: my-happy_cat, my-happy_dog, my-red_apple.
-
- The person who added "happy" might have fixed a situation where there is no red cat or dog and while understanding that there is no happy apple.
- However, in case (1) because "my_red" is grouped together by the underscore, it is clear that there is a "my_red" must be preserved and there is red cat and red dog, so happy is added to the cat and dog but not the apple without removing the "red".
+ The person who added code:"happy" might have fixed a situation where there is no red cat or dog and while understanding that there is no happy apple.
+ However, in case italic:"(1)" because code:"my_red" is grouped together by the underscore, it is clear that there is a code:"my_red" must be preserved and there is red cat and red dog, so happy is added to the cat and dog but not the apple without removing the code:"red".
Purpose of Defines:
There are several types of defines, often wrapped in code:"#ifndef" blocks, for both communicating a type of define and the purpose of the define.
This project requires that, so long as it is allowed by the language (in terms of valid syntax, etc..), items in a list must always end in a comma.
Example Grammatically Correct Way\:
- - char list[] = {
- 'a',
- 'b',
- 'c'
- };
-
- Example FLL Correct Way\:
- - char list[] = {
- 'a',
- 'b',
- 'c',
- };
+ block:"
+ char list[] = {
+ 'a',
+ 'b',
+ 'c'
+ };
+ "
+
+ Example FLL:"Featureless Linux Library" Correct Way\:
+ block:"
+ char list[] = {
+ 'a',
+ 'b',
+ 'c',
+ };
+ "
Loops and Newlines:
All loops, except loops with only 0 or 1 lines within it, add an extra new line after the loop condition part (or before the loop condition part for post-increment loops).
- All pre-increment loops will have their loop type (such as "while", or "for") in a comment inline with the closing brace.
+ All pre-increment loops will have their loop type (such as code:"while", or code:"for") in a comment inline with the closing brace.
- A for loop would like like\:
- for (int x = 0; x < y; ++x) {
+ A code:"for" loop would like like\:
+ block:"
+ for (int x = 0; x < y; ++x) {
- do_something();
- do_something_else();
- } // while
+ do_something();
+ do_something_else();
+ } // while
+ "
- A do while loop would like like\:
- do {
- do_something();
- do_something_else();
+ A code:"do while" loop would like like\:
+ block:"
+ do {
+ do_something();
+ do_something_else();
- } while (true);
+ } while (true);
+ "
Returns, Breaks, Continues, Gotos, and Newlines:
Operations that change the flow of a block or a function must have a newline before them, except in certain conditions.
- This includes "return" statements, "break" statements, "continue" statements, and "goto" statements.
+ This includes code:"return" statements, code:"break" statements, code:"continue" statements, and code:"goto" statements.
Exceptions to this includes one line flow change operations directly tied to a function called before it.
These are meant to be treated as an accessory to the function.
Return Code Names:
The return code names are C-language specific names used by this project as the status or return codes for functions and programs.
- To uniquely identify these, they follow the naming structure "(A)_(b)", where "(A)" is replaced with an upper-case character representing the project level (or name) and "(b)" is replaced with the lower-case status code name using words that are underscore separated.
+ To uniquely identify these, they follow the naming structure code:"(A)_(b)", where code:"(A)" is replaced with an upper-case character representing the project level (or name) and code:"(b)" is replaced with the lower-case status code name using words that are underscore separated.
These are enumerations but they do not follow the enumeration style guide and are an exception to it.
Examples\:
- - F_none
- - F_signal_file_size_limit
+ - code:"F_none".
+ - code:"F_signal_file_size_limit".
Global String Constant Names:
The C-language specific global names are used in two ways\:
1) Via a define (macro).
2) As a variable at the global scope.
- These follow the naming structure "(A)_(b)_s" or "(a)_(b)_s".
- The "(A)" represents upper-case characters used for the project level (or similar purposes).
- The "(a)" represents lower-case characters used for the project level (or similar purposes).
- The "(b)" represents lower-case characters used for the name.
+ These follow the naming structure code:"(A)_(b)_s" or code:"(a)_(b)_s".
+ The code:"(A)" represents upper-case characters used for the project level (or similar purposes).
+ The code:"(a)" represents lower-case characters used for the project level (or similar purposes).
+ The code:"(b)" represents lower-case characters used for the name.
- The trailing "_s" designates that this is a string.
+ The trailing code:"_s" designates that this is a string.
The upper-case variant is to be used for the defines.
The lower-case variant is to be used for the variables, such as global consant strings.
Replacement macros may use eithe depending on which of these they are replacing and the way in which they are performing the replacement.
- A special case define that describes the length of the string is of the forms: (A)_(b)_s_length.
+ A special case define that describes the length of the string is of the forms: code:"(A)_(b)_s_length".
Examples\:
- - F_file_open_mode_truncate_s: as a define, such as: #define F_file_open_mode_truncate_s "w".
- - F_file_open_mode_truncate_s_length: as a define, such as: #define F_file_open_mode_truncate_s_length 1.
- - f_file_open_mode_truncate_s: as a variable, such as: extern const f_string_t f_file_open_mode_truncate_s;.
+ - code:"F_file_open_mode_truncate_s": as a define, such as: code:'#define F_file_open_mode_truncate_s "w"'.
+ - code:"F_file_open_mode_truncate_s_length": as a define, such as: code:'#define F_file_open_mode_truncate_s_length 1'.
+ - code:"f_file_open_mode_truncate_s": as a variable, such as: code:"extern const f_string_t f_file_open_mode_truncate_s;".
Global Character Constant Names:
- The C-language specific global names are identical to the "Global String Constant Names" except that they represent a single 1-byte character.
+ The C-language specific global names are identical to the strong:"Global String Constant Names" except that they represent a single 1-byte character.
- These are of the form "(A)_(b)_c" or "(a)_(b)_c".
+ These are of the form code:"(A)_(b)_c" or code:"(a)_(b)_c".
- The trailing "_c" designates that this is a 1-byte character.
+ The trailing code:"_c" designates that this is a 1-byte character.
Enumeration Names:
- The C-language specific enumeration names follow the naming structure "(a)_(b)_e".
- The "(a)" represents lower-case characters used for the project level (or similar purposes).
- The "(b)" represents lower-case characters used for the name.
+ The C-language specific enumeration names follow the naming structure code:"(a)_(b)_e".
+ The code:"(a)" represents lower-case characters used for the project level (or similar purposes).
+ The code:"(b)" represents lower-case characters used for the name.
- The trailing "_e" designates that this is an enumeration.
+ The trailing code:"_e" designates that this is an enumeration.
Examples\:
- - f_console_verbosity_quiet_e
- - f_fss_basic_e
- - fss_extended_list_read_parameter_at_e
+ - code:"f_console_verbosity_quiet_e".
+ - code:"f_fss_basic_e".
+ - code:"fss_extended_list_read_parameter_at_e".
Wrapping Define Names:
Most, if not all, of the code that follows this style guide is to be wrapped in some sort of define.
- These are formally referred to as Wrapping Defines or Wrapping Define Names.
+ These are formally referred to as bold:"Wrapping Defines" or bold:"Wrapping Define Names".
These C-language specific define names (also known as macro names) used for wrapping always begin and end in an underscore.
1) The disable wrapping define name (this is the most common).
2) The enable wrapping define name (this is for special cases or less common cases).
- The format for the disable wrapping defines is "_di_(a)_(b)_".
- The "(a)" is replaced with the name representing the block that is being wrapped.
- The "(b)" represents the type of the wrapping define, which may already be provided by "(a)" (as with types, the "f_string_t" typedef would have a wrapping define name of "_di_f_string_t_".
- This macro must be explicitly defined to "disable" the wrapped block, such as passing "-D_di_f_string_t_" to the compiler.
- These are commonly used with an "#ifndef" block.
+ The format for the disable wrapping defines is code:"_di_(a)_(b)_".
+ The code:"(a)" is replaced with the name representing the block that is being wrapped.
+ The code:"(b)" represents the type of the wrapping define, which may already be provided by code:"(a)" (as with types, the code:"f_string_t" typedef would have a wrapping define name of code:"_di_f_string_t_".
+ This macro must be explicitly defined to italic:"disable" the wrapped block, such as passing code:"-D_di_f_string_t_" to the compiler.
+ These are commonly used with an code:"#ifndef" block.
- The format for the enable wrapping defines is "_en_(a)_(b)_".
- This is exactly the same as the disable wrapping define, except it has "en" instead of "di".
- This macro must be explicitly defined to "enable" the wrapped block, such as passing "-D_en_f_type_number_32_t_" to the compiler.
+ The format for the enable wrapping defines is code:"_en_(a)_(b)_".
+ This is exactly the same as the disable wrapping define, except it has code:"en" instead of code:"di".
+ This macro must be explicitly defined to italic:"enable" the wrapped block, such as passing code:"-D_en_f_type_number_32_t_" to the compiler.
- Both the enable and disable types must end in an "#endif" block that has the comment representing the block, such as "#endif // _di_fl_print_format_".
+ Both the enable and disable types must end in an code:"#endif" block that has the comment representing the block, such as code:"#endif // _di_fl_print_format_".
This helps encourages the concept of using these when passing them as arguments.
- A wrapping define name such as -D_di_fl_print_format_ would be the wrapping define name for the function fl_print_format().
+ A wrapping define name such as code:"-D_di_fl_print_format_" would be the wrapping define name for the function code:"fl_print_format()".
Constant Define Names:
- The define names representing the C-language specific define names (also known as macro names) used to represent constant data follow the naming structure "(A)_(b)_(c).
- The "(A)" represents upper-case characters representing the project level (or something similar).
- The "(b)" represents lower-case characters using words, function names, structure names, or category names that are underscore separated.
- The "(c)" represents lower-case type-description character, such as "_d", "_c", or "_s".
+ The define names representing the C-language specific define names (also known as macro names) used to represent constant data follow the naming structure code:"(A)_(b)_(c)".
+ The code:"(A)" represents upper-case characters representing the project level (or something similar).
+ The code:"(b)" represents lower-case characters using words, function names, structure names, or category names that are underscore separated.
+ The code:"(c)" represents lower-case type-description character, such as code:"_d", code:"_c", or code:"_s".
Examples\:
- - F_file_mode_special_sticky_d
- - F_attribute_visibility_internal_d
- - FL_diectory_recurse_depth_max_d
- - FAKE_program_name_s
+ - code:"F_file_mode_special_sticky_d".
+ - code:"F_attribute_visibility_internal_d".
+ - code:"FL_diectory_recurse_depth_max_d".
+ - code:"FAKE_program_name_s".
Header Define Names:
- The header define are used to wrap the header file and are of the form "_(a)_(b)_h".
- The "(a)" represents lower-case characters representing the project level (or something similar).
- The "(b)" represents lower-case characters representing the file name without the extenson and dashes.
+ The header define are used to wrap the header file and are of the form code:"_(a)_(b)_h".
+ The code:"(a)" represents lower-case characters representing the project level (or something similar).
+ The code:"(b)" represents lower-case characters representing the file name without the extenson and dashes.
- Do not forget the leading "_".
- The trailing "_h" designates that this is a header file name define.
+ Do not forget the leading code:"_".
+ The trailing code:"_h" designates that this is a header file name define.
Macro Replacement Names:
- All C-language specific define names defines are considered macro names but for the purpose of this style guide the ones that are formally considered macros are prefixed with "macro_".
+ All C-language specific define names defines are considered macro names but for the purpose of this style guide the ones that are formally considered macros are prefixed with code:"macro_".
These macro defines represent the traditional concept and use of a macro and are most often used to represent a macro function.
These macro defines are intended to simulate functions and therefore follow the naming styles similar to that of functions.
- The "Type Definition Names" section describs the naming of this in details.
+ The bold:"Type Definition Names" section describs the naming of this in details.
Type Definition Names:
- The C-language specific type definition names follow the naming structure "(a)_(b)_t".
- The "(a)" represents lower-case characters representing the project level (or something similar).
- The "(b)" represents lower-case characters representing the name using words that are underscore separated.
+ The C-language specific type definition names follow the naming structure code:"(a)_(b)_t".
+ The code:"(a)" represents lower-case characters representing the project level (or something similar).
+ The code:"(b)" represents lower-case characters representing the name using words that are underscore separated.
- The trailing "_t" designates that this is a type definition.
+ The trailing code:"_t" designates that this is a type definition.
In addition to the type definition, special defines (macros) are provided that are specific to type definitions are an exception to the Define Names rules.
- - Each type definition should have an initializer and that initializer name follows the naming structure "(a)_(b)_t_initialize" where "_initialize" is appended to the type definition name.
+ - Each type definition should have an initializer and that initializer name follows the naming structure code:"(a)_(b)_t_initialize" where code:"_initialize" is appended to the type definition name.
- Each type definition may have special defines (macros) used as functions for helping with special operations such as complex initialization, allocation, and deallocation.
- These special case defines are an exception to the Define Name rules and follow the naming structure "macro_(a)_(b)_t_(c)" where "macro_" is prepended to the type definition name and the (c) is just like (b) but is used to communicate the special purpose.
+ These special case defines are an exception to the Define Name rules and follow the naming structure code:"macro_(a)_(b)_t_(c)" where code:"macro_" is prepended to the type definition name and the code:"(c)" is just like code:"(b)" but is used to communicate the special purpose.
Examples\:
- - f_string_static_t
- - f_status_t
- - macro_f_account_t_clear
- - macro_f_string_dynamic_t_resize
+ - code:"f_string_static_t".
+ - code:"f_status_t".
+ - code:"macro_f_account_t_clear".
+ - code:"macro_f_string_dynamic_t_resize".
Function Names:
- The C-language specific function names follow the naming structure "(a)_(b)" or "private_(a)_(b)", where "(a)" is replaced with an lower-case character representing the project level (or name) and "(b)" is replaced with the lower-case name using words that are underscore separated.
+ The C-language specific function names follow the naming structure code:"(a)_(b)" or code:"private_(a)_(b)", where code:"(a)" is replaced with an lower-case character representing the project level (or name) and code:"(b)" is replaced with the lower-case name using words that are underscore separated.
- The leading "private_" is used to designate that this is a private function.
+ The leading code:"private_" is used to designate that this is a private function.
There are also special practices.
- - For FLL projects, each project has a level.
- Each project within some level is prepended to functions with their level representation characters of: "f" (level 0), "fl" (level 1), and "fll" (level 2).
+ - For FLL:"Featureless Linux Library" projects, each project has a level.
+ Each project within some level is prepended to functions with their level representation characters of: code:"f" (level 0), code:"fl" (level 1), and code:"fll" (level 2).
- For programs, each program has a project name.
The program name, or a short alias of the program name, is prepended to functions.
- - For programs, the "main" function does not do this and is always called "main" without modification.
+ - For programs, the code:"main" function does not do this and is always called code:"main" without modification.
Examples\:
- - f_fss_basic_e
- - fl_conversion_string_to_binary_signed
- - fake_print_help
+ - code:"f_fss_basic_e".
+ - code:"fl_conversion_string_to_binary_signed".
+ - code:"fake_print_help".
File Names:
The C-language specific file names follow the simple naming structure utilizing word characters, underscores, and dashes.
- Special cases will have prefixes, such a "private-".
+ Special cases will have prefixes, such a code:"private-".
- The "private-" special case is intended for private files (aka: not intended to be exposed via the API or ABI).
+ The code:"private-" special case is intended for private files (aka: not intended to be exposed via the API:"Application Programming Interface" or ABI:"Application Binary Interface").
Returns, Breaks, Continues, and Gotos Function Accessories:
To avoid excessive newline spacing, certain one-line operations that are tightly coupled to a function are treated as an accessory to the function.
As an accessory to some function, these one-line operations must not have a line between them and the function that they are an accessory of unless there is an excessive amount.
These function accessories are operations that change the flow of a block or a function.
- This includes "return" statements, "break" statements, "continue" statements, and "goto" statements.
+ This includes code:"return" statements, code:"break" statements, code:"continue" statements, and code:"goto" statements.
-# fss-0002
+# fss-0002 iki-0000
#
# license: cc-by-sa-4.0
#
+# This file (assumed to be named threads.txt) can be more easily read using the following iki_read commands:
+# iki_read threads.txt +Q -w -r FLL FLL -WW character "'" "'" code '"' '"'
+#
+# To read the "Threads Documentation" section of this file, use this command sequence:
+# fss_basic_list_read threads.txt +Q -cn "Threads Documentation" | iki_read +Q -w -r FLL FLL -WW character "'" "'" code '"' '"'
+#
Threads Documentation:
- With the inclusion of the f_thread project, the Featureless Linux Library supports and uses threads by default.
- This essentially adds -pthread to all level and monolithic builds with all projects depending on f_thread requiring passing -pthread.
+ With the inclusion of the code:"f_thread" project, the Featureless Linux Library supports and uses threads by default.
+ This essentially adds code:"-pthread" to all level and monolithic builds with all projects depending on code:"f_thread" requiring passing -pthread.
- To compile without this thread support, remove all occurances of "-pthread" from each of the build settings files.
- Be sure to remove f_thread project from the compile list as well (which can be found either in the individual projects build settings file or the appropriate level or monolithic build settings file).
+ To compile without this thread support, remove all occurances of code:"-pthread" from each of the build settings files.
+ Be sure to remove code:"f_thread" project from the compile list as well (which can be found either in the individual projects build settings file or the appropriate level or monolithic build settings file).
- Any project or library depending on f_thread must have -pthread passed to guarantee a correct and valid compilation.
+ Any project or library depending on f_thread must have code:"-pthread" passed to guarantee a correct and valid compilation.
- Some projects that optionally support pthreads may support the macro _di_pthread_support_ for disabling threads.
+ Some projects that optionally support pthreads may support the macro code:"_di_pthread_support_" for disabling threads.
- Thread support is a very common functionality and there may be changes to the FLL scripts and fakefile to support the options "--disable-thread" and "--enable-thread" to make utilizing threads slightly easier.
+ Thread support is a very common functionality and there may be changes to the FLL:"Featureless Linux Library" scripts and file:"fakefile" to support the options "--disable-thread" and "--enable-thread" to make utilizing threads slightly easier.
Some libraries and programs in this project require threads to work and will not compile with threads disabled.
GLIBC Problems:
- Some versions of GLIBC butcher static linking in some way or another.
- One of the problems encountered is that with compiling against threads (-pthread) some programs may get messages like\:
- multiple definition of `__lll_lock_wait_private' ... libpthread.a(lowlevellock.o): in function `__lll_unlock_wake_private' ...
+ Some versions of bold:"GLIBC" butcher static linking in some way or another.
+ One of the problems encountered is that with compiling against threads (code:"-pthread") some programs may get messages like\:
+ block:"
+ multiple definition of `__lll_lock_wait_private' ... libpthread.a(lowlevellock.o): in function `__lll_unlock_wake_private' ...
+ "
- An immediate solution would be to fix the GLIBC and set __lll_lock_wait_private to a weak_function.
- This is not practical for most users, so it may be that thread support in statically compiled libraries for GLIBC will not be possible.
- An alternative could be to use a more sane libc instead of GLIBC (if you can find one, like musl-libc).
+ An immediate solution would be to fix the bold:"GLIBC" and set code:"__lll_lock_wait_private" to a code:"weak_function".
+ This is not practical for most users, so it may be that thread support in statically compiled libraries for bold:"GLIBC" will not be possible.
+ An alternative could be to use a more sane libc instead of bold:"GLIBC" (if you can find one, like bold:"musl-libc").
There needs to be more investigation into the cause of this.
Maybe there is some way to fix this during compile or link time without having to fix GLIBC or use a different libc for static linking.
Valgrind Debugging:
- The tool "helgrind" in valgrind allows for debugging threads (such as valgrind --tool=helgrrind controller).
+ The tool code:"helgrind" in valgrind allows for debugging threads (such as code:"valgrind --tool=helgrind" controller).
- The way in which the "active" lock is used will result in out of order locks.
- This causes "helgrind" to produce a lot of warnings about locks being out of order.
- Therefore, it is stongly recommended to use the parameter "--track-lockorders=no".
+ The way in which the code:"active" lock is used will result in out of order locks.
+ This causes code:"helgrind" to produce a lot of warnings about locks being out of order.
+ Therefore, it is stongly recommended to use the parameter code:"--track-lockorders=no".
Thread Cancellation Problems:
- The POSIX standard designates thread cancellation via pthread_cancel() (which is provided via f_thread_cancel()).
- This cancellation approach works such that when pthread_cancel() the thread is immediately terminated at a cancellation point.
- The POSIX standard designates the detecting and acting on a cancellation point via pthread_testcancel() (which is provided via f_thread_cancel_test()).
+ The bold:"POSIX" standard designates thread cancellation via code:"pthread_cancel()" (which is provided via code:"f_thread_cancel()").
+ This cancellation approach works such that when code:"pthread_cancel()" the thread is immediately terminated at a cancellation point.
+ The bold:"POSIX" standard designates the detecting and acting on a cancellation point via code:"pthread_testcancel()" (which is provided via code:"f_thread_cancel_test()").
- The pthread_testcancel() operates such that if pthread_cancel() was ever used for some thread with pthread_testcancel() that thread immediately exits.
- There is no opportunity for the thread calling pthread_testcancel() to do any cleanup.
+ The code:"pthread_testcancel()" operates such that if code:"pthread_cancel()" was ever used for some thread with code:"pthread_testcancel()" that thread immediately exits.
+ There is no opportunity for the thread calling code:"pthread_testcancel()" to do any cleanup.
- The POSIX standard designates a way to perform exit tasks via pthread_cleanup_push() and pthread_cleanup_pop().
+ The bold:"POSIX" standard designates a way to perform exit tasks via code:"pthread_cleanup_push()" and code:"pthread_cleanup_pop()".
These are allowed to be implemented as macros.
- The POSIX standard then provides a number of POSIX functions that must act as a cancellation point (essentially they call pthread_testcancel() at act as if they do).
+ The bold:"POSIX" standard then provides a number of bold:"POSIX" functions that must act as a cancellation point (essentially they call code:"pthread_testcancel()" at act as if they do).
- What all of this means is that the POSIX cancellation system is unusable, useless, and dangerous (except in a very restricted set of project designs).
+ What all of this means is that the bold:"POSIX" cancellation system is unusable, useless, and dangerous (except in a very restricted set of project designs).
- The Featureless Linux Library is designed to encourage everything to be functional and non-global.
- The pthread_cleanup_push() and pthread_cleanup_pop() functions cannot be safely and reliable used because they not only may be macros but the Featureless Linux Library allows for the design to be in multiple scopes.
- The pthread_testcancel() is incredibly dangerous and can very easily result in segmentation faults, memory leaks, dead locks, and other security concerns.
+ The FLL:"Featureless Linux Library" is designed to encourage everything to be functional and non-global.
+ The code:"pthread_cleanup_push()" and code:"pthread_cleanup_pop()" functions cannot be safely and reliable used because they not only may be macros but the FLL:"Featureless Linux Library" allows for the design to be in multiple scopes.
+ The code:"pthread_testcancel()" is incredibly dangerous and can very easily result in segmentation faults, memory leaks, dead locks, and other security concerns.
- The cancellation functions, such as sleep(), may require being either interrupted through an interrupt signal or be cancelled via pthread_testcancel().
- The pthread_testcancel() may need to be used in these cases.
+ The cancellation functions, such as code:"sleep()", may require being either interrupted through an interrupt signal or be cancelled via code:"pthread_testcancel()".
+ The code:"pthread_testcancel()" may need to be used in these cases.
- Therefore, avoid using any design or functions that may force or require the use of pthread_testcancel() but when forced to be very careful to clear up resources and locks to make sure that if a cancellation occurs that nothing bad can happen.
+ Therefore, avoid using any design or functions that may force or require the use of code:"pthread_testcancel()" but when forced to be very careful to clear up resources and locks to make sure that if a cancellation occurs that nothing bad can happen.
A better approach would be to use timed checks on some variable shared between all affected functions and scopes that designates cancellation.
That way when a cancellation is reseived through the custom variable, the functions can actually handle the situation, safely and properly, before cancelling.
C/C++ Standard:
Newer C/C++ standards provide thread support.
- This is ideally much better than POSIX in that it will be more portable.
+ This is ideally much better than bold:"POSIX" in that it will be more portable.
At this time, most C/C++ compilers do not implement this thread support.
-# fss-0002
+# fss-0002 iki-0000
#
# license: open-standard-license-1.0
#
-# fss-0002
+# fss-0002 iki-0000
#
# license: cc-by-sa-4.0
#
+# This file (assumed to be named unicode.txt) can be more easily read using the following iki_read commands:
+# iki_read unicode.txt +Q -w -r FLL FLL -WW character "'" "'" code '"' '"'
+#
+# To read the "Unicode Documentation" section of this file, use this command sequence:
+# fss_basic_list_read unicode.txt +Q -cn "Unicode Documentation" | iki_read +Q -w -r FLL FLL -WW character "'" "'" code '"' '"'
+#
-Unicode:
- This project attempts to support Unicode 15.0.
+Unicode Documentation:
+ This project attempts to support bold:"Unicode 15.0".
Given the scale of Unicode in conjunction with the knowledege and availability of the developers behind this project this is goal is likely not met.
The intent is to reach compatibility, therefore fixes, improvements, and corrections will continue to be made as they are discovered and time is available.
# 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 abbreviation-ASCII ASCII abbreviation-GCC GCC abbreviation-HTML HTML -WW character "'" "'" code '"' '"'
+# 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 abbreviation-ASCII ASCII abbreviation-GCC GCC abbreviation-HTML HTML -WW character "'" "'" code '"' '"'
+# 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 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 abbreviation-GCC:"GNU Compiler Collection", but there may be certain hard-coded functionality that may need to be changed.
+ 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:"\U+000A": Prints a new line, equivalent to character:"\n".
- code:"\U+2E19": Prints the Unicode feather-like character character:"⸙".
- Only abbreviation-ASCII:"American Standard Code for Information Interchange" alpha-numeric hexidecimal digits are allowed in the Unicode sequence (upper or lower case).
+ 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:"\U+000A": Prints a new line, equivalent to character:"\n".
- code:"\U+2E19": Prints the Unicode feather-like character character:"⸙".
- Only abbreviation-ASCII:"American Standard Code for Information Interchange" alpha-numeric hexidecimal digits are allowed in the Unicode sequence (upper or lower case).
+ 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:"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 abbreviation-HTML:"Hyper Text Markup Language").
+ - 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 abbreviation-HTML:"Hyper Text Markup Language").
+ - 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.
# 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 abbreviation-ASCII ASCII abbreviation-FLL FLL abbreviation-GCC GCC -WW character "'" "'" code '"' '"'
+# 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 abbreviation-ASCII ASCII abbreviation-FLL FLL -WW character "'" "'" code '"' '"'
+# 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 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 abbreviation-GCC:"GNU Compiler Collection", but there may be certain hard-coded functionality that may need to be changed.
+ 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".
- 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 abbreviation-GCC:"GNU Compiler Collection" or a linker via abbreviation-GCC:"GNU Compiler Collection") is order sensitive.
+ 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 abbreviation-GCC:"GNU Compiler Collection" or a linker via abbreviation-GCC:"GNU Compiler Collection") is order sensitive.
+ 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 abbreviation-GCC:"GNU Compiler Collection" or a linker via abbreviation-GCC:"GNU Compiler Collection") is order sensitive.
+ 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 abbreviation-GCC:"GNU Compiler Collection" or a linker via abbreviation-GCC:"GNU Compiler Collection") is order sensitive.
+ 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 abbreviation-GCC:"GNU Compiler Collection" or a linker via abbreviation-GCC:"GNU Compiler Collection") is order sensitive.
+ 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 abbreviation-GCC:"GNU Compiler Collection" or a linker via abbreviation-GCC:"GNU Compiler Collection") is order sensitive.
+ 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 abbreviation-GCC:"GNU Compiler Collection" or a linker via abbreviation-GCC:"GNU Compiler Collection") is order sensitive.
+ 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 abbreviation-GCC:"GNU Compiler Collection" or a linker via abbreviation-GCC:"GNU Compiler Collection") is order sensitive.
+ 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 abbreviation-GCC:"GNU Compiler Collection" or a linker via abbreviation-GCC:"GNU Compiler Collection") is order sensitive.
+ 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"\:
- 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 abbreviation-GCC:"GNU Compiler Collection" or a linker via abbreviation-GCC:"GNU Compiler Collection") is order sensitive.
+ 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 abbreviation-GCC:"GNU Compiler Collection" or a linker via abbreviation-GCC:"GNU Compiler Collection") is order sensitive.
+ 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 abbreviation-GCC:"GNU Compiler Collection" or a linker via abbreviation-GCC:"GNU Compiler Collection") is order sensitive.
+ 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 abbreviation-GCC:"GNU Compiler Collection" or a linker via abbreviation-GCC:"GNU Compiler Collection") is order sensitive.
+ 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 abbreviation-GCC:"GNU Compiler Collection" or a linker via abbreviation-GCC:"GNU Compiler Collection") is order sensitive.
+ 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 abbreviation-GCC:"GNU Compiler Collection" or a linker via abbreviation-GCC:"GNU Compiler Collection") is order sensitive.
+ 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"\:
- 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 abbreviation-GCC:"GNU Compiler Collection" or a linker via abbreviation-GCC:"GNU Compiler Collection") is order sensitive.
+ 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 abbreviation-GCC:"GNU Compiler Collection" or a linker via abbreviation-GCC:"GNU Compiler Collection") is order sensitive.
+ 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 abbreviation-GCC:"GNU Compiler Collection" or a linker via abbreviation-GCC:"GNU Compiler Collection") is order sensitive.
+ 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"\:
- code:"path_headers"\:
A sub-path in which headers are to be installed under.
- For example, the abbreviation-FLL:"Featureless Linux Library" project might use the code:"level_0", code:"level_1", etc.. headers without requiring that structure within the source.
+ 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"
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 abbreviation-ASCII:"American Standard Code for Information Interchange" period character character:".".
+ 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).
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 abbreviation-ASCII:"American Standard Code for Information Interchange" period character character:".".
+ 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).
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 abbreviation-ASCII:"American Standard Code for Information Interchange" period character character:".".
+ 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).
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 abbreviation-ASCII:"American Standard Code for Information Interchange" period character character:".".
+ 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.
# license: open-standard-license-1.0
#
# This file (assumed to be named dependencies.txt) can be more easily read using the following iki_read commands:
-# iki_read dependencies.txt +Q -w -r abbreviation-FLL FLL -WW code '"' '"' bold '"' '"'
+# iki_read dependencies.txt +Q -w -r FLL FLL -WW code '"' '"' bold '"' '"'
#
# To read the "Dependencies Specification" section of this file, use this command sequence:
-# fss_basic_list_read dependencies.txt +Q -cn "Dependencies Specification" | iki_read +Q -w -r abbreviation-FLL FLL -WW code '"' '"' bold '"' '"'
+# fss_basic_list_read dependencies.txt +Q -cn "Dependencies Specification" | iki_read +Q -w -r FLL FLL -WW code '"' '"' bold '"' '"'
#
Dependencies Specification:
Each Content represents associated information, such as a version number.
Future versions of this will clarify what and how Content, such as version numbers, are to be used and processed.
- This file is originally intended for dependencies provided by the abbreviation-FLL:"Featureless Linux Library" project.
+ This file is originally intended for dependencies provided by the FLL:"Featureless Linux Library" project.
Order matters, and the provided order represents the order of dependencies.
The first entry therefore has no preceding dependency and the last dependency could potentially depend on all dependencies above it.
# license: open-standard-license-1.0
#
# This file (assumed to be named fss-000c.txt) can be more easily read using the following iki_read commands:
-# iki_read fss-000c.txt +Q -w -r abbreviation-FSS FSS -WWW character "'" "'" code '"' '"' emphasis '"' '"'
+# iki_read fss-000c.txt +Q -w -r FSS FSS -WWW character "'" "'" code '"' '"' emphasis '"' '"'
#
# To read the "Featureless Settings Specification: 000C - IKI Text" section of this file, use this command sequence:
-# fss_basic_list_read fss-000c.txt +Q -cn "Featureless Settings Specification: 000C - IKI Text" | iki_read +Q -w -r abbreviation-FSS FSS -WWW character "'" "'" code '"' '"' emphasis '"' '"'
+# fss_basic_list_read fss-000c.txt +Q -cn "Featureless Settings Specification: 000C - IKI Text" | iki_read +Q -w -r FSS FSS -WWW character "'" "'" code '"' '"' emphasis '"' '"'
#
Featureless Settings Specification: 000C - IKI Text:
- The IKI specifications are separate specifications from the abbreviation-FSS:"Featureless Settings Specifications".
+ The IKI specifications are separate specifications from the FSS:"Featureless Settings Specifications".
This is simply a more formal way to designate that this format utilizes IKI syntax.
- The IKI syntax may be used in any abbreviation-FSS:"Featureless Settings Specifications".
+ The IKI syntax may be used in any FSS:"Featureless Settings Specifications".
The IKI format may be added to the.
See the file:"iki.txt" specification for details on the IKI specifications.
Example\:
# fss-000c iki-0000
- This is a emphasis:"formal example" utilizing the FSS headers.
+ This is a italic:"formal example" utilizing the FSS headers.
Example\:
# iki-0000
- This is a emphasis:"informal example" utilizing the IKI headers.
+ This is a italic:"informal example" utilizing the IKI headers.
# license: open-standard-license-1.0
#
# This file (assumed to be named fss-000d.txt) can be more easily read using the following iki_read commands:
-# iki_read fss-000d.txt +Q -w -r abbreviation-FSS FSS -WW character "'" "'" code '"' '"'
+# iki_read fss-000d.txt +Q -w -r FSS FSS -WW character "'" "'" code '"' '"'
#
# To read the "Featureless Settings Specification: 000D - Basic Rule" section of this file, use this command sequence:
-# fss_basic_list_read fss-000d.txt +Q -cn "Featureless Settings Specification: 000D - Basic Rule" | iki_read +Q -w -r abbreviation-FSS FSS -WW character "'" "'" code '"' '"'
+# fss_basic_list_read fss-000d.txt +Q -cn "Featureless Settings Specification: 000D - Basic Rule" | iki_read +Q -w -r FSS FSS -WW character "'" "'" code '"' '"'
#
Featureless Settings Specification: 000D - Basic Rule:
- This is a special case that follows code:"FSS-0002 (Basic List)", and different abbreviation-FSS:"Featureless Settings Specifications" formats inside this code:"FSS-0002 (Basic List)".
+ This is a special case that follows code:"FSS-0002 (Basic List)", and different FSS:"Featureless Settings Specifications" formats inside this code:"FSS-0002 (Basic List)".
This code:"FSS-0002 (Basic List)" is considered the "Outer List" and the Content of this Outer List is considered the "Inner Content".
- The Inner Content may be any of the following abbreviation-FSS:"Featureless Settings Specifications" formats: code:"FSS-0000 (Basic)", code:"FSS-0001 (Extended)", and code:"FSS-0003 (Extended List)".
+ The Inner Content may be any of the following FSS:"Featureless Settings Specifications" formats: code:"FSS-0000 (Basic)", code:"FSS-0001 (Extended)", and code:"FSS-0003 (Extended List)".
The way in which each format is determined is first to see if the Inner Content Object would be a valid Extended List Object.
If the Inner Content Object is not a valid code:"FSS-0003 (Extended List)" Object, then check to see if it is an code:"FSS-0000 (Basic)" or code:"FSS-0001 (Extended)" Object.
Additional restrictions on the use of IKI syntax is allowed if explicitly defined in the implementing specification.
This additional restriction may also include using a more restrictive IKI syntax, such as code:"iki-0001 (Basic)".
- Anything implementing this specification may impose its own restrictions on when to determine if the Inner Content is what abbreviation-FSS:"Featureless Settings Specifications" format, based on Object names.
+ 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 file:"fss-0000.txt", file:"fss-0001.txt", and file:"fss-0003.txt" specification files for details on the syntax rules.
# license: open-standard-license-1.0
#
# This file (assumed to be named fss-000e.txt) can be more easily read using the following iki_read commands:
-# iki_read fss-000e.txt +Q -w -rr abbreviation-FLL FLL abbreviation-EOF EOF -WWW character "'" "'" code '"' '"' emphasis '"' '"'
+# iki_read fss-000e.txt +Q -w -rr EOF EOF FLL FLL -WWW character "'" "'" code '"' '"' emphasis '"' '"'
#
# To read the "Featureless Settings Specification: 000e - Payload" section of this file, use this command sequence:
-# fss_basic_list_read fss-000e.txt +Q -cn "Featureless Settings Specification: 000e - Payload" | iki_read +Q -w -r abbreviation-FLL FLL abbreviation-EOF EOF -WWW character "'" "'" code '"' '"' emphasis '"' '"'
+# fss_basic_list_read fss-000e.txt +Q -cn "Featureless Settings Specification: 000e - Payload" | iki_read +Q -w -r EOF EOF FLL FLL -WWW character "'" "'" code '"' '"' emphasis '"' '"'
#
Featureless Settings Specification: 000e - Payload:
This is a code:"FSS-0002 (Basic List)" with two required objects\:
- 1) emphasis:"header".
- 2) emphasis:"payload".
+ 1) italic:"header".
+ 2) italic:"payload".
- The emphasis:"header"\:
- - The emphasis:"header"'s Content is of type code:"FSS-0001 (Extended)".
- - The emphasis:"header" is recommended to have the Objects emphasis:"length", emphasis:"status", emphasis:"part", and emphasis:"total".
- - The recommended emphasis:"length" represents the size of the emphasis:"payload".
- - The recommended emphasis:"part" represents a single part of a set of packets for when the data being transmitted is split across multiple payloads.
- - The recommended emphasis:"total" represents the total number of parts representing a complete data transmitted across multiple payloads.
- - The recommended emphasis:"status" represents status codes (such as success or failure) and multiple.
- - The Content for the recommended emphasis:"length" and emphasis:"status" are positive whole numbers (including zero) that may be in emphasis:"binary", emphasis:"octal", emphasis:"decimal", emphasis:"duodecimal", or emphasis:"hexidecimal" numerical format.
+ The italic:"header"\:
+ - The italic:"header"'s Content is of type code:"FSS-0001 (Extended)".
+ - The italic:"header" is recommended to have the Objects italic:"length", italic:"status", italic:"part", and italic:"total".
+ - The recommended italic:"length" represents the size of the italic:"payload".
+ - The recommended italic:"part" represents a single part of a set of packets for when the data being transmitted is split across multiple payloads.
+ - The recommended italic:"total" represents the total number of parts representing a complete data transmitted across multiple payloads.
+ - The recommended italic:"status" represents status codes (such as success or failure) and multiple.
+ - The Content for the recommended italic:"length" and italic:"status" are positive whole numbers (including zero) that may be in italic:"binary", italic:"octal", italic:"decimal", italic:"duodecimal", or italic:"hexidecimal" numerical format.
- The emphasis:"payload"\:
- - The emphasis:"payload"'s Content may contain anything, including raw binary data.
- - The emphasis:"payload" is emphasis:"required" to be the last list Object in the file.
- - The emphasis:"payload" is recommended to have its size designated in some manner in the emphasis:"header" (such as with the recommended emphasis:"length").
- - The emphasis:"payload" is terminated by the abbreviation-EOF:"End of File" character or by the recommended emphasis:"length" header.
- - The emphasis:"payload" may be empty (length may be zero), but the list Object emphasis:"payload" must still exist.
- - Nothing in the emphasis:"payload" may be considered a valid list Object by the outer code:"FSS-0002 (Basic List)" and therefore escaping is unnecessary (No further processing by the outer code:"FSS-0002 (Basic List)" is allowed at this point).
- - Comments in the emphasis:"payload" are not considered comments and are instead considered part of the payload, as-is.
- - Essentially, the emphasis:"payload" should be treated as binary data embedded in a text file.
+ The italic:"payload"\:
+ - The italic:"payload"'s Content may contain anything, including raw binary data.
+ - The italic:"payload" is italic:"required" to be the last list Object in the file.
+ - The italic:"payload" is recommended to have its size designated in some manner in the italic:"header" (such as with the recommended italic:"length").
+ - The italic:"payload" is terminated by the EOF:"End of File" character or by the recommended italic:"length" header.
+ - The italic:"payload" may be empty (length may be zero), but the list Object italic:"payload" must still exist.
+ - Nothing in the italic:"payload" may be considered a valid list Object by the outer code:"FSS-0002 (Basic List)" and therefore escaping is unnecessary (No further processing by the outer code:"FSS-0002 (Basic List)" is allowed at this point).
+ - Comments in the italic:"payload" are not considered comments and are instead considered part of the payload, as-is.
+ - Essentially, the italic:"payload" should be treated as binary data embedded in a text file.
- The recommended emphasis:"length" emphasis:"header" Object used to designate the emphasis:"payload" size does not necessarily have to be defined in the emphasis:"header".
- That is to say, if the emphasis:"payload" is expected to be of some pre-defined or static length then a length does not need to be provided in the emphasis:"header".
+ The recommended italic:"length" italic:"header" Object used to designate the italic:"payload" size does not necessarily have to be defined in the italic:"header".
+ That is to say, if the italic:"payload" is expected to be of some pre-defined or static length then a length does not need to be provided in the italic:"header".
- The recommended emphasis:"status" emphasis:"header" Object may be a string, such as code:"F_none", or a positive whole number.
- What the status code represents is application specific (or specific to a sub-standard) but may often be used to represent abbreviation-FLL:"Featureless Linux Library" status code.
- - The abbreviation-FLL:"Featureless Linux Library" status code is a 16-bit digit whose first two high-order bits represent emphasis:"error" and emphasis:"warning" ( representing emphasis:"signal").
- - The abbreviation-FLL:"Featureless Linux Library" status code as a number is binary sensitive and may not be portable across binaries or systems.
+ The recommended italic:"status" italic:"header" Object may be a string, such as code:"F_none", or a positive whole number.
+ What the status code represents is application specific (or specific to a sub-standard) but may often be used to represent FLL:"Featureless Linux Library" status code.
+ - The FLL:"Featureless Linux Library" status code is a 16-bit digit whose first two high-order bits represent italic:"error" and italic:"warning" ( representing italic:"signal").
+ - The FLL:"Featureless Linux Library" status code as a number is binary sensitive and may not be portable across binaries or systems.
- For best portability, consider using status as a name string to ensure cross-system or cross-binary compatibility.
Example\:
The Control Block is the first block in the packet and is considered endianless.
There exists only a single byte within the Control Block.
- Regardless of the endianness of the packet, the leftmost bit is always the emphasis:"string" or emphasis:"binary" bit.
+ Regardless of the endianness of the packet, the leftmost bit is always the italic:"string" or italic:"binary" bit.
The second bit following that bit represents the endianness bit.
- The emphasis:"string" or emphasis:"binary" bit, a value of 0 designates that the packet is in string format and a value of 1 designates that the packet is in binary format.
+ The italic:"string" or italic:"binary" bit, a value of 0 designates that the packet is in string format and a value of 1 designates that the packet is in binary format.
While the packet might be considered to be in string format, it is technically always in binary format due to the Control Block and Size Block.
- This means that the bit designating the packet as a emphasis:"string" packet or a emphasis:"binary" packet is referring to whether or not the Payload Block is in emphasis:"string" format or is in emphasis:"binary" format.
+ This means that the bit designating the packet as a italic:"string" packet or a italic:"binary" packet is referring to whether or not the Payload Block is in italic:"string" format or is in italic:"binary" format.
The endianness bit designates whether or not the packet is in big endian or little endian format.
A bit value of 0 designates that this packet is in little endian and a value of 1 designates that this packet is in big endian format.
The Payload Block is not defined by this standard of that that it exists and should be in code:"FSS-000e (Payload)" format.
The code:"FSS-000e (Payload)" may be represented in either string format or binary format.
- The code:"FSS-000e (Payload)" may contain multiple emphasis:"header"(s) but may only contain a single emphasis:"payload".
- With this in mind, it is recommended that only a single emphasis:"header" be supported in the Payload Block.
+ The code:"FSS-000e (Payload)" may contain multiple italic:"header"(s) but may only contain a single italic:"payload".
+ With this in mind, it is recommended that only a single italic:"header" be supported in the Payload Block.
See the file:"fss-000e.txt" specification file for details on the syntax rules for the Payload Block.
# license: open-standard-license-1.0
#
# This file (assumed to be named fss.txt) can be more easily read using the following iki_read commands:
-# iki_read fss.txt +Q -w -rrrrrrrr abbreviation-FSS FSS abbreviation-KISS KISS anti-abbreviation-KISS anti-KISS abbreviation-XML XML abbreviation-UTF-8 UTF-8 abbreviation-ASCII ASCII abbreviation-BOM BOM abbreviation-URL URL -WWW character "'" "'" code '"' '"' emphasis '"' '"'
+# iki_read fss.txt +Q -w -rrrrrrrr anti-KISS anti-KISS ASCII ASCII BOM BOM FSS FSS KISS KISS UTF-8 UTF-8 URL URL XML XML -WWW character "'" "'" code '"' '"' emphasis '"' '"'
#
# Individual sections in this file may be parsed using fss_basic_list_read command and then passed to the iki_read command.
# To read the "Featureless Settings Specifications" section of this file, use this command sequence:
-# fss_basic_list_read fss.txt +Q -cn "Featureless Settings Specifications" | iki_read +Q -w -rrrrrrrr abbreviation-FSS FSS abbreviation-KISS KISS anti-abbreviation-KISS anti-KISS abbreviation-XML XML abbreviation-UTF8 UTF8 abbreviation-ASCII ASCII abbreviation-BOM BOM abbreviation-URL URL -WWW character "'" "'" code '"' '"' emphasis '"' '"'
+# fss_basic_list_read fss.txt +Q -cn "Featureless Settings Specifications" | iki_read +Q -w -rrrrrrrr anti-KISS anti-KISS ASCII ASCII BOM BOM FSS FSS KISS KISS UTF-8 UTF-8 URL URL XML XML -WWW character "'" "'" code '"' '"' emphasis '"' '"'
#
Featureless Settings Specifications:
- The Featureless Settings Specifications describe a set of standards designed around the age-old design principle referred to as emphasis:"Keep It Simple Stupid", aka abbreviation-KISS:"Keep It Simple Stupid". The abbreviation-FSS:"Featureless Settings Specifications" are primarily intended for settings files but are extensible enough to be used beyond that.
+ The Featureless Settings Specifications describe a set of standards designed around the age-old design principle referred to as italic:"Keep It Simple Stupid", aka KISS:"Keep It Simple Stupid". The FSS:"Featureless Settings Specifications" are primarily intended for settings files but are extensible enough to be used beyond that.
- The abbreviation-FSS:"Featureless Settings Specifications" defines the following\:
+ The FSS:"Featureless Settings Specifications" defines the following\:
- Will consist of numerous different kinds of specification files, depending on the type of information stored.
- - As with the practice of code:"#!/bin/bash", the setting files emphasis:"should" have the following: code:"# fss-????" format, such as "# fss-0001".
- - Multiple sub-standards may be appended to the abbreviation-FSS:"Featureless Settings Specifications" header, using the same format structure, such as supporting IKI: "# fss-0000 iki-0000" or HTML5: "# fss-0000 html-0005".
+ - As with the practice of code:"#!/bin/bash", the setting files italic:"should" have the following: code:"# fss-????" format, such as "# fss-0001".
+ - Multiple sub-standards may be appended to the FSS:"Featureless Settings Specifications" header, using the same format structure, such as supporting IKI: "# fss-0000 iki-0000" or HTML5: "# fss-0000 html-0005".
- With the character:"?" representing the (hexadecimal/base-16) number that represents the particular specification structure.
- - All settings specifications emphasis:"should" avoid any form of noise, relative to the data being stored.
- - abbreviation-XML:"Extensible Markup Language" would be considered anti-abbreviation-KISS:"Anti Keep It Simple Stupid" due to the extreme level of noise generated by the abbreviation-XML:"Extensible Markup Language" language (not easy to read).
+ - All settings specifications italic:"should" avoid any form of noise, relative to the data being stored.
+ - XML:"Extensible Markup Language" would be considered anti-KISS:"Anti Keep It Simple Stupid" due to the extreme level of noise generated by the XML:"Extensible Markup Language" language (not easy to read).
- The settings files are setup so that they should (reasonably) produce easy readability on both the console and in a GUI.
- The specifications should strive for completeness (see the completeness theorem).
- The most basic form of abbreviation-FSS:"Featureless Settings Specifications" consists of two main parts: an emphasis:"Object" and the emphasis:"Content".
+ The most basic form of FSS:"Featureless Settings Specifications" consists of two main parts: an italic:"Object" and the italic:"Content".
- Object: Considered the name or identifier of some property or data; Objects do not require an associated Content.
- - Content: The data associated with a given Object; all Content emphasis:"must" have an associated Object.
+ - Content: The data associated with a given Object; all Content italic:"must" have an associated Object.
Objects and Contents can include any characters allowed by the specifications.
The specification may choose how a given Object or Content are represented and parsed.
Contents may be broken up into zero or more discrete sets of Content.
Each of these discrete sets of Content are referred to as a column.
- These columns do not need to be setup in a column structure, the word emphasis:"column" is simply used as a grouping terminology.
+ These columns do not need to be setup in a column structure, the word italic:"column" is simply used as a grouping terminology.
While a Content refers to the entire set, a column (more specifically, a Content column) refers to the individual discrete sets within the Content.
For example, in code:"FSS-000 (Basic)" the entire Content may be further represented as a single column.
For example, in code:"FSS-001 (Extended)" the entire Content may be further represented as multiple columns.
Unless otherwise specified, all specifications are newline sensitive (character:"\n" only).
Newline characters are only character:"\n" and are never anything else (character:"\r" is not considered newline in any manner).
- These specifications refer to characters that have printable representation as emphasis:"printable".
- These specifications refer to characters that have no printable representation as emphasis:"non-printable".
+ These specifications refer to characters that have printable representation as italic:"printable".
+ These specifications refer to characters that have no printable representation as italic:"non-printable".
White spaces characters that are printable, such as tabs and spaces, must be considered the same type for the purposes of parsing.
Non-printing white spaces characters (zero-width characters) are ignored, are treated as placeholders for processing with the exception of combining characters.
White spaces that use combining characters result in printable characters and the resulting combination is treated as not white space.
Unless otherwise specified, character/data delimits are performed only when required and not unilaterally.
In the case of Objects, delimits would only apply when that Object could be potentially identified as an Object.
- For example, code:"FSS-0001 (Extended)" needs quotes to group parts that include spaces, if there is no initial quote, then a quote following the data emphasis:"must not" be delimited.
+ For example, code:"FSS-0001 (Extended)" needs quotes to group parts that include spaces, if there is no initial quote, then a quote following the data italic:"must not" be delimited.
Such as these following three lines\:
"Object 1" "This is a single quoted Content." \"Additional unquoted Content."
Object_2 This is multiple" Contents and the trailing quote does not need to be delimited.
Content\:
- Wouldn't require delimits if no white space or end of string after.
- All specifications are expected to support or be of the character encoding abbreviation-UTF-8:"Unicode Transformation Format 8-bit"; however, there is no imposed restriction on supporting or using any other encoding.
+ All specifications are expected to support or be of the character encoding UTF-8:"Unicode Transformation Format 8-bit"; however, there is no imposed restriction on supporting or using any other encoding.
Those encodings must only support the appropriate characters required by a given standard for differentiating Objects, Contents, and delimits.
- All specifications do assume abbreviation-ASCII:"American Standard Code for Information Interchange" and Unicode support.
+ All specifications do assume ASCII:"American Standard Code for Information Interchange" and Unicode support.
Unless otherwise specified, comments are designated by the pound symbol character:"#" but only if only white space is to the left of the pound or the pound character:"#" is at the start of the line.
There is no support for inline comments.
A line containing a valid comment is in its entirety ignored.
This means that if there is white space before the designation symbol (the pound character:"#" character) then that white space is ignored.
- Unless otherwise specified, all designation characters emphasis:"must" represent abbreviation-ASCII:"American Standard Code for Information Interchange" codes.
+ Unless otherwise specified, all designation characters italic:"must" represent ASCII:"American Standard Code for Information Interchange" codes.
With designation characters being any character code used to designate how to identify an Object or Content (such as a colon character:":" at the end of a basic list).
- This keeps the processing and logic simple and safe, for both abbreviation-UTF-8:"Unicode Transformation Format 8-bit" and abbreviation-ASCII:"American Standard Code for Information Interchange".
- White space used for designation characters emphasis:"must" include support for abbreviation-UTF-8:"Unicode Transformation Format 8-bit" white space characters, unless otherwise specified.
+ This keeps the processing and logic simple and safe, for both UTF-8:"Unicode Transformation Format 8-bit" and ASCII:"American Standard Code for Information Interchange".
+ White space used for designation characters italic:"must" include support for UTF-8:"Unicode Transformation Format 8-bit" white space characters, unless otherwise specified.
However, these white space used as a designation character, must be printing white space that are not combining white space characters.
Any visible/graph character that is considered a white space (such as unicode:"U+1680" character:" ") is not to be considered a white space, unless otherwise specified.
When used for syntax matching purposes, zero-width Unicode characters are only to be considered zero-width unless otherwise specified.
- For example, the emphasis:"invisible plus" character (unicode:"U+2064") is not to be considered as a plus.
+ For example, the italic:"invisible plus" character (unicode:"U+2064") is not to be considered as a plus.
- The abbreviation-UTF-8:"Unicode Transformation Format 8-bit" abbreviation-BOM:"Byte Order Mark" is not allowed as a Byte Order Mark; instead, it must always be treated as the character represented by its code (unless explicitly allowed to represent a abbreviation-BOM:"Byte Order Mark" by a standard).
+ The UTF-8:"Unicode Transformation Format 8-bit" BOM:"Byte Order Mark" is not allowed as a Byte Order Mark; instead, it must always be treated as the character represented by its code (unless explicitly allowed to represent a BOM:"Byte Order Mark" by a standard).
- The only Unicode dash-like characters allowed as a emphasis:"dash" are those intended to connect, such as the Unicode hyphens (unicode:"U+2010" and unicode:"U+2011") (unless otherwise specified).
+ The only Unicode dash-like characters allowed as a italic:"dash" are those intended to connect, such as the Unicode hyphens (unicode:"U+2010" and unicode:"U+2011") (unless otherwise specified).
- In any specification where security is intended, if there exists a Unicode character that matches an abbreviation-ASCII:"American Standard Code for Information Interchange" character, that Unicode character emphasis:"may" be prohibited by that standard in favor of the abbreviation-ASCII:"American Standard Code for Information Interchange" equivalent.
- One such example is in the case of a abbreviation-URL:"Uniform Resource Locator", where the name could be used to trick a person (url:"http://this-site.com/" vs url:"http://this‐site.com/").
+ In any specification where security is intended, if there exists a Unicode character that matches an ASCII:"American Standard Code for Information Interchange" character, that Unicode character italic:"may" be prohibited by that standard in favor of the ASCII:"American Standard Code for Information Interchange" equivalent.
+ One such example is in the case of a URL:"Uniform Resource Locator", where the name could be used to trick a person (url:"http://this-site.com/" vs url:"http://this‐site.com/").
This (potential insecure behavior) is allowed in general because a well written program would be able to detect and communicate the possible misunderstanding and thereby avoid mistakes without imposing any character restrictions.
- This is a common behavior for security reasons, each character used for any special purposes must be visibly distinct, with white space and non-printing characters as the exception to the words emphasis:"visibly distinct".
+ This is a common behavior for security reasons, each character used for any special purposes must be visibly distinct, with white space and non-printing characters as the exception to the words italic:"visibly distinct".
The following are core specifications (each with a common name associated with the specification number)\:
- fss-0000: Basic
# license: open-standard-license-1.0
#
# This file (assumed to be named iki-0001.txt) can be more easily read using the following iki_read commands:
-# iki_read iki-0001.txt +Q -w -rrr abbreviation-URI URI abbreviation-URL URL abbreviation-URN URN -WW character "'" "'" code '"' '"'
+# iki_read iki-0001.txt +Q -w -rrr URI URI URL URL URN URN -WW character "'" "'" code '"' '"'
#
# To read the "IKI Specification: 0001 - Basic" section of this file, use this command sequence:
-# fss_basic_list_read iki-0001.txt +Q -cn "IKI Specification: 0001 - Basic" | iki_read +Q -w -rrr abbreviation-URI URI abbreviation-URL URL abbreviation-URN URN -WW character "'" "'" code '"' '"'
+# fss_basic_list_read iki-0001.txt +Q -cn "IKI Specification: 0001 - Basic" | iki_read +Q -w -rrr URI URI URL URL URN URN -WW character "'" "'" code '"' '"'
#
IKI Specification: 0001 - Basic:
- This specification provides a small set of vocabulary names meant to be associated with common uses, such as e-mail addresses and abbreviation-URL:"Uniform Resource Locator"s.
+ This specification provides a small set of vocabulary names meant to be associated with common uses, such as e-mail addresses and URL:"Uniform Resource Locator"s.
Vocabulary\:
- - address: Any mailing address, except for e-mail and abbreviation-URI:"Uniform Resource Identifier".
+ - address: Any mailing address, except for e-mail and URI:"Uniform Resource Identifier".
- code: All text contained within represent code and should be presented as such.
- email: Any valid e-mail address.
- phone: Any valid phone number.
- quote: All text within represents some quote.
- - uri: Any valid abbreviation-URI:"Uniform Resource Identifier" (allows abbreviation-URL:"Uniform Resource Locator" and abbreviation-URN:"Uniform Resource Name").
- - url: Any valid abbreviation-URL:"Uniform Resource Locator".
- - urn: Any valid abbreviation-URN:"Uniform Resource Name".
+ - uri: Any valid URI:"Uniform Resource Identifier" (allows URL:"Uniform Resource Locator" and URN:"Uniform Resource Name").
+ - url: Any valid URL:"Uniform Resource Locator".
+ - urn: Any valid URN:"Uniform Resource Name".
- var: All text contained within represents some sort of variable.
See the file:"iki.txt" specification file for details on the syntax rules.
This vocabulary may be further extended but must at least support the taxonomy defined here.
Flexibility on interpretation is intended so that the context can be more fine-tuned and customized.
- The taxonomy for the emphasis:"context", emphasis:"define", and emphasis:"parameter" are intentionally not defined here and left open.
+ The taxonomy for the italic:"context", italic:"define", and italic:"parameter" are intentionally not defined here and left open.
One utilizing this should document the taxonomy for each of these as desired.
Vocabulary\:
IKI Specifications:
IKI is a minimally structured WIKI-like syntax meant to be simpler than WIKI syntax.
- The IKI syntax provides a vocabulary name (with specific context associated with it) followed by quoted code that is associated with the given vocabulary name.
+ The IKI syntax provides a vocabulary name (with specific context associated with it) followed by quoted value that is associated with the given vocabulary name.
The vocabulary represents a list of allowed variable names that may also have specific contextual meaning defined by a given IKI specification.
- The variable name is considered the emphasis:"Object".
- The variable value is considered the emphasis:"Content".
+ The variable name is considered the italic:"Object" and is also considered the vocabulary.
+ The variable value is considered the italic:"Content".
The IKI format will use code:"iki-0000" to represent an IKI with no explicitly defined vocabulary.
Whereas code:"iki-0001" and beyond represent a specific IKI vocabulary.
The following emphasis\:"is escaped to not be treated as IKI data".'
- Objects would be\:
+ Objects (also called vocabulary or variable name) would be\:
1) emphasis
2) url
3) code
- Contents would be\:
+ Contents (also called variable value) would be\:
1.1) emphasize some text
2.1) http://www.example.com/url with space/
3.1) const char *string = "My \"quoted\" C string.";
projects / fll / commitdiff