Table of Contents
As we've created scripts for the NST project, we've come to realize the following:
Its a good idea to keep the source code for your scripts well organized within your directory tree.
By following conventions, much of the tedious overhead related to maintaining scripts can be eliminated.
Creating a script without supporting documentation is pointless if you intend for others to use it.
Making a script that can be installed on a development system (a system used to build the NST from source) as well as on the final NST is a good idea (general purpose scripts can be quite useful).
Using consistent command line options across scripts is a good idea.
There is a lot of replicated functionality across scripts. Building a collection of script functions that can be included promotes re-use and consistency.
In order to accomplish these goals, the following guidelines must by followed by NST developers:
src/scripts/NAME DirectoryEach script must have its own directory under
src/scripts, and the name of the
directory must match the name of the script. For example,
you will find the source code for the nstnewscript
under the src/scripts/nstnewscript
directory.
src/scripts/NAME/makefileEach script shall have its own
makefile.
Each makefile shall yield both
the final script src/scripts/NAME/NAME
and its HTML documentation
(NAME.man.html).
src/scripts/NAME/NAME.docbookEach script should have a source
DocBook file documenting the
script. This is typically used to produce the
src/scripts/NAME/NAME.man.html
documentation file. If this convention is followed, a link
to the script will automatically appear in this document,
AND the documentation for the script will automatically
appear online at the NST web site. Using
DocBook enables us to produce
HTML documentation now, and gives us
the potential to generate PDF and man
page output later in the future.
If the script can be installed and used on the development system (outside of a NST distribution), it should exit successfully (without actually doing anything) when make installable is run. If the script is installable, the following rules should also be supported:
This should echo the names of the files that will be installed, but should not actually install them.
This should build and install the scripts into the locations shown by make install-list.
This should remove the files listed by make install-list.
src/packages/system/nstscripts.shIf you have a standard simple script (which doesn't require any extra files in order to be used), you can easily add it to the NST distribution by adding the name of the script to this file.
Following this many conventions may seem a bit overwhelming at first. However, you'll find that your scripting productivity is greatly increased.