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

   1 This is a short note on the empire configuration stuff. Some of this
   2 is for deities to enable them to configure things, some of it is for
   3 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 current 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 printout in config format the current
  21 compiled in options. Otherwise with a file containing a configuration
  22 it will first read in this file, and override any compiled in
  23 variables and then printout the merged options.
  24
  25 So the first method shows you what's compiled in, the 2nd how a config
  26 file would modify this.
  27
  28 Blank lines are ignored, as are lines starting with a # character.
  29
  30 Most of the options are straight forward, they take either a string
  31 (quote using " to get spaces in it) or a number - integer or floating
  32 point depending on the option.
  33
  34 For instance
  35   privname "The Deity"
  36 sets the internal privname variable to that string, and
  37   port "7777"
  38 sets the empire port to 7777.
  39   btu_build_rate 0.0004
  40 sets the internal floating point number for btu building rate,
  41 and so on.
  42
  43 The only other type of variable currently defined are the
  44 options. These may be specified as one or more lines starting
  45 "option" and turned off with the keyword "nooption".
  46
  47 So, for instance
  48
  49     option FUEL ORBIT
  50 and
  51     option FUEL
  52     option ORBIT
  53
  54 are equivalent
  55
  56 To turn off an option that is compiled in, you can similarly have
  57
  58     nooption FUEL
  59     nooption ORBIT
  60 or
  61     nooption FUEL ORBIT
  62
  63
  64 As a check, pconfig will printout some of the internal file names as
  65 comments at the end just to check they are in the right place.
  66
  67 The server can take a -e config file as a command line option so that
  68 it will read a specific config file. If not, it will default to
  69 looking for a file econfig in the built in data directory, but it
  70 won't mind if one is absent. Similarly, util/files and util/fairland
  71 et al all take a -e config file to run from a different config.
  72 Thus, to start two games on the same host, you might have
  73
  74 Game1:
  75 files -e econfig1
  76 fairland -e econfig1
  77 emp_server -e econfig1
  78
  79 Game2:
  80 files -e econfig2
  81 fairland -e econfig2
  82 emp_server -e econfig2
  83
  84 econfig1 might have the lines
  85
  86 data "/empire/data1"
  87 info "/empire/info.nr"
  88 port "7777"
  89
  90 and econfig2 might have the lines
  91
  92 data "/empire/data2"
  93 info "/empire/info.nr"
  94 port "7778"
  95
  96 You only need the lines in that file that you require to override the
  97 compiled in definitions, however having all the definitions may help
  98 you to understand what is on and off. You could do this with
  99
 100 pconfig econfig1 > e1 && mv e1 econfig1
 101 pconfig econfig2 > e2 && mv e2 econfig2
 102
 103 which will fill in all the missing options and values with their defaults.
 104
 105
 106
 107 Coder information
 108 -----------------
 109
 110 The simplest way to describe this is to step through how a new option
 111 would be added.
 112
 113 1. Think of the option name, say, "DUMB".
 114 2. In src/lib/global/options.c define an integer and set it to 1 or 0
 115 as appropriate. This is usually done as
 116
 117 #ifdef DUMB
 118 int opt_DUMB = 1;
 119 #else
 120 int opt_DUMB = 0;
 121 #endif
 122
 123 3. At the end of that file, add an entry into the table so it is
 124 configurable. This is done with a line like
 125
 126     { "DUMB", &opt_DUMB },
 127
 128 Make sure the table is still terminated by two NULL values!
 129
 130 4. In include/optlist.h add an external definition of this variable
 131
 132 extern int opt_DUMB;
 133
 134 5. Now the variable is defined, and configurable through the option
 135 keyword in the config file. So you can go ahead and make changes
 136 elsewhere in the code. This normally looks like
 137
 138           if (opt_DUMB) {
 139              pr("You're being dumb\n");
 140           } else {
 141              pr ("You're being really dumb\n");
 142           }
 143
 144 but it may call subroutines, return early from functions or whatever.