From fee185d1789485b79a797a261cbfc6b80e2fac57 Mon Sep 17 00:00:00 2001 From: Kevin Day Date: Sun, 7 Jun 2020 21:16:51 -0500 Subject: [PATCH] Update: documentation, also use fss-0002 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. --- build/documents/readme | 101 +++---- build/documents/readme.bootstrap | 157 ++++++----- build/documents/readme.build | 99 +++++-- documents/readme.txt | 2 +- level_3/fake/documents/settings.txt | 393 ++++++++++++++------------- level_3/fake/specifications/defines.txt | 21 +- level_3/fake/specifications/dependencies.txt | 15 +- level_3/fake/specifications/settings.txt | 129 ++++----- specifications/fss-0000.txt | 59 ++-- specifications/fss-0001.txt | 63 ++--- specifications/fss-0002.txt | 93 ++++--- specifications/fss-0003.txt | 101 +++---- specifications/fss-0004.txt | 7 +- specifications/fss-0005.txt | 7 +- specifications/fss-0006.txt | 7 +- specifications/fss-0007.txt | 7 +- specifications/fss-0008.txt | 7 +- specifications/fss-0009.txt | 7 +- specifications/fss-000A.txt | 7 +- specifications/fss-000B.txt | 14 +- specifications/fss-000C.txt | 5 +- specifications/fss.txt | 153 +++++------ 22 files changed, 789 insertions(+), 665 deletions(-) diff --git a/build/documents/readme b/build/documents/readme index b97c580..d15b87a 100644 --- a/build/documents/readme +++ b/build/documents/readme @@ -1,49 +1,52 @@ -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. diff --git a/build/documents/readme.bootstrap b/build/documents/readme.bootstrap index f9de7c2..926aae0 100644 --- a/build/documents/readme.bootstrap +++ b/build/documents/readme.bootstrap @@ -1,61 +1,96 @@ -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 [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 [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 diff --git a/build/documents/readme.build b/build/documents/readme.build index 28c284f..b3754a6 100644 --- a/build/documents/readme.build +++ b/build/documents/readme.build @@ -1,28 +1,85 @@ -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. diff --git a/documents/readme.txt b/documents/readme.txt index 865b395..eee9988 100644 --- a/documents/readme.txt +++ b/documents/readme.txt @@ -1,4 +1,4 @@ -# fss-003 +# fss-002 # # This readme file is inteded to provide a basic introduction to the Featureless Linux Library (FLL). # diff --git a/level_3/fake/documents/settings.txt b/level_3/fake/documents/settings.txt index c9f7720..eee74d8 100644 --- a/level_3/fake/documents/settings.txt +++ b/level_3/fake/documents/settings.txt @@ -1,195 +1,198 @@ -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. diff --git a/level_3/fake/specifications/defines.txt b/level_3/fake/specifications/defines.txt index 8490789..9ae91ab 100644 --- a/level_3/fake/specifications/defines.txt +++ b/level_3/fake/specifications/defines.txt @@ -1,12 +1,15 @@ -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_". diff --git a/level_3/fake/specifications/dependencies.txt b/level_3/fake/specifications/dependencies.txt index ab40f8c..fe925be 100644 --- a/level_3/fake/specifications/dependencies.txt +++ b/level_3/fake/specifications/dependencies.txt @@ -1,8 +1,11 @@ -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. diff --git a/level_3/fake/specifications/settings.txt b/level_3/fake/specifications/settings.txt index 638fef6..092558e 100644 --- a/level_3/fake/specifications/settings.txt +++ b/level_3/fake/specifications/settings.txt @@ -1,67 +1,70 @@ -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" diff --git a/specifications/fss-0000.txt b/specifications/fss-0000.txt index 9a8d126..ae4adf1 100644 --- a/specifications/fss-0000.txt +++ b/specifications/fss-0000.txt @@ -1,36 +1,37 @@ -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. diff --git a/specifications/fss-0001.txt b/specifications/fss-0001.txt index 5218ae8..c81e048 100644 --- a/specifications/fss-0001.txt +++ b/specifications/fss-0001.txt @@ -1,38 +1,39 @@ -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. diff --git a/specifications/fss-0002.txt b/specifications/fss-0002.txt index b56a84a..d986185 100644 --- a/specifications/fss-0002.txt +++ b/specifications/fss-0002.txt @@ -1,45 +1,48 @@ -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. diff --git a/specifications/fss-0003.txt b/specifications/fss-0003.txt index 851f062..ff6655b 100644 --- a/specifications/fss-0003.txt +++ b/specifications/fss-0003.txt @@ -1,50 +1,51 @@ -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. diff --git a/specifications/fss-0004.txt b/specifications/fss-0004.txt index 46ccceb..fc2be27 100644 --- a/specifications/fss-0004.txt +++ b/specifications/fss-0004.txt @@ -1,5 +1,6 @@ -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. diff --git a/specifications/fss-0005.txt b/specifications/fss-0005.txt index 9b1f73e..e77e1b7 100644 --- a/specifications/fss-0005.txt +++ b/specifications/fss-0005.txt @@ -1,5 +1,6 @@ -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. diff --git a/specifications/fss-0006.txt b/specifications/fss-0006.txt index cdd4644..83cc815 100644 --- a/specifications/fss-0006.txt +++ b/specifications/fss-0006.txt @@ -1,5 +1,6 @@ -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. diff --git a/specifications/fss-0007.txt b/specifications/fss-0007.txt index 8ede652..cc46bcc 100644 --- a/specifications/fss-0007.txt +++ b/specifications/fss-0007.txt @@ -1,5 +1,6 @@ -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. diff --git a/specifications/fss-0008.txt b/specifications/fss-0008.txt index 53449c9..50f944a 100644 --- a/specifications/fss-0008.txt +++ b/specifications/fss-0008.txt @@ -1,5 +1,6 @@ -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. diff --git a/specifications/fss-0009.txt b/specifications/fss-0009.txt index d7deb81..0ea0e42 100644 --- a/specifications/fss-0009.txt +++ b/specifications/fss-0009.txt @@ -1,5 +1,6 @@ -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. diff --git a/specifications/fss-000A.txt b/specifications/fss-000A.txt index a6eeeb0..35847f7 100644 --- a/specifications/fss-000A.txt +++ b/specifications/fss-000A.txt @@ -1,5 +1,6 @@ -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. diff --git a/specifications/fss-000B.txt b/specifications/fss-000B.txt index 4cf31e3..3f02c43 100644 --- a/specifications/fss-000B.txt +++ b/specifications/fss-000B.txt @@ -1,7 +1,9 @@ -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. diff --git a/specifications/fss-000C.txt b/specifications/fss-000C.txt index 728ccf9..aca97cb 100644 --- a/specifications/fss-000C.txt +++ b/specifications/fss-000C.txt @@ -1,3 +1,4 @@ -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. diff --git a/specifications/fss.txt b/specifications/fss.txt index d359284..7ac5875 100644 --- a/specifications/fss.txt +++ b/specifications/fss.txt @@ -1,76 +1,77 @@ -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 -- 1.8.3.1