This guide provides an overview of the Mandolin Creek System Helper (MCSH) Package Extension mechanisms. Developers should read this document in order to create a new MCSH extension.
An MCSH package extension (or simply extension) implements an area of functionality that requires additional build, distribution, and release management processes. Extensions may also implement components that require optional or excessive resources to procduce.
The package documentation was the first extension package, as those distribution files take orders of magnitude longer to build than the core source code package. Build times demanded a solution.
The project roadmap already included plans for distributing custom MCSH Python Scripts. The foundation for that will be a Python extension (python) 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.
Similarly, some extensions need to revisit all of the source code to process it again. The package documentation (docs) extension requirements proved this point, but another extant example would be the planned internationalization (i18n) extension
The extension mechanisms that have been developed meet the above design goals:
By definition, extensions are split out from the main build processes, allowing their build processes to be triggered independently. This means that an extension must provide its own Makefile that can be included by the top-level Makefile.
Each extension is defined by its extension makefile. This makefile fragment must exist inside a top-level subdirectory of the package. The directory name defines the extension name; the docs/ directory contains docs/Makefile.
An extension makefile fragment must
See the following files:
An MCSH extension may include a mechanism for installing its output into the target system.
If an extension provides an installation mechanism, it must also provide a mechanism that allows the complete (safe) removal of the installed files. In addition, a version of this mechanism should be installed in the system, allow complete removal without retaining the source package.
Important
Configuration or data files that may be modified by the user should not be removed unless they can be verified as being unmodified from their installation state.
If an extension contains such files, the uninstall mechanism must display a warning if it leaves any such artifacts behind in the target filesystem.
An MCSH extension may include a mechanism for distributing its output along with other project deliverables.
If an extension provides a distribution mechanism, it must provide a mechanism for cleaning up any files generated in the build tree that were generated during the packaging process.
An MCSH extension may include a mechanism for publishing its output in a high-level manner. For example, the docs module may be configured to publish its output to a remote server, allowing it to be published on a web server using a single command.
If an extension provides a publishing mechanism, it must provide a mechanism for cleaning up any files generated in the build tree that were generated during the publishing process.