git.pond.sub.org Git - empserver/blob - doc/econfig

   1 This is a short note on the Empire run-time configuration stuff.  Some
   2 of this is for deities to enable them to configure things, some of it
   3 is for coders to see how this stuff works.
   4
   5 Julian Onions <j.onions@nexor.co.uk>  15/7/95
   6
   7 --
   8 Also, the Empire config files are now self-documenting (to a point.)
   9 Each option/variable now has a comment associated with it to hopefully
  10 make life easier on deities wanting to change things.
  11
  12 -- Steve McClure, 10/21/1998
  13 --
  14
  15 Deity Notes
  16 -----------
  17
  18 To find out the compiled-in configuration, the simplest method is to
  19 compile up util/pconfig and the run it.  It can be run either with no
  20 arguments, in which case it will print in config format the current
  21 compiled-in configuration.  Otherwise, with a file containing a
  22 configuration, it will first read in this file, and override any
  23 compiled in variables, and then print the merged configuration.
  24
  25 So the first method shows you what's compiled in, the second how a
  26 config file would modify this.
  27
  28 Blank lines are ignored, as are lines starting with a # character.
  29
  30 A line of the form KEY VALUE configures an econfig key to a value.  A
  31 value is either a string (quote using " to get spaces in it), an
  32 integer or a floating-point number, depending on the key.
  33
  34 For instance,
  35     data "/empire/data"
  36 configures the data directory to that place, and
  37     port "7777"
  38 configures the empire port to 7777,
  39   btu_build_rate 0.0004
  40 configures the BTU build rate, and so on.
  41
  42 The programs look for a config file in a compiled-in location, which
  43 is shown by emp_server -h.  Use -e to make the programs use another
  44 config file instead.  Thus, to start two games on the same host, you
  45 might have
  46
  47 Game1:
  48 files -e econfig1
  49 fairland -e econfig1
  50 emp_server -e econfig1
  51
  52 Game2:
  53 files -e econfig2
  54 fairland -e econfig2
  55 emp_server -e econfig2
  56
  57 econfig1 might have the lines
  58
  59 data "/empire/data1"
  60 info "/empire/info.nr"
  61 port "7777"
  62
  63 and econfig2 might have the lines
  64
  65 data "/empire/data2"
  66 info "/empire/info.nr"
  67 port "7778"
  68
  69 You only need the lines in that file that you require to override the
  70 compiled in definitions, however having all the definitions may help
  71 you to understand what is on and off.  You could do this with
  72
  73 pconfig econfig1 > e1 && mv e1 econfig1
  74 pconfig econfig2 > e2 && mv e2 econfig2
  75
  76 which will fill in all the missing keys and values with their defaults.
  77
  78
  79
  80 Coder information
  81 -----------------
  82
  83 The simplest way to describe this is perhaps to step through how a new
  84 key would be added.  Let's do this for a new option "DUMB".
  85
  86 1. Define the variable for the key.  Options go into
  87 src/lib/global/options.c, like this:
  88
  89 int opt_DUMB = 1;
  90
  91 The initializer provides the compiled-in value.
  92
  93 Other keys go into src/lib/global/constants.c.
  94
  95 2. Declare the econfig key in include/econfig-spec.h:
  96
  97 EMPCF_OPT("DUMP", opt_DUMP, "Enable additional dumbness")
  98
  99 For a non-option key, you'd use EMPCFBOTH() there.
 100
 101 The declaration is visible both in include/optlist.h as an external
 102 variable, and in struct keymatch configkeys[], which is used by the
 103 econfig parser.
 104
 105 3. Use the variable in your code.  This normally looks like
 106
 107           if (opt_DUMB) {
 108              pr("You're being dumb\n");
 109           } else {
 110              pr ("You're being really dumb\n");
 111           }