<> = Configuration = Configuring Rattail can be quite simple, or rather complex. It all depends on how you want (or need) to go about it. This document attempts to explain the basics. == Default File Locations == The first thing to understand is where the config file(s) should exist. Even this may be overridden in most cases, but we'll start with the default locations - which vary by operating system. {{{#!wiki note Note that unless instructed otherwise, Rattail will always check ''each'' of the possible default file locations. If more than one location contains a config file, then ''all'' such files will be read and will provide configuration values to the running application. }}} === Linux === On Linux systems, the following paths are checked by default: * `/etc/rattail/rattail.conf` * `/etc/rattail.conf` * `/usr/local/etc/rattail/rattail.conf` * `/usr/local/etc/rattail.conf` * `~/.rattail/rattail.conf` * `~/.rattail.conf` Note that `~` (in last two locations above) will be replaced by the home directory of the current user, i.e. the one running the process which invokes Rattail (e.g. `/home/lance`). === Microsoft Windows === On Windows systems, the following paths are checked by default: * `\rattail\rattail.conf` * `\rattail.conf` * `\rattail\rattail.conf` * `\rattail.conf` Note that `` will be replaced by the "shared application data" directory, and `` will be replaced by the "user application data" directory. The actual location of each of these directories is obtained via the Windows API and will therefore vary depending on the version of Windows in use. On Windows 7, these directories are (assuming a username of `lance`): ||``||`C:\ProgramData`|| ||``||`C:\Users\lance\AppData\Roaming`|| On Windows XP, the directories would be: ||``||`C:\Documents and Settings\All Users\Application Data`|| ||``||`C:\Documents and Settings\lance\Application Data`|| == Overriding File Locations == If you do not wish Rattail to look in the default file locations for its configuration, you must explicitly tell it where to look. This is done via a command line argument. For example: {{{ $ rattail --config=/special/stuff.conf some-command }}} == Inheritance / "Chaining" == The final thing to understand about Rattail configuration is that files may "imperatively" include other files. The reason for this is to encourage [[http://en.wikipedia.org/wiki/Don%27t_repeat_yourself|"DRY"]] configuration. {{{#!wiki note The way this works may be a little confusing, and some may even argue that the mental overhead isn't worth the "savings" represented by DRY configuration. Should this be your stance, please rest assured that this method of organizing configuration is entirely optional. }}} === Use Cases === Config inheritance can be useful for things which are truly "global" to an organization. For example, an outgoing mail server may be used by many instances of Rattail applications. If each of these apps has their own config file (as they often will), it might be nice to specify the mail server location only once instead of within each config file. Another example might be logging configuration. Of course an ''output'' log file location should probably be unique to each application; however the details of log handlers, formats, etc., will often be identical and are therefore good candidates for inclusion within a "global" config file. === How to Specify a Chain === Okay, so we're ready to chain some config files. More on the implementation details regarding the order in which chained files are read, etc., is in the next section. For now we'll just point out how to actually "form" the chain. Within an app's primary config file (e.g. `C:\special\stuff.conf`), simply add a config setting similar to the following: {{{ [edbob] include_config = [ r'C:\global\mail.conf', r'C:\global\logging.conf', ] }}} Note that this example assumes Windows and uses a [[http://docs.python.org/reference/lexical_analysis.html#string-literals|raw string literal]]. This is primarily because this can be a gotcha on Windows; Linux users should have little trouble translating the example. Note also that this config setting should be ''valid Python code'' which evaluates to a sequence of strings. The reason for this is to allow file paths which contain spaces. This particular example splits up the setting value so as to span multiple lines within the config file. This is not required, and is done here only for the sake of illustrating how to do so. And finally, note that the config ''section'' is `[edbob]` and ''not'' `[rattail]` (or anything else, for that matter). This is because the details of the configuration implementation are in fact not part of Rattail itself, but rather another project called [[http://pypi.python.org/pypi/edbob|edbob]]. This distinction should not matter much; however it may be another gotcha if you're not paying attention. Just to be complete, here's a simpler example which assumes Linux: {{{ [edbob] include_config = ['/global/everything.conf'] }}} === Reading Order === Chained config files are ''read'' in the order in which they are encountered. This is done recursively. For example, if an app's primary config file (`app.conf`) contains an include directive for `system.conf`, which in turn includes `global.conf`, then: 1. Rattail reads `app.conf`. 1. Rattail reads `system.conf`. 1. Rattail reads `global.conf`. However it is important to note that the ''settings'' contained in `app.conf` will override those in `system.conf`, which in turn will override those found in `global.conf`. Therefore the primary config file (`app.conf` in this example) may "import" configuration values from other files, yet it still may override any settings as needed.