This guide provides an overview of the Mandolin Creek System Helper (MCSH) architecture and design, introducing the key concepts, organization, and components. Other documents (linked herein) provide information about the architecture and design of individual subsystems and components.
The MCSH package provides hundreds of interdependent scripts that collectively implement an application frameworks. This frameworks provides the foundation for developing additional scripts, without having to reinvent all of the plumbing required to build a good script.
The MCSH package provides an integrated development environment (IDE) that facilitates rapid prototyping, forking, and more. These features automate the MCSH script development, testing, release, and deployment processes.
The MCSH IDE can be used to create all new projects, tools, and libraries using simple wizards.
The MCSH scripts are implemented in the GNU Bource Again SHell (GNU bash, or bash). This obvious but easily-overlooked implementation detail defined most of our design decisions, which in turn led to the evolution of the current architecture.
And yet, the system has already begun to evolve in a direction that effectively makes its scripts a superset of Bash, adopting strict (i.e. machine parsable) standards for coding and documentation styles.
As such, several terms in this document need to be defined clearly at its very outset, to disambiguate their meanings from any that shell programmers might already take for granted.
A MCSH script is a single file on disk. Each script implements an application or a reusable library. The terms application script and library script disambiguate these terms from a C, Python, or other kind of library, so the documention refers to them as such when needed.
Functionally, the MCSH libraries are organized in a layered fashion. Each library script should be clearly identifiable as fitting into one of the following categories:
Abstract libraries encapsulate abstract functionality, allowing managing systems or services without knowing about the implementation details.
Trivial abstract libraries may be referred to as interface libraries, since a simple would implementation only serves to provide an abstract interface to the scripts that implement that interface.
Top-level abstract libraries may implement the interface to an extension group, in which case they may be referred to as extension libraries.
Examples: mcui
Backend libraries implement alternative technologies for an abstract library.
These scripts usually exist within the namespace of the abstract interface library that they implement.
Examples: mcui/cli mcui/dialog mcui/kdialog
Technology libraries integrate individual tools to provide a particular functional technology, utilizing other libraries as needed.
These scripts have their own unique tech namespaces.
Examples: net/tech/apache net/tech/nginx
Tool libraries wrap complex external programs. These script wrappers provide several improvements over the bare tools:
Examples: net/tool/apache and dev/tool/make.
Important
Tool library scripts should be placed in a <group>/tool module.
The MCSH package provides several different classes of application scripts: tools, helpers, and programs.
The documentation needs work to be consistent in its usage of these terms, so this terminology may evolve in the future.
Regardless of what they are called, these conceptual distinctions serve to clarify the architecture of the system by grouping additional design and implementation policies.
Tools scripts assist with flag day transformations in the code base and other ephemeral events. They have intentionally limited scope and lifespan, and they are not included in the package release distribution.
Tools scripts are located in the top-level tools/ directory.
Helpers scripts expose functionality in low-level tool or technology libraries. There are a lot of these, and they are quite useful for developers, system administrators, and power-users. However, these scripts tend to be too low-level for most end users.
Program scripts provide a user-level application experience. They implement complex workflows that leverage multiple script groups and domains.
The MCSH script architecture strives for a high degree of modularity. Toward this end, the MCSH project has adopted these architectural policies for modularity:
This section describes the modular architecture in MCSH that ensures we move toward these lofty goals.
MCSH scripts are categorized into a handful of script groups. A script group itself is divided into three parts: a library group (in libs/<name>/), an (optional) tool group (in src/<name>/), documentation (in docs/<name>/).
The MCSH package provides the following built-in script groups:
We have developed and scheduled many exciting additional groups on our roadmap for future major feature releases. Several more groups are scheduled to appear before MCSH reaches v1.0
Inside each script group, script modules provide additional logical collections of scripts. Like script groups, script modules may be comprised of both a library module and a tool module.
For example, the dev group contains several important script modules:
The dependency graph for the dev script tool group
Script modules may offer their own high-level command interfaces that integrate and expose all of the individual library components. These libraries can be referred to as wizard scripts for all the magic that they perform.
MCSH includes a powerful package extension mechanism, documented in the MCSH Package Extension Developer's Guide. This mechanism allows developers to extend the package in radical new directions.
For example, the project roadmap includes plans for distributing custom MCSH Python Scripts. The foundation for that will be a python extension that knows how to build and install those components. Similar extensions could be implemented to integrate support for distributing tools written in other languages, such as C, Perl, or any other langue du jour.
The MCSH package can be said to be entirely self-documenting: