Notes on Command-Line switches

Many scripts accept command-line options. All options feature a short, one-letter form, and a long form. Following the GNU conventions, short form options are preceded by a single hyphen (as in -a, -b) and long form options are preceded by two hyphens (as in --foo, --bar).

Order of Command-Line Arguments

All command-line options have to be passed first, before other types of arguments (file names, package names, etc). In other words,

FooScript -m Foo

works, but

FooScript Foo -m      # WRONG! Switches must come first.

does not.

Switches taking arguments

Some command-line options accept arguments. These arguments must be passed as the word following the argument, both in short and long forms. For example, say that -s and --long are options that take a parameter. This is the correct way to use them:

FooScript -s value --long another

These are not recognized:

FooScript -s=value --long another      # WRONG! Use distinct tokens.

Do not conglomerate

Each option should be passed in a separate token, even when in short mode. If -a, -b and -c are options for an imaginary FooScript, then

FooScript -a -b -c blah.txt

is correct, but

FooScript -abc blah.txt      # WRONG! Options must be separated.

is not.

Help

All scripts have a --help option (or, in short form, -h). When a program that needs arguments is run without arguments, the help text will be displayed. (Note: Actually, not all scripts conform to this yet, but this is being worked on).

GoboPath

This script is used everywhere inside many scripts. It exports shell variables such as $goboExecutables, $goboUsers, $goboKernel, and so on, which contains a string specifying where in the file system these entries are (/System/Index/bin, /Users, /System/Kernel, and so on).

For example, in the Scripts package, within the bin/ subdirectory are files such as ScriptFunctions or SuggestUpdates, among others. These source GoboPath via:

. GoboPath

This is normally within the Scripts package, at bin/GoboPath. The whole GoboLinux hierarchy is kept as referential prefix in that file. The variable $goboPrefix keeps track as to where GoboLinux is mounted at.

Let’s avoid hardcoding things, sourcing this file and using these variables makes the world a better place :-)

Guidlines for script authors

This section documents the coding style used in GoboLinux shell scripts.

It’s important to note that not all scripts follow these guidelines, because of historical baggage (some of the scripts are older than GoboLinux itself). Patches to correct the non-conformities are welcome.

Indentation and block organization

A few rules of thumb:

• Three spaces for indentation. Avoid joining do and then in the same line with ;, instead put it on a line by itself, aligned with for, while or if.
• Prefer using if rather than idioms like && { }, but apply your common sense.
• Be generous in you use of quotes whenever referring or defining variables, and the ${x} syntax when merging variables inside strings.
• Bear in mind that esac is ridiculous.
• When doing weird stuff such as functional-like programming with eval, hide it in a pretty function to pretend it is a bit more readable. Eventually we might make a Functional module. By now, Map() is defined in the Array module.

It’s hard to believe, but the only shell module containing GoboLinux-specific stuff is the one aptly called GoboLinux. Keep that in mind when submitting functions for inclusion in one of the modules.

Names

The idea in the naming convention is to orthogonally describe scope and purpose of each name. We define “local scope” as names that are specific to a given script, and “library scope” as names defined in Scripts modules such as GoboPath, ScriptFunctions or one of the imported function modules.

These are the guidelines:

• Function names have underscores between words

Example: local_function, Library_Function

• Variable names do not, they’re just connected

Example: localvariable, LibraryVariable

• Library names (for functions and variables) have capital letters

Example: Library_Function, LibraryVariable

• Local names (for functions and variables) are in all-lowercase

Example: local_function, localvariable

• All-uppercase variables are reserved for standard Unix usage

Example: PATH, LD_LIBRARY_PATH

• Configuration variables used in .conf files start with the script name in lowercase, resulting in a case style similar to that used in Java variables

Example: compileRecipeDirs, editKeymapLayout