Copyright © 2007 Alexander Lang
This work is licensed under the Creative Commons Attribution-NonCommercial-ShareAlike License. To view a copy of this license, visit http://creativecommons.org/licenses/by-nc-sa/2.0/ or send a letter to Creative Commons, 559 Nathan Abbott Way, Stanford, California 94305, USA.
Table of Contents
This document contains a description of the “SystemBook” software. This document will contain the functional requirements of the project and how the developers will achieve all the objectives. The SRS will serve as a guide for the users and the developers. Section 2 is concentrated more on the user perspective and Section 3 is directed more for the developers.
As the name “SystemBook” is trying to suggest, SystemBook is a software that helps you manage your source-based UNIX/Linux system, presenting its user an interactive book. The books content describes and explains how software is installed/updated/removed. Think of the content as a LFS-Book that the user can read and modify and the SystemBook software can execute. So the project is actualy split in two parts: the SystemBook software on one side and the SystemBook content on the other. (Actualy this separation is the same as in gentoos portage: the portage software and the portage tree)
Linux From Scratch
gentoos package management system
shell scripts containig package informations and instructions, used by portage
The LFS-Style book, consisting of a collection of pages containing all the information needed to manage a system
Section 2.0, the general description, gives an “executive overview” and is very user-oriented. It expounds on the functional and data requirements of the application. It also lists the limitations, assumptions and dependencies of the application. Section 3.0, the specific requirements section, includes the developers technical view of the users's expectation of the application. It also touches on the performance and quality requirements of the application and provides a solid definition of the interface.
SystemBook is primarily intended for experienced LFS-users and LFS-developers. It may also attract power-users of other source-based distributions such as gentoo.
The SystemBook content is a collection of “pages” containing all the information needed by the SystemBook software. Imagine pages as LFS-pages with the abilities of ebuild scripts.
The SystemBook content is a book. A book consists of pages. As the SystemBook content is a “software book” it's only a collection of pages, no cover (nothing else) is needed.
Every page has a number of properties. The values of these properties make every page unique and identifable. The properties common to all types of pages are:
The name is the primary identification property of a page. “name” is a free form string
The version is an additional identification prperty of a page. “version” is a free form string. (So if you think your page does not need a version, you can leaf it blank)
The “revision” is the final identification prprety of a page. It is an integer value that defaults to zero, and increases if the page changes, but name and version stay the same. It is mainly used if you fix errors in pages. New pages always have a revision value of zero.
The “author” is the person (or program) who wrote the page. As readers of the page we would like to know his name and possibly how to contact him. “author” is a document of defined structure that can be validated.
The author has to define the terms for legal use of his page. “license” is a simple string, its possible values are restricted to a number of known licenses.
Since pages can be modified, we want to keep track of what changed. “ChangeLog” is a document of defined structure and can be validated.
This is sort of a summary of what the page is about. “description” is a document of defined structure and can be validated.
Chapters are a special type of pages. They inherit all the properties of normal pages. Additionaly Chapters contain references to pages that are “part” of this chapter. As chapters are only special pages, they can of corse reference other chapters, making it possible to create a tree of chapters. Besides the refereces to its members each chapter has a “priority” property. The priority serves to determin the order in witch chapters are searched for pages.
Tasks are a special type of pages. They inherit all the properties of normal pages. Think of tasks as the ebuild-skripts of SystemBook. To accomplish this tasks need some more properties:
Indicates how likely something goes wrong when executing the task. “stability” is a string, its possible values are restricted.
indicates if this task replaces other tasks with the same name, installed on the system, or if it coexists with them. As an exemple, you may want to have multiple versions of the gnu autotools installed, so the tasks responsible for installing this packages would have this property set to “yes”. “coexists” is a string, its possible values are yes and no.
Normaly, what a task provides coresponds to its identification (name, version, revision), but sometimes (most likely when more then one task is doing similar things) you may want to identify the tasks accomplishment with a value other then its name-version-revision. This is usefull, if a package depends on something that can be provided by several other packages. Take a dependency on X11 for example: X11 can be provided by xorg or by XFree86, so both their tasks would set “provides” to X11. “provides” is a free formed string.
A task can be configured through the use of variables. “configuration” is a table that stores the names, values and type of these variables. “configuration” is a document of defined structure and can be validated.
Every task has a list of instructions. An “instruction” is a document of defined structure and can be validated. Every “instruction” consists of the following elements:
Each instruction has a “role” and each role has a status. The execution of an instruction changes the role's status. Possible values for role are:
if the instruction is for downloading something
if the instruction configures something
if the instruction builds something
if the instruction installes something
if the instruction uninstalles something
if the instruction changes the shell-environment. The status of such instructions is resetted after each session.
The status can assume the following values:
The sucessfull execution of an instruction may depend on the status of other instructions. This other instructions may be part of the same task, or part of other tasks. Every “dependency” holds a reference to an instruction and specifies the value the reference target has to have. Wildcats in the reference are allowed, as long as at least one target can be found.
The “shellinput” holds the actual code that is going to be executed. You shuld make use of the configuration variables here. The output that this code produces is logged in the “shelllog”. The shelllog stores the stdout and the stderr. Each shellinput has a shelllog. “shellinput” is a document of defined structure and can be validated.
Each instruction shuld have an educational explanation of what is beeing done. “explanation” is a document of defined structure and can be validated. (xhtml and docbook can be considered as possible syntaxes for this purpose)
The SystemBook software will be able to display pages and execute their instructions. It will be able to edit pages, add new ones, remove old ones, search for pages, merge changes between pages, import pages from different resources with different syntaxes, export them in different syntaxes.
The SystemBook software will have at least one userinterface that can display pages to the user, ideally it will have more than one. The interface will alow the user to navigate through the pages.
When it comes to executing instructions, the SystemBook software will be just like a LFS-user and feed the shellcode to a shell. The SystemBook software will be very diligent and create all the logs automaitcally. How this is done will be explained in pages form a SystemBook chapter, with will be part of the software. The SystemBook software will have at least on userinterface that lets him select and execute instructions.
The SystemBook software will have at least one userinterface that can edit pages. If the user saves the page after changeing it and did not change the pages identification, the revision will be automaticaly increased. The source property will also be automaticaly set to the original page, because after an edit the page is always saved as a new one, keeping the original unchanged.
The SystemBook software will have at least one userinterface that can add pages to the content tree. This interface will also allow the user to create the pages he wants to add.
The SystemBook software will have at least one userinterface that allows the user to select and remove pages from the content tree.
The SystemBook software will have at least one userinterface that allows the user to search for pages in the content tree. Every page property can be a filter for the search.
The SystemBook software will have at least one userinterface that allows the user to merge changes between pages if they have the same source.
Writing pages for a whole distribution can be a lot of work, therefore the SystemBook software will have at least one userinterface that allows the user to import resources that use different syntaxes, and convert them to pages. Such resources can be LFS and BLFS books, or ebuild scripts.
We do not want our users to be selfish, therefore the SystemBook software will have at least one userinterface that allows the user to export pages converting them to resources that use different syntaxes. Idealy the export syntaxes will cover all the import ones.
In parts of the content complex formatted descriptions and explanations would improve readability. As we do not want to reinvent the wheel, DocBook sysntax will be used for this parts of pages.
Distributions can grow verry large, so SystemBook will have to handl trees with large numbers of pages. The most time consuming activity will probably be the execution of the instructions, but SystemBook will have no influence on that. All other activitis SystemBook is capable of should be as fast as possible, therefore at least preformance-critical parts have to be written in a compiled language, prefferibly c++. The content-tree will be stored in a database to improve performance.
SystemBook has to be absolutly stabe, as a crash could leaf the whole system corrupted. It has to do a lot of error checking and output usefull error messages if they happen. SystemBook should be able to check the system integrity and in case this test fails be able to restore a sane state.