Fix the documentation to clarify that the --work paramter is, in fact, more different than --prefix parameter.
Update the tree examples to show both the build directory tree and work directory tree.
Switch to using the fss-0002 format for all of the documentation files and specification files.
-The Featureless Linux Library, or FLL, is a set of projects designed to be used for Linux programming.
-
-The FLL is design around the following concepts:
-- API 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 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 "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 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 FLL versioning system has three parts: major.minor.micro.
-- The Major is the primary API specification, changes to this number represent massive breaking changes and for all intents and purposes is a different project.
-- The Minor represents potential breaking changes, Stable status and Development Status (whereas even numbers represent stable and odd numbers represent development).
-- The Micro represents bugfixes and security fixes, these should never introduce API breaking changes nor new functionality.
-
-Development releases (as specified by Minor version part) may introduce breaking changes and new functionality.
-Stable releases (as specified by the Minor version part) may not introduce breaking change, unless forced by some security or other difficult situation, and must not add new functionality.
-
-The FLL project is broken up into 3 different levels: level_0, level_1, and level_2.
-A third pseudo-level also exists for common programs built using this project, called level_3.
-
-With an exception of a few projects within level_0, each level should only depend on a project from a lower level.
-Therefore, a level_1 project can only depend on level_0 projects and a level_2 project can depend on only level_0 and level_1 projects.
-This does not technically apply to the pseudo-level, level_3, projects, but the pattern is generally followed.
-
-A few projects in level_0 are essentially required by everything and are depended on by virtually all projects, regardless of the level.
-These level_0 projects are:
-- f_type: provides core typedef, #define, and similar structures for the entire set of FLL projects.
-- f_status: provides status codes and other status codes to be used by the entire set of FLL projects.
-- f_memory: provides common memory allocation/deallocation to be used by the entire set of FLL projects.
-- f_string: provides common string management to be used by the entire set of the FLL projects.
-- f_utf: provides common UTF-8 related string management to be used by the entire set of the FLL projects.
-
-The above projects should be installed first, and in the provided order (f_type, then f_status, then f_memory, f_string, and finally f_utf).
-No other 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 bootstrap.sh script.
-- The Featureless Make, which is a level_3 project provided by FLL.
-
-An example bootstrap script is provided (build/scripts/bootstrap-example.sh) is provided for to show how to build the FLL directly from source.
-Use it as an example or explicitly call it (such as: "bash build/scripts/bootstrap-example.sh monolithic 0.5.0").
-
-See: dependencies for specific dependencies of this project.
-See: readme.bootstrap for bootstrap compiling (or just regular compiling) any part of the FLL and notes on installing.
-See: readme.build for Featureless Make compiling and notes on installing.
+# fss-0002
+
+Readme Documentation:
+ The Featureless Linux Library, or FLL, is a set of projects designed to be used for Linux programming.
+
+ The FLL is design around the following concepts\:
+ - API 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 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 "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 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 FLL versioning system has three parts: major.minor.micro.
+ - The Major is the primary API specification, changes to this number represent massive breaking changes and for all intents and purposes is a different project.
+ - The Minor represents potential breaking changes, Stable status and Development Status (whereas even numbers represent stable and odd numbers represent development).
+ - The Micro represents bugfixes and security fixes, these should never introduce API breaking changes nor new functionality.
+
+ Development releases (as specified by Minor version part) may introduce breaking changes and new functionality.
+ Stable releases (as specified by the Minor version part) may not introduce breaking change, unless forced by some security or other difficult situation, and must not add new functionality.
+
+ The FLL project is broken up into 3 different levels: level_0, level_1, and level_2.
+ A third pseudo-level also exists for common programs built using this project, called level_3.
+
+ With an exception of a few projects within level_0, each level should only depend on a project from a lower level.
+ Therefore, a level_1 project can only depend on level_0 projects and a level_2 project can depend on only level_0 and level_1 projects.
+ This does not technically apply to the pseudo-level, level_3, projects, but the pattern is generally followed.
+
+ A few projects in level_0 are essentially required by everything and are depended on by virtually all projects, regardless of the level.
+ These level_0 projects are\:
+ - f_type: provides core typedef, #define, and similar structures for the entire set of FLL projects.
+ - f_status: provides status codes and other status codes to be used by the entire set of FLL projects.
+ - f_memory: provides common memory allocation/deallocation to be used by the entire set of FLL projects.
+ - f_string: provides common string management to be used by the entire set of the FLL projects.
+ - f_utf: provides common UTF-8 related string management to be used by the entire set of the FLL projects.
+
+ The above projects should be installed first, and in the provided order (f_type, then f_status, then f_memory, f_string, and finally f_utf).
+ No other 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 bootstrap.sh script.
+ - The Featureless Make, which is a level_3 project provided by FLL.
+
+ An example bootstrap script is provided (build/scripts/bootstrap-example.sh) is provided for to show how to build the FLL directly from source.
+ Use it as an example or explicitly call it (such as: "bash build/scripts/bootstrap-example.sh monolithic 0.5.0").
+
+ See: dependencies for specific dependencies of this project.
+ See: readme.bootstrap for bootstrap compiling (or just regular compiling) any part of the FLL and notes on installing.
+ See: readme.build for Featureless Make compiling and notes on installing.
-The Featureless Linux Library provides a special bootstrap script in case the Featureless Make is not currently installed.
-
-The GNU bash scripts, called bootstrap.sh and install.sh, are provided to perform this bootstrap process.
-
-The syntax for bootstrap.sh is:
- bootstrap.sh <operation> [options]
- - where operation is one of the following: 'build' or 'clean'.
- - No 'install' command is provided, all of the files to install may be found in the build/ directory after the build command is executed.
- - To install, either copy the files in the build directory to their appropriate destination or use the install.sh GNU bash script.
- - For all operations and options, get help from the bootstrap script by appending the "--help" to the script, such as: "./bootstrap.sh --help".
- - The monolithic build process is the simplest, which can be generated like the following: "./bootstrap.sh build -m monolithic".
- - When during development, consider using a work directory: "./bootstrap.sh --work /tmp/work".
-
-The syntax for install.sh is:
- install.sh [options]
- - This defaults to /usr/local/ paths commonly found in GNU Linux systems.
- - Accepts options for specifying specific install directory paths, such as a custom bin directory: "./install.sh --bindir /custom/program".
- - This is a simple installer and is not intended to be an all-solution.
- - For more powerful installation: manually install, use custom scripts, or use an appropriate build/install system.
- - When during development, consider using a work directory: "./install.sh --work /tmp/work".
- - The --work parameter in install.sh is essentially identical to the --prefix parameter, except that it is used for easier development scripting and also for communicating intent.
- - Note: The Featureless Make is a build system only and not an install system, this script may still be needed to install when using the Featureless Make.
-
-Build Example:
- ./bootstrap.sh build
-
-Install Example:
- ./install.sh
-
-Manual Install Example:
- cp -vR build/includes/* /usr/include/
- cp -vR build/libaries/shared/* /usr/lib/
- cp -vR build/programs/shared/* /usr/bin/
- cp -vR build/settings/* /etc/
-
-Alternatively, a primitive install script is provided to help install:
- ./install.sh
-
-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 status_code-0.5.0 project):
-build/
-├── bash
-├── includes
-│ └── level_3
-│ └── status_code.h
-├── libraries
-│ ├── shared
-│ │ ├── libstatus_code.so -> libstatus_code.so.0
-│ │ ├── libstatus_code.so.0 -> libstatus_code.so.0.5.0
-│ │ └── libstatus_code.so.0.5.0
-│ └── static
-│ └── libstatus_code.a
-├── objects
-│ └── status_code.c.o
-├── programs
-│ ├── shared
-│ │ └── status_code
-│ └── static
-│ └── status_code
-└── settings
+# fss-0002
+
+Bootstrap Readme Documentation:
+ The Featureless Linux Library provides a special bootstrap script in case the Featureless Make is not currently installed.
+
+ The GNU bash scripts, called bootstrap.sh and install.sh, are provided to perform this bootstrap process.
+
+ The syntax for bootstrap.sh is\:
+ bootstrap.sh <operation> [options]
+ - where operation is one of the following: 'build' or 'clean'.
+ - No 'install' command is provided, all of the files to install may be found in the build/ directory after the build command is executed.
+ - To install, either copy the files in the build directory to their appropriate destination or use the install.sh GNU bash script.
+ - For all operations and options, get help from the bootstrap script by appending the "--help" to the script, such as: "./bootstrap.sh --help".
+ - The monolithic build process is the simplest, which can be generated like the following: "./bootstrap.sh build -m monolithic".
+ - When during development, consider using a work directory, such as: "./bootstrap.sh --work /tmp/work".
+
+ The syntax for install.sh is\:
+ install.sh [options]
+ - This defaults to /usr/local/ paths commonly found in GNU Linux systems.
+ - Accepts options for specifying specific install directory paths, such as a custom bin directory: "./install.sh --bindir /custom/program".
+ - This is a simple installer and is not intended to be an all-solution.
+ - For more powerful installation: manually install, use custom scripts, or use an appropriate build/install system.
+ - When during development, consider using a work directory, such as: "./install.sh --work /tmp/work".
+ - The --work parameter in install.sh is similar to the --prefix parameter, except that it is used for easier development scripting and also for communicating intent and has a different directory structure.
+ - Note: The Featureless Make is a build system only and not an install system, this install.sh script may still be needed to install when using the Featureless Make.
+
+ Build Example\:
+ ./bootstrap.sh build
+
+ Install Example\:
+ ./install.sh
+
+ Manual Install Example\:
+ cp -vR build/includes/* /usr/include/
+ cp -vR build/libaries/shared/* /usr/lib/
+ cp -vR build/programs/shared/* /usr/bin/
+ cp -vR build/settings/* /etc/
+
+ Alternatively, a primitive install script is provided to help install\:
+ ./install.sh
+
+ 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 status_code-0.5.0 project)\:
+ build/
+ ├── documents
+ ├── includes
+ │ └── level_3
+ │ └── status_code.h
+ ├── libraries
+ │ ├── script
+ │ ├── shared
+ │ │ ├── libstatus_code.so -> libstatus_code.so.0
+ │ │ ├── libstatus_code.so.0 -> libstatus_code.so.0.5.0
+ │ │ └── libstatus_code.so.0.5.0
+ │ └── static
+ │ └── libstatus_code.a
+ ├── objects
+ │ ├── private-status_code.o
+ │ └── status_code.o
+ ├── programs
+ │ ├── script
+ │ ├── shared
+ │ │ └── status_code
+ │ └── static
+ │ └── status_code
+ ├── settings
+ └── stage
+ ├── libraries_shared.built
+ ├── libraries_static.built
+ ├── objects_static.built
+ ├── programs_shared.built
+ ├── programs_static.built
+ ├── skeleton.built
+ ├── sources_headers.built
+ ├── sources_script.built
+ └── sources_settings.built
+
+
+ Work Tree Structure Example at /tmp/work (using the status_code-0.5.0 project)\:
+ /tmp/work/
+ ├── includes
+ │ └── level_3
+ │ └── status_code.h
+ ├── libraries
+ │ ├── shared
+ │ │ ├── libstatus_code.so -> libstatus_code.so.0
+ │ │ ├── libstatus_code.so.0 -> libstatus_code.so.0.5.0
+ │ │ └── libstatus_code.so.0.5.0
+ │ └── static
+ │ └── libstatus_code.a
+ └── programs
+ ├── shared
+ │ └── status_code
+ └── static
+ └── status_code
-The Featureless Make, or Fake, is a build system opposing the GNU Make build (and install) system.
+# fss-0002
-The GNU Make system is powerful, but introduces too much unecessary functionality.
-In opposition to parts of how GNU Make works but also in honor of the success of the GNU Make system, the Featureless Make system follows the following concepts:
-- A build system is just that, a build system. Do not attempt to install, leave that to the distributor or individual installer.
-- A build system should not be trying to guess what is or is not on the system, instead, allow the distributor or individual installer to just specify what they want.
-- Provide a simple configuration design by using Featureless Settings Specification, or FSS.
-- Provide advanced functionality to provide flexibility with different system designs.
-- 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 "configure" script, like GNU Autoconf.
+Build Readme Documentation:
+ The Featureless Make, or Fake, is a build system opposing the GNU Make build (and install) system.
-The Fake is designed to specifically build the FLL and encourages the use of Fake to build FLL.
+ The GNU Make system is powerful, but introduces too much unecessary functionality.
+ In opposition to parts of how GNU Make works but also in honor of the success of the GNU Make system, the Featureless Make system follows the following concepts\:
+ - A build system is just that, a build system. Do not attempt to install, leave that to the distributor or individual installer.
+ - A build system should not be trying to guess what is or is not on the system, instead, allow the distributor or individual installer to just specify what they want.
+ - Provide a simple configuration design by using Featureless Settings Specification, or FSS.
+ - Provide advanced functionality to provide flexibility with different system designs.
+ - 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 "configure" script, like GNU Autoconf.
-The Fake provides two main build operations:
-- build: a lean purely FSS based build process, designed around specific but simple project designs (explicitly used by FLL).
-- make: a more powerful build process design to be more akin to GNU Make.
+ The Fake is designed to specifically build the FLL and encourages the use of Fake to build FLL.
-The Fake supports custom development environments using the "work" directory concept, such as "fake build -w /tmp/work".
+ The Fake provides two main build operations\:
+ - build: a lean purely FSS based build process, designed around specific but simple project designs (explicitly used by FLL).
+ - make: a more powerful build process design to be more akin to GNU Make.
-Build Example, using "build":
- fake build
+ The Fake supports custom development environments using the "work" directory concept, such as "fake build -w /tmp/work".
+ The "work" directory structure is identical to the build directory structure.
-Build Example, using "make":
- fake make
+ Build Example, using "build"\:
+ fake build
-See: FLL Fake project documents for further details on how to use the Fake system.
-See: FLL Fake project specifications for how to configure the build FSS files and make FSS files.
-See: readme.bootstrap for notes on installing.
+ Build Example, using "make"\:
+ fake make
+
+ Build Tree Structure Example (using the status_code-0.5.0 project)\:
+ build/
+ ├── documents
+ ├── includes
+ │ └── level_3
+ │ └── status_code.h
+ ├── libraries
+ │ ├── script
+ │ ├── shared
+ │ │ ├── libstatus_code.so -> libstatus_code.so.0
+ │ │ ├── libstatus_code.so.0 -> libstatus_code.so.0.5.0
+ │ │ └── libstatus_code.so.0.5.0
+ │ └── static
+ │ └── libstatus_code.a
+ ├── objects
+ │ ├── private-status_code.o
+ │ └── status_code.o
+ ├── programs
+ │ ├── script
+ │ ├── shared
+ │ │ └── status_code
+ │ └── static
+ │ └── status_code
+ ├── settings
+ └── stage
+ ├── libraries_shared.built
+ ├── libraries_static.built
+ ├── objects_static.built
+ ├── programs_shared.built
+ ├── programs_static.built
+ ├── skeleton.built
+ ├── sources_headers.built
+ ├── sources_script.built
+ └── sources_settings.built
+
+ Work Tree Structure Example at '/tmp/work' (using the status_code-0.5.0 project)\:
+ /tmp/work/
+ ├── includes
+ │ └── level_3
+ │ └── status_code.h
+ ├── libraries
+ │ ├── shared
+ │ │ ├── libstatus_code.so -> libstatus_code.so.0
+ │ │ ├── libstatus_code.so.0 -> libstatus_code.so.0.5.0
+ │ │ └── libstatus_code.so.0.5.0
+ │ └── static
+ │ └── libstatus_code.a
+ └── programs
+ ├── shared
+ │ └── status_code
+ └── static
+ └── status_code
+
+ See: FLL Fake project documents for further details on how to use the Fake system.
+ See: FLL Fake project specifications for how to configure the build FSS files and make FSS files.
+ See: readme.bootstrap for notes on installing.
-# fss-003
+# fss-002
#
# This readme file is inteded to provide a basic introduction to the Featureless Linux Library (FLL).
#
-This describes intent and purposes of the build settings file settings.
-For specific details on the allowed formatting, see the settings.txt under the specifications folder.
-
-build_compiler:
- Expects the name of the compiler, which generally should not be the path to the file, just the executable name.
- Currently only GCC is truly supported.
- All of the arguments assume the GCC, so if a non-GCC executable is provided supports the GCC argument structure, then that is by effect supported.
- Many of the parameters in the settings file can be changed if using a non-GCC, but there is certain hard-coded functionality that may still need changing.
-
-build_language:
- The language to build with.
- The only currently supported languages are: bash, c, and c++.
- The "bash" language is not currently implemented and needs some consideration because there is nothing to compile.
- The "bash" language will likely build a set of individual scripts, and perhaps script dependencies, into a single bash script.
-
-build_linker:
- Exactly like build_compiler, except for the linker.
- Currently only supports the GNU ar program.
- As with build_compiler, anything linker that supports the "ar" program parameters is effectively supported.
-
-build_libraries:
- A collection of libraries to be linked against.
- The should contain the compiler specific parameter parts, such as the "-l" prefix.
- The order of these may matter if GCC (or the linker via GCC) is order sensitive.
-
-build_script:
- When "yes", the build process will build any scripts, such as bash script.
- This is currently not implemented.
-
-build_shared:
- When "yes", the build process will compile any source code for any supported language that supports shared library linking.
-
-build_sources_headers:
- A collection of header files.
- May include a relative sub-path to each individual header (such as "level_0/a.h level_0/b.h level_1/c.h".
- The order of these may matter if GCC (or the linker via GCC) is order sensitive.
-
-build_sources_library:
- A collection of library related source files.
- May include a relative sub-path to each individual header (such as "level_0/a.c level_0/b.c level_1/c.c".
- The order of these may matter if GCC (or the linker via GCC) is order sensitive.
- These files are used when compiling the library.
-
-build_sources_program:
- A collection of program related source files.
- May include a relative sub-path to each individual header (such as "level_0/a.h level_0/b.h level_1/c.h".
- The order of these may matter if GCC (or the linker via GCC) is order sensitive.
- These files are used when compiling the program.
-
-build_sources_setting:
- A collection of settings files.
- These are settings files used by the project and are simply copied over to the build directory.
- Unless a pre-process script (or in theory post-process script) is configured to alter these, they are not modified.
-
-build_sources_script:
- A collection of script files.
- These are settings files used by the project and are simply copied over to the build directory.
- Unless a pre-process script (or in theory post-process script) is configured to alter these, they are not modified.
- Unlike the "compile_language" setting "bash", this is not for built Bash script, but is instead for any valid scripting language (including Bash).
- These could be in any language.
-
-build_static:
- When "yes", the build process will compile any source code for any supported language that supports static library linking.
-
-defines_all:
- A collection of macro names.
- These will be appended to the compiler for compiled languages such as C and C++.
- These will automatically have "-D" prepended to them.
- These are applied to both shared and static builds.
-
-defines_shared:
- A collection of macro names.
- These will be appended to the compiler for compiled languages such as C and C++.
- These will automatically have "-D" prepended to them.
- These are applied to only shared builds.
-
-defines_static:
- A collection of macro names.
- These will be appended to the compiler for compiled languages such as C and C++.
- These will automatically have "-D" prepended to them.
- These are applied to only static builds.
-
-environment:
- A collection of environment names to pass from the callers environment into the environment of executed programs.
- For security and integrity reasons, all environment variables are removed when calling user-space programs, such as "gcc".
- There are times when someone desires that an environment variable be exposed to the user-space programs.
- Add them here and they will be available in the environment of all user-space programs executed.
-
-flags_all:
- A collection of any flag support by the "build_compiler", such as GCC.
- These are applied to both shared and static builds.
-
-flags_shared:
- A collection of any flag support by the "build_compiler", such as GCC.
- These are applied to only shared builds.
-
-flags_static:
- A collection of any flag support by the "build_compiler", such as GCC.
- These are applied to only static builds.
-
-modes:
- A collection of available build modes.
- Build modes provide custom variants of the build process where certain settings are appended onto others.
- See the settings.txt specification for a list of which setting names this applies to.
-
-modes_default:
- The name of the default mode to use when no mode is specified.
- This must be one of the modes specified in the "modes" setting.
-
-path_headers:
- A sub-path in which headers are to be installed under.
- This is primarily for the FLL project to build the "level_0", "level_1", etc.. headers without requiring that structure within the source.
- A resulting build destination for a path_headers of "level_0" would be something like "build/includes/level_0/".
-
-path_language:
- A sub-path in which to find the source files for the currently defined language.
- If the "build_language" is changed, it is recommended to change this as well to match.
-
-path_library_script:
- A sub-path representing when the built library script files are placed.
- This is currently not implemented.
-
-path_library_shared:
- A sub-path representing when the built shared library files are placed.
-
-path_library_static:
- A sub-path representing when the built shared library files are placed.
-
-path_program_script:
- A sub-path representing when the built program script files are placed.
- This is currently not implemented.
-
-path_program_shared:
- A sub-path representing when the built shared program files are placed.
-
-path_program_static:
- A sub-path representing when the built shared program files are placed.
-
-project_name:
- The name of the project.
- If program sources are specified, then this will be used as the program name.
- If library sources are specified, then this will be used in the library name, such as "libX.so" where "X" would be the "project_name" value.
-
-process_post:
- The filename (relative to the "data/build/" directory) of a script to execute after the "build" operation successfully completes.
- A small subset of parameters from the main execution are passed to this script during execution as parameters (using short parameter codes):
- Color context parameters, such as: "+l", "+n", and "+d".
- Operation mode, such as: "build", "clean", "make", or "skeleton".
- Verbosity parameters, such as: "+q", "+D", or "+V".
- Define parameters, such as "-d X" or "-d Y", whereas "X" or "Y" are any valid argument associated with "-d".
- Process parameter, such as "-p X", whereas "X" is any valid argument associated with "-p".
- Settings parameter, such as "-s X', whereas "X" is any valid argument associated with "-s".
- Build Path parameter, such as "-b X', whereas "X" is any valid argument associated with "-b".
- Data Path parameter, such as "-D X', whereas "X" is any valid argument associated with "-D".
- Sources Path parameter, such as "-S X', whereas "X" is any valid argument associated with "-S".
- Work Path parameter, such as "-w X', whereas "X" is any valid argument associated with "-w".
-
-search_exclusive:
- When "yes", the search path during compile for shared libraries will only include shared library paths.
- When "no", the search path during compile time for shared libraries will include shared library paths followed by static library paths.
- Setting this to "yes" helps prevent static libraries from ended up in shared libraries (very useful when bootstrapping a system).
- Setting this to "no" allows for including static libraries if no shared libraries are found but static are.
- This does not alter search paths introduced automatically by the "build_compiler" or "build_linker", so it is still possible for static libraries to end up even when this is set to "yes".
-
-search_shared:
- When "yes", shared library paths are searched during compile.
- Both this and search_static cannot be "no" at the same time.
-
-search_shared:
- When "yes", static library paths are searched during compile.
- Both this and search_shared cannot be "no" at the same time.
-
-version_major:
- The major version number (or in theory any characters allowed in a filename).
- This should generally be a positive number or 0.
- Anything else is currently untested but allowed.
- With a structure of "A.B.C", the major version would be the "A".
-
-version_minor:
- The minor version number (or in theory any characters allowed in a filename).
- This should generally be a positive number or 0.
- Anything else is currently untested but allowed.
- With a structure of "A.B.C", the minor version would be the "B".
-
-version_micro:
- The micro version number (or in theory any characters allowed in a filename).
- This should generally be a positive number or 0.
- Anything else is currently untested but allowed.
- With a structure of "A.B.C", the micro version would be the "C".
-
-version_target:
- Designates which version should be used when building the shared library and creating the respective symbolic links.
- When "major" is used, a shared library is generated with "-Wl,-soname,libX.A", whereas "X" is the "project_name" and "A" is the major version.
- When "minor" is used, a shared library is generated with "-Wl,-soname,libX.A.B", whereas "X" is the "project_name" and "A.B" is the major and minor versions, respectively.
- When "micro" is used, a shared library is generated with "-Wl,-soname,libX.A.B.C", whereas "X" is the "project_name" and "A.B.C" is the major, minor, and micro versions, respectively.
+# fss-0002
+
+Settings Documentation:
+ This describes intent and purposes of the build settings file settings.
+ For specific details on the allowed formatting, see the settings.txt under the specifications folder.
+
+ build_compiler\:
+ Expects the name of the compiler, which generally should not be the path to the file, just the executable name.
+ Currently only GCC is truly supported.
+ All of the arguments assume the GCC, so if a non-GCC executable is provided supports the GCC argument structure, then that is by effect supported.
+ Many of the parameters in the settings file can be changed if using a non-GCC, but there is certain hard-coded functionality that may still need changing.
+
+ build_language\:
+ The language to build with.
+ The only currently supported languages are: bash, c, and c++.
+ The "bash" language is not currently implemented and needs some consideration because there is nothing to compile.
+ The "bash" language will likely build a set of individual scripts, and perhaps script dependencies, into a single bash script.
+
+ build_linker\:
+ Exactly like build_compiler, except for the linker.
+ Currently only supports the GNU ar program.
+ As with build_compiler, anything linker that supports the "ar" program parameters is effectively supported.
+
+ build_libraries\:
+ A collection of libraries to be linked against.
+ The should contain the compiler specific parameter parts, such as the "-l" prefix.
+ The order of these may matter if GCC (or the linker via GCC) is order sensitive.
+
+ build_script\:
+ When "yes", the build process will build any scripts, such as bash script.
+ This is currently not implemented.
+
+ build_shared\:
+ When "yes", the build process will compile any source code for any supported language that supports shared library linking.
+
+ build_sources_headers\:
+ A collection of header files.
+ May include a relative sub-path to each individual header (such as "level_0/a.h level_0/b.h level_1/c.h".
+ The order of these may matter if GCC (or the linker via GCC) is order sensitive.
+
+ build_sources_library\:
+ A collection of library related source files.
+ May include a relative sub-path to each individual header (such as "level_0/a.c level_0/b.c level_1/c.c".
+ The order of these may matter if GCC (or the linker via GCC) is order sensitive.
+ These files are used when compiling the library.
+
+ build_sources_program\:
+ A collection of program related source files.
+ May include a relative sub-path to each individual header (such as "level_0/a.h level_0/b.h level_1/c.h".
+ The order of these may matter if GCC (or the linker via GCC) is order sensitive.
+ These files are used when compiling the program.
+
+ build_sources_setting\:
+ A collection of settings files.
+ These are settings files used by the project and are simply copied over to the build directory.
+ Unless a pre-process script (or in theory post-process script) is configured to alter these, they are not modified.
+
+ build_sources_script\:
+ A collection of script files.
+ These are settings files used by the project and are simply copied over to the build directory.
+ Unless a pre-process script (or in theory post-process script) is configured to alter these, they are not modified.
+ Unlike the "compile_language" setting "bash", this is not for built Bash script, but is instead for any valid scripting language (including Bash).
+ These could be in any language.
+
+ build_static\:
+ When "yes", the build process will compile any source code for any supported language that supports static library linking.
+
+ defines_all\:
+ A collection of macro names.
+ These will be appended to the compiler for compiled languages such as C and C++.
+ These will automatically have "-D" prepended to them.
+ These are applied to both shared and static builds.
+
+ defines_shared\:
+ A collection of macro names.
+ These will be appended to the compiler for compiled languages such as C and C++.
+ These will automatically have "-D" prepended to them.
+ These are applied to only shared builds.
+
+ defines_static\:
+ A collection of macro names.
+ These will be appended to the compiler for compiled languages such as C and C++.
+ These will automatically have "-D" prepended to them.
+ These are applied to only static builds.
+
+ environment\:
+ A collection of environment names to pass from the callers environment into the environment of executed programs.
+ For security and integrity reasons, all environment variables are removed when calling user-space programs, such as "gcc".
+ There are times when someone desires that an environment variable be exposed to the user-space programs.
+ Add them here and they will be available in the environment of all user-space programs executed.
+
+ flags_all\:
+ A collection of any flag support by the "build_compiler", such as GCC.
+ These are applied to both shared and static builds.
+
+ flags_shared\:
+ A collection of any flag support by the "build_compiler", such as GCC.
+ These are applied to only shared builds.
+
+ flags_static\:
+ A collection of any flag support by the "build_compiler", such as GCC.
+ These are applied to only static builds.
+
+ modes\:
+ A collection of available build modes.
+ Build modes provide custom variants of the build process where certain settings are appended onto others.
+ See the settings.txt specification for a list of which setting names this applies to.
+
+ modes_default\:
+ The name of the default mode to use when no mode is specified.
+ This must be one of the modes specified in the "modes" setting.
+
+ path_headers\:
+ A sub-path in which headers are to be installed under.
+ This is primarily for the FLL project to build the "level_0", "level_1", etc.. headers without requiring that structure within the source.
+ A resulting build destination for a path_headers of "level_0" would be something like "build/includes/level_0/".
+
+ path_language\:
+ A sub-path in which to find the source files for the currently defined language.
+ If the "build_language" is changed, it is recommended to change this as well to match.
+
+ path_library_script\:
+ A sub-path representing when the built library script files are placed.
+ This is currently not implemented.
+
+ path_library_shared\:
+ A sub-path representing when the built shared library files are placed.
+
+ path_library_static\:
+ A sub-path representing when the built shared library files are placed.
+
+ path_program_script\:
+ A sub-path representing when the built program script files are placed.
+ This is currently not implemented.
+
+ path_program_shared\:
+ A sub-path representing when the built shared program files are placed.
+
+ path_program_static\:
+ A sub-path representing when the built shared program files are placed.
+
+ project_name\:
+ The name of the project.
+ If program sources are specified, then this will be used as the program name.
+ If library sources are specified, then this will be used in the library name, such as "libX.so" where "X" would be the "project_name" value.
+
+ process_post\:
+ The filename (relative to the "data/build/" directory) of a script to execute after the "build" operation successfully completes.
+ A small subset of parameters from the main execution are passed to this script during execution as parameters (using short parameter codes)\:
+ Color context parameters, such as: "+l", "+n", and "+d".
+ Operation mode, such as: "build", "clean", "make", or "skeleton".
+ Verbosity parameters, such as: "+q", "+D", or "+V".
+ Define parameters, such as "-d X" or "-d Y", whereas "X" or "Y" are any valid argument associated with "-d".
+ Process parameter, such as "-p X", whereas "X" is any valid argument associated with "-p".
+ Settings parameter, such as "-s X', whereas "X" is any valid argument associated with "-s".
+ Build Path parameter, such as "-b X', whereas "X" is any valid argument associated with "-b".
+ Data Path parameter, such as "-D X', whereas "X" is any valid argument associated with "-D".
+ Sources Path parameter, such as "-S X', whereas "X" is any valid argument associated with "-S".
+ Work Path parameter, such as "-w X', whereas "X" is any valid argument associated with "-w".
+
+ search_exclusive\:
+ When "yes", the search path during compile for shared libraries will only include shared library paths.
+ When "no", the search path during compile time for shared libraries will include shared library paths followed by static library paths.
+ Setting this to "yes" helps prevent static libraries from ended up in shared libraries (very useful when bootstrapping a system).
+ Setting this to "no" allows for including static libraries if no shared libraries are found but static are.
+ This does not alter search paths introduced automatically by the "build_compiler" or "build_linker", so it is still possible for static libraries to end up even when this is set to "yes".
+
+ search_shared\:
+ When "yes", shared library paths are searched during compile.
+ Both this and search_static cannot be "no" at the same time.
+
+ search_shared\:
+ When "yes", static library paths are searched during compile.
+ Both this and search_shared cannot be "no" at the same time.
+
+ version_major\:
+ The major version number (or in theory any characters allowed in a filename).
+ This should generally be a positive number or 0.
+ Anything else is currently untested but allowed.
+ With a structure of "A.B.C", the major version would be the "A".
+
+ version_minor\:
+ The minor version number (or in theory any characters allowed in a filename).
+ This should generally be a positive number or 0.
+ Anything else is currently untested but allowed.
+ With a structure of "A.B.C", the minor version would be the "B".
+
+ version_micro\:
+ The micro version number (or in theory any characters allowed in a filename).
+ This should generally be a positive number or 0.
+ Anything else is currently untested but allowed.
+ With a structure of "A.B.C", the micro version would be the "C".
+
+ version_target\:
+ Designates which version should be used when building the shared library and creating the respective symbolic links.
+ When "major" is used, a shared library is generated with "-Wl,-soname,libX.A", whereas "X" is the "project_name" and "A" is the major version.
+ When "minor" is used, a shared library is generated with "-Wl,-soname,libX.A.B", whereas "X" is the "project_name" and "A.B" is the major and minor versions, respectively.
+ When "micro" is used, a shared library is generated with "-Wl,-soname,libX.A.B.C", whereas "X" is the "project_name" and "A.B.C" is the major, minor, and micro versions, respectively.
-The build settings "defines" file follows the FSS-0000 (Basic) format.
+# fss-002
-Each Object represents a specific a macro name to be defined during compilation.
-Each Content represents documentation explaining the intent and purpose of that define.
+Defines Specification:
+ The build settings "defines" file follows the FSS-0000 (Basic) format.
-The Object name has further restrictions than FSS-0000 requires.
-These restrictions are that the Object must only evaluate to a valid C/C++ macro name.
-This is essentially means only Word characters.
+ Each Object represents a specific a macro name to be defined during compilation.
+ Each Content represents documentation explaining the intent and purpose of that define.
-It is recommended that each define begin and end with an underscore.
-The Featureless Make program will convert the define as follows when compiling:
-- Object name = "_en_my_macro_" will become "-D_en_my_macro_".
+ The Object name has further restrictions than FSS-0000 requires.
+ These restrictions are that the Object must only evaluate to a valid C/C++ macro name.
+ This is essentially means only Word characters.
+
+ It is recommended that each define begin and end with an underscore.
+ The Featureless Make program will convert the define as follows when compiling\:
+ - Object name = "_en_my_macro_" will become "-D_en_my_macro_".
-The build settings "dependencies" file follows the FSS-0000 (Basic) format.
+# fss-002
-Each Object represents a specific project name as it would be linked against.
-Each Content must not be specified, only FSS-0000 Object names are allowed.
+Dependencies Specification:
+ The build settings "dependencies" file follows the FSS-0000 (Basic) format.
-This file only holds dependencies provided by the FLL 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.
+ Each Object represents a specific project name as it would be linked against.
+ Each Content must not be specified, only FSS-0000 Object names are allowed.
+
+ This file only holds dependencies provided by the FLL 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.
-The build settings "settings" file follows the FSS-0001 (Extended) format.
+# fss-002
-Each Object represents a settings property name.
-There is only a distinct set of setting property names (see below).
+Settings Specification:
+ The build settings "settings" file follows the FSS-0001 (Extended) format.
-Each Content represents the values associated with that property.
-Additional restrictions are applied to each Content depending on each specific Object name (see below).
+ Each Object represents a settings property name.
+ There is only a distinct set of setting property names (see below).
-Object Names and their respective Content purpose/restrictions:
- "build_compiler": Must only be a valid filename.
- "build_language": Must only be one of: "bash", "c", or "c++".
- "build_linker": Must only be a valid filename.
- "build_libraries": Must only contain any number of valid library include arguments that are valid for the compiler defined in "build_compiler" Object.
- "build_script": Must only one of: "yes" or "no".
- "build_shared": Must only one of: "yes" or "no".
- "build_sources_headers": Must only contain any number of valid filenames.
- "build_sources_library": Must only contain any number of valid filenames.
- "build_sources_program": Must only contain any number of valid filenames.
- "build_sources_setting": Must only contain any number of valid filenames.
- "build_sources_script": Must only contain any number of valid filenames.
- "build_static": Must only one of: "yes" or "no".
- "defines_all": Must only contain any number of valid C/C++ macro names.
- "defines_static": Must only contain any number of valid C/C++ macro names.
- "defines_shared": Must only contain any number of valid C/C++ macro names.
- "environment": Environment variable names, case-sensitive, usually uppercase. May only contain characters allowed in an environment variable.
- "flags_all": Must only contain any number of parameters supported by the compiler specified in "build_compiler".
- "flags_library": Must only contain any number of parameters supported by the compiler specified in "build_compiler".
- "flags_program": Must only contain any number of parameters supported by the compiler specified in "build_compiler".
- "flags_shared": Must only contain any number of parameters supported by the compiler specified in "build_compiler".
- "flags_static": Must only contain any number of parameters supported by the compiler specified in "build_compiler".
- "modes": Any valid word character, '-', or '+'.
- "modes_default": May only be a single complete Content word defined in "modes" Object.
- "path_headers": Must be a single valid path.
- "path_language": Must be a single valid path.
- "path_library_script": Must be a single valid path.
- "path_library_shared": Must be a single valid path.
- "path_library_static": Must be a single valid path.
- "path_program_script": Must be a single valid path.
- "path_program_shared": Must be a single valid path.
- "path_program_static": Must be a single valid path.
- "project_name": Must only contain characters allowed in a filename.
- "process_post": Must contain only a single valid filename.
- "process_pre": Must contain only a single valid filename.
- "search_exclusive": Must only one of: "yes" or "no".
- "search_shared": Must only one of: "yes" or "no".
- "search_static": Must only one of: "yes" or "no".
- "version_major": Must only be a single value containg valid filename characters.
- "version_minor": Must only be a single value containg valid filename characters.
- "version_micro": Must only be a single value containg valid filename characters.
- "version_target": Must only be one of: "major", "minor", or "micro".
+ Each Content represents the values associated with that property.
+ Additional restrictions are applied to each Content depending on each specific Object name (see below).
-The following Object names support having a "-" and a "mode" name, such as "build_libraries-individual" for a mode called "individual":
- "build_libraries"
- "build_sources_headers"
- "build_sources_library"
- "build_sources_program"
- "build_sources_setting"
- "build_sources_script"
- "defines_all"
- "defines_shared"
- "defines_static"
- "environment"
- "flags_all"
- "flags_library"
- "flags_program"
- "flags_shared"
- "flags_static"
+ Object Names and their respective Content purpose/restrictions\:
+ "build_compiler": Must only be a valid filename.
+ "build_language": Must only be one of: "bash", "c", or "c++".
+ "build_linker": Must only be a valid filename.
+ "build_libraries": Must only contain any number of valid library include arguments that are valid for the compiler defined in "build_compiler" Object.
+ "build_script": Must only one of: "yes" or "no".
+ "build_shared": Must only one of: "yes" or "no".
+ "build_sources_headers": Must only contain any number of valid filenames.
+ "build_sources_library": Must only contain any number of valid filenames.
+ "build_sources_program": Must only contain any number of valid filenames.
+ "build_sources_setting": Must only contain any number of valid filenames.
+ "build_sources_script": Must only contain any number of valid filenames.
+ "build_static": Must only one of: "yes" or "no".
+ "defines_all": Must only contain any number of valid C/C++ macro names.
+ "defines_static": Must only contain any number of valid C/C++ macro names.
+ "defines_shared": Must only contain any number of valid C/C++ macro names.
+ "environment": Environment variable names, case-sensitive, usually uppercase. May only contain characters allowed in an environment variable.
+ "flags_all": Must only contain any number of parameters supported by the compiler specified in "build_compiler".
+ "flags_library": Must only contain any number of parameters supported by the compiler specified in "build_compiler".
+ "flags_program": Must only contain any number of parameters supported by the compiler specified in "build_compiler".
+ "flags_shared": Must only contain any number of parameters supported by the compiler specified in "build_compiler".
+ "flags_static": Must only contain any number of parameters supported by the compiler specified in "build_compiler".
+ "modes": Any valid word character, '-', or '+'.
+ "modes_default": May only be a single complete Content word defined in "modes" Object.
+ "path_headers": Must be a single valid path.
+ "path_language": Must be a single valid path.
+ "path_library_script": Must be a single valid path.
+ "path_library_shared": Must be a single valid path.
+ "path_library_static": Must be a single valid path.
+ "path_program_script": Must be a single valid path.
+ "path_program_shared": Must be a single valid path.
+ "path_program_static": Must be a single valid path.
+ "project_name": Must only contain characters allowed in a filename.
+ "process_post": Must contain only a single valid filename.
+ "process_pre": Must contain only a single valid filename.
+ "search_exclusive": Must only one of: "yes" or "no".
+ "search_shared": Must only one of: "yes" or "no".
+ "search_static": Must only one of: "yes" or "no".
+ "version_major": Must only be a single value containg valid filename characters.
+ "version_minor": Must only be a single value containg valid filename characters.
+ "version_micro": Must only be a single value containg valid filename characters.
+ "version_target": Must only be one of: "major", "minor", or "micro".
+
+ The following Object names support having a "-" and a "mode" name, such as "build_libraries-individual" for a mode called "individual"\:
+ "build_libraries"
+ "build_sources_headers"
+ "build_sources_library"
+ "build_sources_program"
+ "build_sources_setting"
+ "build_sources_script"
+ "defines_all"
+ "defines_shared"
+ "defines_static"
+ "environment"
+ "flags_all"
+ "flags_library"
+ "flags_program"
+ "flags_shared"
+ "flags_static"
-Featureless Settings Specification: 0000 - Basic
+# fss-0002
-Each Object starts at the beginning of a line and whitespace to the left of the Object is not treated as an object.
-Whitespace separates an Object from the Content.
-An Object may be followed by a newline, in which case means that the Object has no Content.
+Featureless Settings Specification: 0000 - Basic:
+ Each Object starts at the beginning of a line and whitespace to the left of the Object is not treated as an object.
+ Whitespace separates an Object from the Content.
+ An Object may be followed by a newline, in which case means that the Object has no Content.
-Content exists on the same line as the Object.
-Content consists of everything following the first non-whitespace character until the newline.
-Content includes trailing whitespace before newline is reached.
-Content does not include the leading whitespace.
-No delimits are supported in the content.
+ Content exists on the same line as the Object.
+ Content consists of everything following the first non-whitespace character until the newline.
+ Content includes trailing whitespace before newline is reached.
+ Content does not include the leading whitespace.
+ No delimits are supported in the content.
-Key:
- \s = whitespace, except newline.
- \b = either whitespace or printable, except newline.
- \q = non-whitespace or quoteded whitespace, no whitespace outside of quotes.
- \n = newline.
- * = 0 or more occurrences.
- + = one or more occurrences.
+ Key\:
+ \s = whitespace, except newline.
+ \b = either whitespace or printable, except newline.
+ \q = non-whitespace or quoteded whitespace, no whitespace outside of quotes.
+ \n = newline.
+ * = 0 or more occurrences.
+ + = one or more occurrences.
-Structure:
- \s*\q+\s+\b*\n
+ Structure\:
+ \s*\q+\s+\b*\n
-Example:
- # fss-0000
- # valid comments are ignored.
- "The Object" Content until newline.
- Second object set.
+ Example\:
+ # fss-0000
+ # valid comments are ignored.
+ "The Object" Content until newline.
+ Second object set.
-Object would be:
- 1) The Object
- 2) Second
+ Object would be\:
+ 1) The Object
+ 2) Second
-Content would be:
- 1.1) Content until newline.
- 2.1) object set.
+ Content would be\:
+ 1.1) Content until newline.
+ 2.1) object set.
-Featureless Settings Specification: 0001 - Extended
+# fss-0002
-Each Object starts at the beginning of a line and whitespace to the left of the Object is not treated as an object.
-Whitespace separates an Object from the Content.
-An Object may be followed by a newline, in which case means that the Object has no Content.
+Featureless Settings Specification: 0001 - Extended:
+ Each Object starts at the beginning of a line and whitespace to the left of the Object is not treated as an object.
+ Whitespace separates an Object from the Content.
+ An Object may be followed by a newline, in which case means that the Object has no Content.
-Content exists on the same line as the Object.
-Content of whitespace separated sets until the newline.
-Any number of sets may exist in the Content until the newline is reached.
+ Content exists on the same line as the Object.
+ Content of whitespace separated sets until the newline.
+ Any number of sets may exist in the Content until the newline is reached.
-Key:
- \s = whitespace, except newline.
- \b = either whitespace or printable, except newline.
- \q = non-whitespace or quoteded whitespace, no whitespace outside of quotes.
- \n = newline.
- * = 0 or more occurrences.
- + = one or more occurrences.
- ()* = grouping that repeats 0 or more times.
+ Key\:
+ \s = whitespace, except newline.
+ \b = either whitespace or printable, except newline.
+ \q = non-whitespace or quoteded whitespace, no whitespace outside of quotes.
+ \n = newline.
+ * = 0 or more occurrences.
+ + = one or more occurrences.
+ ()* = grouping that repeats 0 or more times.
-Structure:
- \s*\q+\s+(\s*\q+)*\s*\n
+ Structure\:
+ \s*\q+\s+(\s*\q+)*\s*\n
-Example:
- # fss-0001
- # valid comments are ignored.
- "The Object" Content "content 2" content_3.
- Second object set.
+ Example\:
+ # fss-0001
+ # valid comments are ignored.
+ "The Object" Content "content 2" content_3.
+ Second object set.
-Objects would be:
- 1) The Object
- 2) Second
+ Objects would be\:
+ 1) The Object
+ 2) Second
-Contents would be:
- 1.1) Content
- 1.2) content 2
- 1.3) content_3.
- 2.1) object
- 2.2) set.
+ Contents would be\:
+ 1.1) Content
+ 1.2) content 2
+ 1.3) content_3.
+ 2.1) object
+ 2.2) set.
-Featureless Settings Specification: 0002 - Basic List
-
-Each Object starts at the beginning of a line and whitespace to the left of the Object is not treated as an object.
-A colon followed by any whitespace until a newline terminates a valid Object.
-Non-whitespace may not follow the colon of a valid Object.
-
-Content exists on every line following a valid object until the end of file (or string) or until the next valid Object is found.
-Any content that could be interpreted as a valid Object must have the colon delimited.
-
-There is no single-quote or double-quote delimitation in this specification.
-Only the colon that would result in a valid Object can be delimited.
-
-Key:
- \s = whitespace, except newline.
- \o = any printable character, except unescaped ':'.
- \l = any printable character or whitespace, except unescaped ':'.
- \c = either whitespace or printable, including newline, that not interpretable as an Object.
- \n = newline.
- * = 0 or more occurrences.
-
-Structure:
- \s*\o\l*:\s*\n\c*\n*
-
-Example:
- # fss-0002
- # valid comments are ignored.
- "The Object":
- Does not need to be quoted.
- This: does not need to be delimited.
- This Does\:
- Second:
- Continues until EOS/EOF.
- All whitespace, including newline (and leading whitespace) is part of content.
- # Valid comments are still ignored.
-
-Objects would be:
- 1) "The Object"
- 2) Second
-
-Contents would be:
- 1.1) Does not need to be quoted.
- This: does not need to be delimited.
- This Does:
- 2.1) Continues until EOS/EOF.
- All whitespace, including newline (and leading whitespace) is part of content.
+# fss-0002
+#
+# Note: this file is in fss-0002 format and as a result the example below has to be escaped (can potentially be confusing when reading this raw).
+
+Featureless Settings Specification: 0002 - Basic List:
+ Each Object starts at the beginning of a line and whitespace to the left of the Object is not treated as an object.
+ A colon followed by any whitespace until a newline terminates a valid Object.
+ Non-whitespace may not follow the colon of a valid Object.
+
+ Content exists on every line following a valid object until the end of file (or string) or until the next valid Object is found.
+ Any content that could be interpreted as a valid Object must have the colon delimited.
+
+ There is no single-quote or double-quote delimitation in this specification.
+ Only the colon that would result in a valid Object can be delimited.
+
+ Key\:
+ \s = whitespace, except newline.
+ \o = any printable character, except unescaped ':'.
+ \l = any printable character or whitespace, except unescaped ':'.
+ \c = either whitespace or printable, including newline, that not interpretable as an Object.
+ \n = newline.
+ * = 0 or more occurrences.
+
+ Structure\:
+ \s*\o\l*:\s*\n\c*\n*
+
+ Example\:
+ # fss-0002
+ # valid comments are ignored.
+ "The Object"\:
+ Does not need to be quoted.
+ This: does not need to be delimited.
+ This Does\\\:
+ Second\:
+ Continues until EOS/EOF.
+ All whitespace, including newline (and leading whitespace) is part of content.
+ # Valid comments are still ignored.
+
+ Objects would be\:
+ 1) "The Object"
+ 2) Second
+
+ Contents would be\:
+ 1.1) Does not need to be quoted.
+ This: does not need to be delimited.
+ This Does\:
+ 2.1) Continues until EOS/EOF.
+ All whitespace, including newline (and leading whitespace) is part of content.
-Featureless Settings Specification: 0003 - Extended List
-
-Each Object starts at the beginning of a line and whitespace to the left of the Object is not treated as an object.
-An open-brace ({) followed by any whitespace until a newline terminates a valid Object.
-Non-whitespace may not follow the open-brace of a valid Object.
-
-Content exists on every line following a valid object until the end of file (or string) or until a non-delimited close-brace (}).
-Any Content that could be interpreted as an end of content must be delimited if it should be part of the content.
-Whitespace may follow a valid close-brace but a terminating newline must be present to designate a valid end of content.
-
-There is no single-quote or double-quote delimitation in this specification.
-Only the open-brace that would result in a valid Object or the close-brace that would terminate valid Content can be delimited.
-Each delimit slash in an open-brace is treated as a potential delimit such that two slashes represents a single delimited slash ('\\\{' would represent '\{').
-Only the first delimit slash in a close-brace is treated as a potential delimit ('\\\}' would represent '\\}').
-
-Key:
- \s = whitespace, except newline.
- \o = any printable character, except unescaped '{'.
- \l = any printable character or whitespace, except unescaped '}'.
- \c = either whitespace or printable, including newline, that is not interpretable as an Object.
- \n = newline.
- * = 0 or more occurrences.
-
-Structure:
- \s*\o\l*{\s*\n\c*\n\s*}\s*\n
-
-Example:
- # fss-0003
- # valid comments are ignored.
- "The Object" {
- Does not need to be quoted.
- This: does not need to be delimited.
- \}
- }
- Second {
- Continues until EOS/EOF.
- All whitespace, including newline (and leading whitespace) is part of content.
- # Valid comments are still ignored.
- }
-
-Objects would be:
- 1) "The Object"
- 2) Second
-
-Contents would be:
- 1.1) Does not need to be quoted.
- This: does not need to be delimited.
- }
- 2.1) Continues until EOS/EOF.
- All whitespace, including newline (and leading whitespace) is part of content.
+# fss-0002
+
+Featureless Settings Specification: 0003 - Extended List:
+ Each Object starts at the beginning of a line and whitespace to the left of the Object is not treated as an object.
+ An open-brace ({) followed by any whitespace until a newline terminates a valid Object.
+ Non-whitespace may not follow the open-brace of a valid Object.
+
+ Content exists on every line following a valid object until the end of file (or string) or until a non-delimited close-brace (}).
+ Any Content that could be interpreted as an end of content must be delimited if it should be part of the content.
+ Whitespace may follow a valid close-brace but a terminating newline must be present to designate a valid end of content.
+
+ There is no single-quote or double-quote delimitation in this specification.
+ Only the open-brace that would result in a valid Object or the close-brace that would terminate valid Content can be delimited.
+ Each delimit slash in an open-brace is treated as a potential delimit such that two slashes represents a single delimited slash ('\\\{' would represent '\{').
+ Only the first delimit slash in a close-brace is treated as a potential delimit ('\\\}' would represent '\\}').
+
+ Key\:
+ \s = whitespace, except newline.
+ \o = any printable character, except unescaped '{'.
+ \l = any printable character or whitespace, except unescaped '}'.
+ \c = either whitespace or printable, including newline, that is not interpretable as an Object.
+ \n = newline.
+ * = 0 or more occurrences.
+
+ Structure\:
+ \s*\o\l*{\s*\n\c*\n\s*}\s*\n
+
+ Example\:
+ # fss-0003
+ # valid comments are ignored.
+ "The Object" {
+ Does not need to be quoted.
+ This: does not need to be delimited.
+ \}
+ }
+ Second {
+ Continues until EOS/EOF.
+ All whitespace, including newline (and leading whitespace) is part of content.
+ # Valid comments are still ignored.
+ }
+
+ Objects would be\:
+ 1) "The Object"
+ 2) Second
+
+ Contents would be\:
+ 1.1) Does not need to be quoted.
+ This: does not need to be delimited.
+ }
+ 2.1) Continues until EOS/EOF.
+ All whitespace, including newline (and leading whitespace) is part of content.
-Featureless Settings Specification: 0004 - Very Basic List
+# fss-0002
-This is a fss-0002 Basic List whose Content is then processed as fss-0000 Basic.
+Featureless Settings Specification: 0004 - Very Basic List:
+ This is a fss-0002 Basic List whose Content is then processed as fss-0000 Basic.
-TODO: further document this.
+ TODO: further document this.
-Featureless Settings Specification: 0005 - Somewhat Basic List
+# fss-0002
-This is a fss-0002 Basic List whose Content is then processed as fss-0001 Extended.
+Featureless Settings Specification: 0005 - Somewhat Basic List:
+ This is a fss-0002 Basic List whose Content is then processed as fss-0001 Extended.
-TODO: further document this.
+ TODO: further document this.
-Featureless Settings Specification: 0006 - Somewhat Extended List
+# fss-0002
-This is a fss-0003 Extended List whose Content is then processed as fss-0000 Basic.
+Featureless Settings Specification: 0006 - Somewhat Extended List:
+ This is a fss-0003 Extended List whose Content is then processed as fss-0000 Basic.
-TODO: further document this.
+ TODO: further document this.
-Featureless Settings Specification: 0007 - Very Extended List
+# fss-0002
-This is a fss-0003 Extended List whose Content is then processed as fss-0001 Extended.
+Featureless Settings Specification: 0007 - Very Extended List:
+ This is a fss-0003 Extended List whose Content is then processed as fss-0001 Extended.
-TODO: further document this.
+ TODO: further document this.
-Featureless Settings Specification: 0008 - Embedded List
+# fss-0002
-This is a fss-0003 Extended List whose Content is then recursively processed as fss-0003 Extended List.
+Featureless Settings Specification: 0008 - Embedded List:
+ This is a fss-0003 Extended List whose Content is then recursively processed as fss-0003 Extended List.
-TODO: further document this.
+ TODO: further document this.
-Featureless Settings Specification: 0009 - Reverse Mapping
+# fss-0002
-This is based off of fss-0000 Basic, except the Object is at the end of the line.
+Featureless Settings Specification: 0009 - Reverse Mapping:
+ This is based off of fss-0000 Basic, except the Object is at the end of the line.
-TODO: further document this.
+ TODO: further document this.
-Featureless Settings Specification: 000A - Extended Reverse Mapping
+# fss-0002
-This is based off of fss-0001 Extended, except the Object is at the end of the line.
+Featureless Settings Specification: 000A - Extended Reverse Mapping:
+ This is based off of fss-0001 Extended, except the Object is at the end of the line.
-TODO: further document this.
+ TODO: further document this.
-Featureless Settings Specification: 000B - Simple Json
+# fss-0002
-TODO: this will be implemented such that it is as closely FSS compliant form of JSON.
-It is not intended to be identical to JSON nor a JSON replacement.
-It is intended to be a subset of JSON that follows the FSS practices.
-(An FSS format that can be imported as JSON with no functional changes to the data).
-This will likely be a more specific form of fss-0008 Embedded List, except additional tweaks added to accommodate JSON requirements.
+Featureless Settings Specification: 000B - Simple Json:
+ TODO: this will be implemented such that it is as closely FSS compliant form of JSON.
+
+ It is not intended to be identical to JSON nor a JSON replacement.
+ It is intended to be a subset of JSON that follows the FSS practices.
+ (An FSS format that can be imported as JSON with no functional changes to the data).
+ This will likely be a more specific form of fss-0008 Embedded List, except additional tweaks added to accommodate JSON requirements.
-Featureless Settings Specification: 000C - Simple List
+# fss-0002
-This might be similar to fss-0008 - Embedded List, except it is an fss-0003 Extended List with a (non-recursive) fss-0002 Basic List inside the Content.
+Featureless Settings Specification: 000C - Simple List:
+ This might be similar to fss-0008 - Embedded List, except it is an fss-0003 Extended List with a (non-recursive) fss-0002 Basic List inside the Content.
-Featureless Settings Specifications
-
-A Keep It Simple Stupid specifications for configuration/settings files.
-
-This specification defines the following:
-- Will consist of numerous different kinds of specification files, depending on the type of information stored.
-- As with the practice of "#!/bin/bash", the setting files MUST have the following: "# fss-????" format, such as "# fss-0001".
-- With the ? representing the (hexadecimal/base-16) number that represents the particular specification structure.
-- All settings specifications must avoid any form of noise, relative to the data being stored.
-- ie: XML would be considered anti-KISS due to the extreme level of noise generated by the XML language (not easy to read).
-- The settings files are setup so that they produce easy readability on both the console and in a GUI.
-
-The basic FSS specifications consists of two main parts: an "object" and the "content".
-- Object: considered the name or identifier of some particular data.
-- Content: the data associated with a given Object; all Content must have an associated Object.
-
-Objects can include any characters allowed by the specifications.
-Contents should allow any data and the specification has to allow it in some way.
-The specification may chose, however, how a given Content is represented and parse.
-For example, in FSS-0000 (Basic), Content is treated as a single item whereas in FSS-0001 (Extended), Content is broken apart in multiple sub parts.
-
-Unless explicitly defined by the specification, all specifications are newline sensitive ('\n' only).
-Newline characters are only '\n' and are never anything else (\r is not considered newline in any manner).
-Whitespaces characters that are printable, such as tabs and spaces must be considered the same type.
-Non-printing whitespaces characters are ignored or are treated as placeholders for processing.
-In terms of processing, it is recommended that the NULL character is not considered the end of a string, but this is only a suggestion.
-
-Unless explicitly defined, newlines designate the start of a potential new Object or the potential end of some Content.
-
-Unless explicitly defined, whitespace may exist to the left of the start of objects.
-
-Unless explicitly defined, whitespace immediately both before and after an object is not considered part of an object.
-This simplifies identifying the object, use quoted objects to support whitespace before/after an object.
-
-Unless explicitly defined, quotes may only be either a single quote or a double quote and only a backslash may be used as a delimiter.
-
-Unless explicitly defined by the specification, 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 when it otherwise should not.
-For example, FSS-0001 (Extended) needs quotes to group parts that include spaces, if there is no initial quote, then a quote following the data must not be delimited.
-Such as these following two 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.
-
-Unlike this specification, a more traditional delimit process would have the above two lines instead represented as:
- "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.
-
-All specifications are expected to support or be of the character encoding UTF-8; 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.
-
-Unless explicitly defined, comments are designated by the pound symbol '#' but only if only whitespace is to the left of the pound.
-There is no support for inline comments.
-
-Unless explicitly defined, all designation characters must be in ASCII.
-With designation characters being any character code used to designate how to read a file (such as a colon ':' at the end of a basic list).
-This keeps the processing and logic simple, for UTF-8.
-Whitespace used for designation characters must include support UTF-8 whitespace characters, unless explicitly designate not to.
-Control characters used for designation characters must include support UTF-8 control character support, unless explicitly designate not to.
-
-The UTF-8 BOM is not allowed as a "BOM", instead it must always be treated as the character represented by its code (unless explicitly allowed).
-
-The follow specifications are defined in this project.
-Each of these specifications has a common name associated with the specification number.
-- fss-0000: Basic
-- fss-0001: Extended
-- fss-0002: Basic List
-- fss-0003: Extended List
-- fss-0004: Very Basic List
-- fss-0005: Somewhat Basic List
-- fss-0006: Somewhat Extended List
-- fss-0007: Very Extended List
-- fss-0008: Embedded List
-- fss-0009: Reverse Mapping
-- fss-000A: Extended Reverse Mapping
-- fss-000B: Simple Json
-- fss-000C: Simple List
+# fss-0002
+
+Featureless Settings Specifications:
+ A Keep It Simple Stupid specifications for configuration/settings files.
+
+ This specification defines the following\:
+ - Will consist of numerous different kinds of specification files, depending on the type of information stored.
+ - As with the practice of "#!/bin/bash", the setting files MUST have the following: "# fss-????" format, such as "# fss-0001".
+ - With the ? representing the (hexadecimal/base-16) number that represents the particular specification structure.
+ - All settings specifications must avoid any form of noise, relative to the data being stored.
+ - ie: XML would be considered anti-KISS due to the extreme level of noise generated by the XML language (not easy to read).
+ - The settings files are setup so that they produce easy readability on both the console and in a GUI.
+
+ The basic FSS specifications consists of two main parts: an "object" and the "content".
+ - Object: considered the name or identifier of some particular data.
+ - Content: the data associated with a given Object; all Content must have an associated Object.
+
+ Objects can include any characters allowed by the specifications.
+ Contents should allow any data and the specification has to allow it in some way.
+ The specification may chose, however, how a given Content is represented and parse.
+ For example, in FSS-0000 (Basic), Content is treated as a single item whereas in FSS-0001 (Extended), Content is broken apart in multiple sub parts.
+
+ Unless explicitly defined by the specification, all specifications are newline sensitive ('\n' only).
+ Newline characters are only '\n' and are never anything else (\r is not considered newline in any manner).
+ Whitespaces characters that are printable, such as tabs and spaces must be considered the same type.
+ Non-printing whitespaces characters are ignored or are treated as placeholders for processing.
+ In terms of processing, it is recommended that the NULL character is not considered the end of a string, but this is only a suggestion.
+
+ Unless explicitly defined, newlines designate the start of a potential new Object or the potential end of some Content.
+
+ Unless explicitly defined, whitespace may exist to the left of the start of objects.
+
+ Unless explicitly defined, whitespace immediately both before and after an object is not considered part of an object.
+ This simplifies identifying the object, use quoted objects to support whitespace before/after an object.
+
+ Unless explicitly defined, quotes may only be either a single quote or a double quote and only a backslash may be used as a delimiter.
+
+ Unless explicitly defined by the specification, 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 when it otherwise should not.
+ For example, FSS-0001 (Extended) needs quotes to group parts that include spaces, if there is no initial quote, then a quote following the data must not be delimited.
+ Such as these following two 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.
+
+ Unlike this specification, a more traditional delimit process would have the above two lines instead represented as\:
+ "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.
+
+ All specifications are expected to support or be of the character encoding UTF-8; 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.
+
+ Unless explicitly defined, comments are designated by the pound symbol '#' but only if only whitespace is to the left of the pound.
+ There is no support for inline comments.
+
+ Unless explicitly defined, all designation characters must be in ASCII.
+ With designation characters being any character code used to designate how to read a file (such as a colon ':' at the end of a basic list).
+ This keeps the processing and logic simple, for UTF-8.
+ Whitespace used for designation characters must include support UTF-8 whitespace characters, unless explicitly designate not to.
+ Control characters used for designation characters must include support UTF-8 control character support, unless explicitly designate not to.
+
+ The UTF-8 BOM is not allowed as a "BOM", instead it must always be treated as the character represented by its code (unless explicitly allowed).
+
+ The follow specifications are defined in this project.
+ Each of these specifications has a common name associated with the specification number.
+ - fss-0000: Basic
+ - fss-0001: Extended
+ - fss-0002: Basic List
+ - fss-0003: Extended List
+ - fss-0004: Very Basic List
+ - fss-0005: Somewhat Basic List
+ - fss-0006: Somewhat Extended List
+ - fss-0007: Very Extended List
+ - fss-0008: Embedded List
+ - fss-0009: Reverse Mapping
+ - fss-000A: Extended Reverse Mapping
+ - fss-000B: Simple Json
+ - fss-000C: Simple List
projects / fll / commitdiff