From 94e68a8197594a6dcc742fe0e80db4b7f1e6b69c Mon Sep 17 00:00:00 2001 From: Kevin Day Date: Sun, 7 Jun 2020 10:19:36 -0500 Subject: [PATCH] Update: add new documentation, improve existing documentation --- build/documents/readme | 46 +++++++++++++++++++++++++++++++++++++ build/documents/readme.bootstrap | 49 +++++++++++++++++++--------------------- build/documents/readme.build | 28 +++++++++++++++++++++++ 3 files changed, 97 insertions(+), 26 deletions(-) create mode 100644 build/documents/readme create mode 100644 build/documents/readme.build diff --git a/build/documents/readme b/build/documents/readme new file mode 100644 index 0000000..c90f954 --- /dev/null +++ b/build/documents/readme @@ -0,0 +1,46 @@ +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 generate.sh script. +- The Featureless Make, which is a level_3 project provided by FLL. + +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 2a71e69..9ee5199 100644 --- a/build/documents/readme.bootstrap +++ b/build/documents/readme.bootstrap @@ -1,16 +1,33 @@ -This package provides a _very_ primitive build system using a bash script called generate.sh. -(Once the FLL project is fully bootstrap compiled, the Featureless Make project, called fake, can be used to build any part of this project instead of the primitive generate.sh script.) +The Featureless Linux Library provides a special bootstrap script in case the Featureless Make is not currently installed. + +The GNU bash scripts, called generate.sh and install.sh, are provided to perform this bootstrap process. The syntax for generate.sh is: - generate.sh [options] - - where command is one of the following: 'build' or 'clean'. + generate.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, simply copy the files in the build directory to their appropriate destination. + - 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 generate script by appending the "--help" to the script, such as: "./generate.sh --help". + - The monolithic build process is the simplest, which can be generated like the following: "./generate.sh build -m monolithic". + - When during development, consider using a work directory: "./generate.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: ./generate.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/ @@ -18,7 +35,7 @@ Install Example: 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): @@ -42,23 +59,3 @@ build/ │   └── static │   └── status_code └── settings - -The FLL project is broken up into 3 diffeent 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. - -See: data/build/dependencies for specific dependencies of this project. diff --git a/build/documents/readme.build b/build/documents/readme.build new file mode 100644 index 0000000..28c284f --- /dev/null +++ b/build/documents/readme.build @@ -0,0 +1,28 @@ +The Featureless Make, or Fake, is a build system opposing the 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: +- 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 is designed to specifically build the FLL and encourages the use of Fake to build FLL. + +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 supports custom development environments using the "work" directory concept, such as "fake build -w /tmp/work". + +Build Example, using "build": + fake build + +Build Example, using "make": + fake make + +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. -- 1.8.3.1