- read in any number of text files and combines these into a single flat resource (extra config files may be specified in a config file)
- reads data organised into un-nested stanzas
- reads tokens of different types: integer, float, string, arrays, booleans...
- optionally several different stanzas of the same name may exist
- writes user config to store session data? (only for Blixem)
- maintains a version history of user data? (not really)
- specifies an internal data format for the data and provides functions to access it (using GLib)
- defines (via data structures) what data and options may be specified by the user.
- provides a default directory and main config file and allows alternate ones to be specified
Some of the comments are clearly out of date and it looks like the functional spec has migrated.
How much config data and code is there?
In a simple installation (development) in the default ZMap file there are 5 types of stanza: [ZMap], [source], [logging], [blixen], [window], (76 lines of data) and in another file there are 136 [style] stanzas (specifying display formats for columns - about 1000 lines of data)
At a rough guess there are currently 3500 lines of code (not including headers) to drive config files and 1000+ lines using it. There are 75 files out of 181 that include the string 'config'.
Is it thread safe?
Arguably there is no need as all the data can be read in on program startup and stored in memory. Threads can be made to regard config as read-only, and the master thread (the view) can handle all user changable data. There may be an argument for threads maintaining thier own config files, but given that the point of having threads is to have more than one there are obvious security issues.
Files
zmapConfig.c "no longer used"
zmapConfigRead.c not used
zmapConfigWrite.c one function, not called
zmapConfigGet.c returns stanzas from stored data, not used
zmapConfigUtils.c not used
zmapConfigDir finds where the config file(s) are
zmapConfigIni.c -- this does a lot of the work -- ** appears to be 2 files pasted together **
zmapConfigLoader.c -- this does a lot of the work -- ** in the zmapUtils directory **
All realistic locations appear to have been catered for:
Hard coded (defaults?)
System
Application Home
User Home
User supplied
There is also a 'default_dir' which is not used.
There are functions that ultimately call zMapMakeUserConfig() (which writes an empty file with a comment header) in zmapView.c, but both of these are iffed out with comments like THIS_NEEDS_REDOING and NOT_NEEDED_ATM. (addAlignments() and getSequenceServers()C).
How it works: (yes really)
-- Reading the Data --
zmapConfigIni.c/zMapConfigIniContextCreate() calls zmapConfigLoader.c/zmapConfigIniContextProvide() and then zmapConfigIniR.c/zMapConfigIniReadAll() which will try to read all the files and then construct a merged (overlayed) version.
'All the files' being system, application and user. A complete set of stanzas is created in memory and overlayed with data from the files, although it is not clear how defaults are handled: these could be set up as static data but are not.
-- Merging Groups and Files --
GKeyFile will combine multiple stanzas with the same name into one; if multiple copies of the same key exist the last one wins.
Multiple files get overlayed by the zmapConfigIni code.
There are five key files recognised:
files[0] = config->buffer_key_file; (not used - from zmapConfigIni days)
files[1] = config->extra_key_file; (not used - from zmapConfigIni days - but see below)
files[2] = config->user_key_file;
files[3] = config->zmap_key_file;
files[4] = config->sys_key_file;
Currently the code is a little confused and 3 then 4 are prioritised, then 0,1,2 in that order, ie a user file setting will not overwrite a system file setting; this appears to be based on the theory that only keys that must not be changed will appear in these files. There is another function that checks for stanza existance which operates in the opposite order. If more than one extra file is read (or the same one mentioned more than once) then there is a memory leak.
Additionally, extra files can be read in by request (eg the styles config, called from zmapServerProtocolHandler.c/getStylesFromFile() via zmapStylesUtils.c/zMapFeatureTypeGetFromFile(), and this is stored in config->extra_key_file
-- Saving Config Data --
Currently used to remember Blixem setup, the entire user file is written using GKeyFile functions. Blixem also appears to have its own config file, and the name of this is defined inthe ZMap config but not read by ZMap.
-- Stanzas: Allowed Names and Keys --
In the ZMap config file there are a few stanzas that are allowed and these are created in zMapConfigIniProvideContext() with the full set of allowed keys. Stanzas that can be duplicated (eg [source] and [style]) must be named uniquely or else will overwrite - these are processed directly by application code.
The Plan
- tighten up the design and document it
define merging rules
define the use of extra files and bring this into the Config module not the application code
change ZMapConfigIniStruct to be a list of key files that can be extended as files get read,
priority being the order of files in the list
take Config file use out of threads - read all data in the main thread (GUI)
implement reading of 'extra' config files in the top level files (system, application, user) in the stanzas that need to use this
add styles-file=XXX into [ZMap] and make it a list like sources and styles. (but keep it as an option in [source])
a default user file to be created by a command line argument option
- unused functions to be deleted from the source
- zmapConfigLoader.c to be moved to zmapConfig from zmapUtils
- zmapServerProtocolHandler.c to call functions that parse stored data rather than reading files
- any other application code handling config directly (eg in zmapView) to be adjusted
- a new set of files created (eg zmapConf*) and the old once replaced to avoid confusion, and to allow old code to be restored from the CVS if necessary. Old (especially unused) files to be deleted from the CVS.
- function names and structures, data to be changed (eg zmMapConf*) to ensure that old code does not escape inspection
- doxygen and other documentation put online
Questions
Why does ZMAP store Blixem config when it has it's own file?
Can Blixem be used without Otterlace (other than for development)?
Is there milage in removing the write config file functions, or creating a seperate file for each writable group of data ? (more secure)
Time and Effort Estimates
- writing the functional spec (merging rules, handling of files, application interface, user guide) 2 hrs
mainly expanding on the above
- writing a technical spec: files and function definitions, data structures, data in and data out 2 hrs
very brief, again expanding on the above
** see zmapConf/README for further details **
---** see zmapConf/README for further details ------------------------------------------------------- OK
- create new directories and files, cut and paste functions from old code to new 4 hrs ?
~2500 lines of code
---Builds + runs ok, some issues on source organisation --------------------------------------------- OK
- implement extra files and merging rules, modify stanza handling to match 2 hrs
--- only 1 buffer config and only 1 extra file config exists, so keep existing hard coded pointers --
---directory structure no cleaner, only zmapConfig/ is used------------------------------------------ OK
- create default file on command line arg 2 hrs (not done)
- renaming types and functions to force editing and clean compile relating to config code 1 day
75 files include the string 'config', 18 include 'configinicontext' (260 instances)
317 instances of 'configini' in 18 files - this is realistic. Most will require no change.
---most functions not changed, external references are now relatively clean-------------------------- OK
- doxygen comments (currently not there at all) 1 day
- OPTIONAL clean compiles of all affected source files where no difficult issues arise 1 day
- operating the CVS
add new files and directories and deleting old ones and comitting the source 1 hr
----------------------------------------------------------------------------------------------------- OK
- running ValGrind over the code and fixing ConfigIni related issues 1 day
NB this is fixing existing bugs, not updating the module
In rough terms 3 days to do the work, 1 to write it up, plus 1 day to fix old bugs w/ ValGrind.
