From d2f39336ffd233f8d3af46515db4eadbe2d30017 Mon Sep 17 00:00:00 2001 From: Kevin Day Date: Mon, 12 Dec 2022 22:11:45 -0600 Subject: [PATCH] Update: Build and other documentation, fixing or adding IKI support. --- build/documents/readme.bootstrap.txt | 69 +++++++++++++++++-------------- build/documents/readme.build.txt | 57 +++++++++++++++----------- build/documents/readme.txt | 79 ++++++++++++++++++++---------------- documents/disabling_functions.txt | 2 +- 4 files changed, 117 insertions(+), 90 deletions(-) diff --git a/build/documents/readme.bootstrap.txt b/build/documents/readme.bootstrap.txt index 21f632c..be62771 100644 --- a/build/documents/readme.bootstrap.txt +++ b/build/documents/readme.bootstrap.txt @@ -1,45 +1,54 @@ -# fss-0002 +# fss-0002 iki-0000 +# +# license: cc-by-sa-4.0 +# +# This file (assumed to be named readme.bootstrap.txt) can be more easily read using the following iki_read commands: +# iki_read readme.bootstrap.txt +Q -w -rr abbreviation-FLL FLL abbreviation-FSS FSS -WW character "'" "'" code '"' '"' +# +# To read the "Bootstrap Readme Documentation" section of this file, use this command sequence: +# fss_basic_list_read readme.bootstrap.txt +Q -cn "Bootstrap Readme Documentation" | iki_read +Q -w -rr abbreviation-FLL FLL abbreviation-FSS FSS -WW character "'" "'" code '"' '"' +# Bootstrap Readme Documentation: - The Featureless Linux Library provides a special bootstrap script in case the Featureless Make is not currently installed. + The abbreviation-FLL:"Featureless Linux Library" provides a special bootstrap script in case the bold:"Featureless Make" is not currently installed. - The GNU bash scripts, called bootstrap.sh and install.sh, are provided to perform this bootstrap process. + The bold:"GNU Bash" scripts, called file:"bootstrap.sh" and file:"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 file:"bootstrap.sh" is\: + code:"bootstrap.sh [options]" + - where operation is one of the following: code:"build" or code:"clean". + - No code:"install" command is provided, all of the files to install may be found in the file:"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 file:"install.sh" bold:"GNU Bash" script. + - For all operations and options, get help from the bootstrap script by appending the code:"--help" to the script, such as: code:"./bootstrap.sh --help". + - The monolithic build process is the simplest, which can be generated like the following: code:"./bootstrap.sh build -m monolithic". + - When during development, consider using a work directory, such as: code:"./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". + The syntax for file:"install.sh" is\: + code:"install.sh [options]" + - This defaults to code:"/usr/local/" paths commonly found in bold:"GNU Linux" systems. + - Accepts options for specifying specific install directory paths, such as a custom bin directory: code:"./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. + - When during development, consider using a work directory, such as: code:"./install.sh --work /tmp/work". + - The code:"--work" parameter in file:"install.sh" is similar to the code:"--prefix" parameter, except that it is used for easier development scripting and also for communicating intent and has a different directory structure. + - The bold:"Featureless Make" is a build system only and not an install system, the file:"install.sh" script may still be needed to install when using the bold:"Featureless Make". Build Example\: - ./bootstrap.sh build + code:"./bootstrap.sh build" Install Example\: - ./install.sh + code:"./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/ + code:"cp -vR build/includes/* /usr/include/" + code:"cp -vR build/libaries/shared/* /usr/lib/" + code:"cp -vR build/programs/shared/* /usr/bin/" + code:"cp -vR build/settings/* /etc/" 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.7.0 project)\: - build/ + Build Tree Structure Example (using the abbreviation-FLL:"Featureless Linux Library" code:"status_code-0.7.0" project)\: + block:"build/ ├── documents ├── includes │   └── program @@ -99,10 +108,10 @@ Bootstrap Readme Documentation: ├── sources_script-settings.main.built ├── sources_settings-settings.built ├── sources_settings-settings.fss.built - └── sources_settings-settings.main.built + └── sources_settings-settings.main.built" - Work Tree Structure Example at /tmp/work (using the status_code-0.7.0 project)\: - /tmp/work/ + Work Tree Sructure Example at file:"/tmp/work" (using the abbreviation-FLL:"Featureless Linux Library" code:"status_code-0.7.0" project)\: + block:"/tmp/work/ ├── includes │   └── program │   └── status_code @@ -121,4 +130,4 @@ Bootstrap Readme Documentation: │   ├── libstatus_code.so.0.7 -> libstatus_code.so.0.7.0 │   └── libstatus_code.so.0.7.0 └── static - └── libstatus_code.a + └── libstatus_code.a" diff --git a/build/documents/readme.build.txt b/build/documents/readme.build.txt index 4aa409c..3fa85e1 100644 --- a/build/documents/readme.build.txt +++ b/build/documents/readme.build.txt @@ -1,37 +1,46 @@ -# fss-0002 +# fss-0002 iki-0000 +# +# license: cc-by-sa-4.0 +# +# This file (assumed to be named readme.build.txt) can be more easily read using the following iki_read commands: +# iki_read readme.build.txt +Q -w -rr abbreviation-FLL FLL abbreviation-FSS FSS -WW character "'" "'" code '"' '"' +# +# To read the "Build Readme Documentation" section of this file, use this command sequence: +# fss_basic_list_read readme.build.txt +Q -cn "Build Readme Documentation" | iki_read +Q -w -rr abbreviation-FLL FLL abbreviation-FSS FSS -WW character "'" "'" code '"' '"' +# Build Readme Documentation: - The Featureless Make, or Fake, is a build system opposing the GNU Make build (and install) system. + The bold:"Featureless Make", or code:"fake", is a build system opposing the bold:"GNU Make" build (and install) system. - 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\: + The bold:"GNU Make" system is powerful, but introduces too much unecessary functionality. + In opposition to parts of how bold:"GNU Make" works but also in honor of the success of the bold:"GNU Make" system, the bold:"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 a simple configuration design by using the bold:"Featureless Settings Specification". - 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. + - There should never need to be a code:"configure" script, like bold:"GNU Autoconf". - The Fake is designed to specifically build the FLL and encourages the use of Fake to build FLL. + The code:"fake" is designed to specifically build the abbreviation-FLL:"Featureless Linux Library" and encourages the use of code:"fake" to build abbreviation-FLL:"Featureless Linux Library". - The 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 code:"fake" provides two main build operations\: + - code:"build": a lean purely abbreviation-FSS:"Featureless Settings Specification" based build process, designed around specific but simple project designs (explicitly used by abbreviation-FLL:"Featureless Linux Library"). + - code:"make": a more powerful build process design to be more akin to bold:"GNU Make". - 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. + The code:"fake" supports custom development environments using the file:"work" directory concept, such as code:"fake build -w /tmp/work". + The file:"work" directory structure is identical to the build directory structure. - Build Example, using "build"\: - fake build + Build Example, Using code:"build"\: + code:"fake build" - Build Example, using "make"\: - fake + Build Example, Using code:"make"\: + code:"fake" - Build Example, explicitly using "make"\: - fake make + Build Example, Explicitly Using code:"make"\: + code:"fake make" - Build Tree Structure Example (using the FLL status_code-0.7.0 project)\: - build/ + Build Tree Structure Example (using the abbreviation-FLL:"Featureless Linux Library" code:"status_code-0.7.0" project)\: + block:"build/ ├── documents ├── includes │   └── program @@ -91,8 +100,8 @@ Build Readme Documentation: ├── sources_script-settings.main.built ├── sources_settings-settings.built ├── sources_settings-settings.fss.built - └── sources_settings-settings.main.built + └── sources_settings-settings.main.built" - 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.txt for notes on installing. + See: abbreviation-FLL:"Featureless Linux Library" code:"fake" project documents for further details on how to use the bold:"Featureless Make" system. + See: abbreviation-FLL:"Featureless Linux Library" code:"fake" project specifications for how to configure the build abbreviation-FSS:"Featureless Settings Specification" files and make abbreviation-FSS:"Featureless Settings Specification" files. + See: file:"readme.bootstrap.txt" for notes on installing. diff --git a/build/documents/readme.txt b/build/documents/readme.txt index 7670e58..1a7b7c0 100644 --- a/build/documents/readme.txt +++ b/build/documents/readme.txt @@ -1,53 +1,62 @@ -# fss-0002 +# fss-0002 iki-0000 +# +# license: cc-by-sa-4.0 +# +# This file (assumed to be named readme.build.txt) can be more easily read using the following iki_read commands: +# iki_read readme.txt +Q -w -rrrr abbreviation-API API abbreviation-FLL FLL abbreviation-FSS FSS abbreviation-KISS KISS -WW character "'" "'" code '"' '"' +# +# To read the "Readme Documentation" section of this file, use this command sequence: +# fss_basic_list_read readme.txt +Q -cn "Readme Documentation" | iki_read +Q -w -rrrr abbreviation-API API abbreviation-FLL FLL abbreviation-FSS FSS abbreviation-KISS KISS -WW character "'" "'" code '"' '"' +# Readme Documentation: - The Featureless Linux Library, or FLL, is a set of projects designed to be used for Linux programming. + The abbreviation-FLL:"Featureless Linux Library" is a set of projects designed to be used for bold:"Linux" programming. - The FLL is design around the following concepts\: - - API designed around communicating to the programmer and maintaining unchanging consistency. + The abbreviation-FLL:"Featureless Linux Library" is design around the following concepts\: + - abbreviation-API:"Application Programming Interface" designed around communicating to the programmer and maintaining unchanging consistency. - 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. + - Add freedom back to computing, via the bold:"LGPL" license, because a library is a library. - A standard is not a true standard if it is not freely available and cannot be freely used or followed. - - Avoid the "Feature" trap where projects keep adding things. + - Avoid the bold:"feature" trap where projects keep adding things. - Provide an explicit versioning system that is more than a number, it communicates the status in a very simple manner. - Continue mantaining major versions, a project should be able to last 20, 30, or even 60 years without breaking changes. - - Follow the KISS, Keep It Simple Stupid, principles. + - Follow the abbreviation-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. + The abbreviation-FLL:"Featureless Linux Library" versioning system has three parts: code:"major.minor.micro". + - The bold:"Major" is the primary abbreviation-API:"Application Programming Interface" specification, changes to this number represent massive breaking changes and for all intents and purposes is a different project. + - The bold:"Minor" represents potential breaking changes, where odd numbers represent bold:"development status" and even numbers represent bold:"stable status". + - The bold:"Micro" represents bug fixes and security fixes, these should never introduce neither abbreviation-API:"Application Programming Interface" breaking changes nor new functionality. - 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. + Development releases (as specified by bold:"Minor" version part) may introduce breaking changes and new functionality. + Stable releases (as specified by the bold:"Minor" version part) may not introduce breaking change, unless forced by some security or other difficult situation, and must not add new functionality. - The 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. + The abbreviation-FLL:"Featureless Linux Library" project is broken up into 3 different levels: code:"level_0", code:"level_1", and code:"level_2". + A third pseudo-level also exists for common programs built using this project, called code:"level_3". - With an exception of a few projects within 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. + With an exception of a few projects within code:"level_0", each level should only depend on a project from a lower level. + Therefore, a code:"level_1" project can only depend on code:"level_0" projects and a code:"level_2" project can depend on only code:"level_0" and code:"level_1" projects. + This does not technically apply to the pseudo-level, code:"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_type_array: provides an extension on f_type that requires linking to f_memory 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. + A few projects in code:"level_0" are essentially required by everything and are depended on by virtually all projects, regardless of the level. + These code:"level_0" projects are\: + - code:"f_type": Provides core type definitions, code:"#define", and similar structures for the entire set of abbreviation-FLL:"Featureless Linux Library" projects. + - code:"f_status": provides status codes and other status codes to be used by the entire set of abbreviation-FLL:"Featureless Linux Library" projects. + - code:"f_memory": provides common memory allocation or deallocation to be used by the entire set of abbreviation-FLL:"Featureless Linux Library" projects. + - code:"f_type_array": provides an extension on code:"f_type" that requires linking to code:"f_memory" to be used by the entire set of abbreviation-FLL:"Featureless Linux Library" projects. + - code:"f_string": provides common string management to be used by the entire set of the abbreviation-FLL:"Featureless Linux Library" projects. + - code:"f_utf": provides common UTF-8 related string management to be used by the entire set of the abbreviation-FLL:"Featureless Linux Library" projects. - The above projects should be installed first, and in the provided order (f_type, then f_status, then f_memory, then f_type_array, then f_string, and finally f_utf). - No other level_0 project should depend on another and can be installed in any order. + The above projects should be installed first, and in the provided order (code:"f_type", then code:"f_status", then code:"f_memory", then code:"f_type_array", then code:"f_string", and finally code:"f_utf"). + No other code:"level_0" project should depend on another and can be installed in any order. To facilitate building of this project, two different build systems are provided\: - - The bootstrap, via the bootstrap.sh script. - - The Featureless Make, which is a level_3 project provided by FLL. + - The bootstrap, via the file:"bootstrap.sh" script. + - The bold:"Featureless Make", which is a level_3 project provided by abbreviation-FLL:"Featureless Linux Library". - 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.7.0"). + An example bootstrap script is provided (file:"build/scripts/bootstrap-example.sh") is provided for to show how to build the abbreviation-FLL:"Featureless Linux Library" directly from source. + Use it as an example or explicitly call it (such as: code:"bash build/scripts/bootstrap-example.sh monolithic 0.7.0"). - See: dependencies for specific dependencies of this project. - See: readme.bootstrap.txt for bootstrap compiling (or just regular compiling) any part of the FLL and notes on installing. - See: readme.build.txt for Featureless Make compiling and notes on installing. + See: file:"dependencies" for specific dependencies of this project. + See: file:"readme.bootstrap.txt" for bootstrap compiling (or just regular compiling) any part of the abbreviation-FLL:"Featureless Linux Library" and notes on installing. + See: file:"readme.build.txt" for bold:"Featureless Make" compiling and notes on installing. diff --git a/documents/disabling_functions.txt b/documents/disabling_functions.txt index 7b902e3..4d07d01 100644 --- a/documents/disabling_functions.txt +++ b/documents/disabling_functions.txt @@ -32,7 +32,7 @@ Disabling Functions: All other functions in the abbreviation:"FLL" can be removed. The compiled binaries should be analyzed and the dependencies can be extracted. - Something like the following needs to be done to get the list of functions from the strong:"fake" program\: + Something like the following needs to be done to get the list of functions from the bold:"fake" program\: script:" rm -f unsorted.txt ; nm -Dgu -f p libfake.so | grep -oP '^(f|fl|fll)_[^\s]+' | sed -e '/_s$/d' -e '/_c$/d' >> unsorted.txt sort unsorted.txt | uniq > sorted.txt -- 1.8.3.1