Some parts of Pyrite have user-configurable options. The user's selections are stored in a set of editable configuration files, which are loaded by Pyrite-based utilities upon startup.
In order to support both system-wide and user-specific configuration, Pyrite looks in three places for option values. First, it loads system-wide defaults from /etc/palm.conf. Then, it loads the user's personal defaults from ~/.palm.conf. Finally, it may load additional options from the data repository, in the palm.conf file under the user's data directory.
Note: The names of the configuration files are specified near the top of Config.py.
Because the last step requires a user name, it is done after a synchronization connection has been initiated, or (in utilities which do not initiate a connection) once a default user name has been selected. Values in files read later override those read earlier, so even system-wide defaults are not enforced rigidly.
Note: While this layout may seem overly complicated, it is intended to provide flexibility in multi-user, multi-handheld installations. Generally, the system-wide configuration file should be used to specify the location of the data repository and port assignments of cradles, leaving everything else to the user- or handheld-specific configurations.
The Pyrite configuration file format is simple, and resembles the 'INI' format used on a popular non-Unix operating system. Each configuration file is divided into sections, and each section can contain any number of key/value pairs. For example:
[defaults] port = /dev/pilot user = Rob Tillotson
Whitespace at the beginning and end of lines, and before and after the equal sign, is ignored. Values must fit on one line; if there is a need for multiline values in the future, the parser will be expanded to suit. In some cases, multiple key/value pairs with the same key are allowed; for instance, you can use three 'port' entries to specify that you have three connected cradles.
Section and option names are case insensitive.
The [defaults] section of a configuration file holds option values which might be common to many Palm Computing platform aware applications. Pyrite recognizes the following options in this section:
Names a port (eg. /dev/ttyS2) to which a synchronization cradle or cable is connected. This option is normally specified in the system-wide configuration file.
The port to use by default, if none is specified at the time a connection is opened. If no default-port is specified, the first listed one will be used. This option is normally specified in the system-wide configuration file, but in some installations it makes more sense to let the user choose his own default port.
The default user name, which is used when there is no Palm Computing platform device connected and no other user name is specified. This option should normally not be specified in the system-wide configuration file. Instead, each user should set a default user name which matches his handheld, so that Pyrite can locate the data associated with that handheld while it is not in the cradle.
The default numeric user ID. The use of this option is currently unsupported.
The location of the data repository. It can be specified in the system-wide configuration file, creating a shared repository. Alternately, it can be specified in the per-user configuration file; this is appropriate if, for instance, users will be keeping their own data in their home directories.
All Pyrite-specific options go in the [Pyrite] section of a configuration file. In general, Pyrite-specific options follow a standard naming scheme: the type of plug-in they refer to, a dot, the name of the plug-in they refer to, a dot, and then the specific option name. For example, Conduit.Backup.incremental is the full name of the "incremental" option of the Backup conduit. Specific options, and the values they may be set to, are documented elsewhere along with the plug-ins they apply to.
One exception to this general rule is the standard option Sync.conduits. This option should be set to a list of conduit names, separated by commas. The synchronization manager will run each named conduit, in the specified order, during a standard sync session.
Tip: The Backup conduit is best placed either at the beginning or end of the list, depending on what you want to happen. For example, if you run Install before Backup, you will always immediately back up all the databases that were just installed. This is safe, but wastes time and battery power when you are installing programs and data you might not want to keep.
Example 3-2. Sample System-Wide Configuration File
[defaults] port = /dev/ttyS1 default-port = /dev/ttyS1 data-directory = /var/local/pilot
Example 3-3. Sample User Configuration File
[defaults] data-directory = /home/rob/Palm My own data directory, rather than the system default. user = Rob Tillotson My default user name. [Pyrite] Sync.conduits = Backup, Install, TimeSync