home *** CD-ROM | disk | FTP | other *** search
/ Fresh Fish 10 / Fresh_Fish_10_2352.bin / useful / util / edit / mg / docs / config < prev    next >
Text File  |  1990-06-02  |  28KB  |  671 lines
  1.  
  2.             CONFIG USERS MANUAL
  3.  
  4.  
  5.  
  6. 0. TABLE OF CONTENTS
  7.  
  8.     0.    TABLE OF CONTENTS
  9.     1.    INTRODUCTION
  10.     1.1    Description
  11.     1.2    Overview
  12.     1.3    Conventions
  13.     2.    PREPARING A CONFIGURATION
  14.     2.1    Syntax
  15.     2.2    Options Files
  16.     2.3    Configuration Files
  17.     3.    PREPARING OPTIONS FILES
  18.     3.1    Value Options
  19.     3.2    Option Options
  20.     3.3    Required Options
  21.     3.4    Action Options
  22.     3.5    Names To Avoid
  23.     4.    PROGRAMMING FOR CONFIG
  24.     4.1    Starting Out
  25.     4.2    Required Options
  26.     4.3    Option Options
  27.     4.4    Value Options
  28.     4.5    The "Appropriate" Options File
  29.     4.6    Converting a Program for Config
  30.  
  31. 1. INTRODUCTION
  32.  
  33. This section describes config, gives an overview of this manual, and
  34. introduces the user to the conventions and terminology of config.
  35.  
  36. 1.1 Description
  37.  
  38. Config is a tool that makes configuring a certain type of large
  39. program much easier for anyone not intimately familiar with the
  40. details of the program. It also makes keeping multiple different
  41. configurations of such programs easier - even though they may run on
  42. different machines, or under different operating systems.
  43.  
  44. The programs in question all use numerous symbols to control the
  45. conditional compilation of features in the program, or to control
  46. which code is compiled for what system.  These programs need to run on
  47. multiple different machines or operating systems, or run in an
  48. environment where having all the features of a program enabled entails
  49. an unacceptable performance cost, or makes running the program
  50. impossible.
  51.  
  52. The two normal approaches to this type of program both have problems.
  53. One approach is to change the compile commands to enable and disable
  54. features. The other approach is to keep a large file which defines all
  55. the features, and have all other files depend on that. The first can
  56. quickly generate unwieldy command lines. Both require recompiling the
  57. entire program after a change of one option, unless that option only
  58. effects one file, and the automatic building facility used for that
  59. program is defeated. Config provides an alternative that avoids both
  60. of these problems. 
  61.  
  62. 1.2 Overview
  63.  
  64. This config users manual has the following four sections:
  65.  
  66. Section 1 states what config is used for, describes this manual, and
  67. explains some conventions and terminology used throughout the manual.
  68. It should be read by anyone not already partly familiar with config.
  69.  
  70. Section 2 explains how, if you have a program already prepared for use
  71. with config and all the appropriate files set up, you would go about
  72. preparing a new configuration of that program. It should be read by
  73. everyone who wishes to rebuild a config-supported program.
  74.  
  75. Section 3 explains the meaning of the options files in terms of the
  76. program. It should be read by all those who are adding features to a
  77. config-supported program.
  78.  
  79. Section 4 describes what form a program must be in before it can be
  80. supported by config, and how to set up the initial configuration files
  81. for a program. It should be read by anyone who has a program they
  82. would like config to support.
  83.  
  84. 1.3 Conventions
  85.  
  86. There are several conventions associated with the use of config that
  87. are assumed to be true throughout this manual. The first is that
  88. config is being used to configure a program, referred to as "the
  89. program." The second is that all the files needed by config are in one
  90. directory, near the top of the source tree for the program. The third
  91. is that that directory is called "conf". It will hereinafter be
  92. referred to as "the conf directory", or just "conf". Config assumes
  93. that at the same level as the conf directory there will be one
  94. directory for every configuration that can currently be built. These
  95. will be called "configuration directories", or "the configuration
  96. directory". The names of these directories are usually in upper case.
  97. In the conf directory, there are two types of files which config cares
  98. about. The first are those with the extension ".options". These are
  99. "options files". The second are conventionally in upper case, and
  100. represent different configurations of the program.  For each of these,
  101. there should be a configuration directory with the same name. These
  102. are "configuration files" or "config files".  Configuration files and
  103. options files contain lines, each of which is either a comment, or
  104. describes some symbol the programmer uses to control compilation of
  105. the program. These symbols are called options.  Currently, config only
  106. supports the configuration of C programs. It could easily support
  107. others, but this document assumes the program is written in C. 
  108.  
  109.  
  110. 2. PREPARING A CONFIGURATION
  111.  
  112. This section describes the steps necessary to prepare a configuration
  113. file for use in building a configuration of a config-supported
  114. program. 
  115.  
  116. 2.1 Syntax
  117.  
  118. In the conf directory, you should find a collection of options files.
  119. These list all the options that can be used in all configurations of
  120. the program. Some options are required; some can be toggled on or off;
  121. others allow you to change values used by the compiler. The form of
  122. each line in an option file indicates which it is.
  123.  
  124. The most important rule about options files is that it's line based.
  125. The end of a line is the end of an option. The second thing to know is
  126. that a "#" character followed by a space starts a comment. Everything
  127. after that will be ignored by config, and is for the benefit of the
  128. reader. The meaning of the option is given in the comment. The third
  129. rule is that the first word on the line is the "name" for the option
  130. this line describes, and that everything from the end of the name to
  131. the start of any comment or the end of the line, ignoring any leading
  132. or trailing whitespace, is the "value" for the option this line
  133. describes. 
  134.  
  135. There are two special values for options in the options files. The
  136. first is "required". This means any config file that uses options in
  137. that options file must specify a value for that option (explained
  138. in a later section). The second special value is "option". This
  139. means that the named option is a toggle, and is normally off. It also
  140. changes the format used in the configuration file for that option.
  141. Finally, there is one special name for options: "action". You should
  142. ignore any option lines with that name. All other options allow you to
  143. specify a value for the named option, and list the default value if
  144. you don't specify one.
  145.  
  146. A required option could look like this, with comments:
  147.  
  148. system        required    # which system we're compiling it for
  149.                 # currently supported: amiga, vms, bsd
  150.  
  151. A toggle option might look like this, with comments.
  152.  
  153. no_metakey    option        # disables the use of "meta" keys as modifiers
  154.                 # instead of prefacing commands sequences with
  155.                 # an ESC character
  156.  
  157.  
  158. This option, according to the comments, says that "meta" keys are supported
  159. for all configurations unless their config file specifies
  160. "no_metakey".
  161.  
  162. A non-required value option could look like this:
  163.  
  164. metabit            0x80    # what bit in a char is the metabit
  165.  
  166. which says that metabit is normally "0x80", unless the config file
  167. changes it.
  168.  
  169. 2.2 Options Files
  170.  
  171. Now that you know the syntax for an options file, you can start
  172. reading them. The first one to read is always "config.options". It
  173. describes the options that exist in every configuration of the
  174. program. You should read through config.options, reading the comments
  175. that describe each option (if there are no such comments, you should
  176. find the author of the program or options file and insist that they be
  177. added), and considering what values you would like those options to
  178. have.
  179.  
  180. First, decide what values the required options should have. These
  181. values will be limited to a small set, and should be listed in the
  182. comments.  For example, according to the comments:
  183.  
  184. system        required    # which system we're compiling it for
  185.                 # currently supported: amiga, vms, bsd
  186.  
  187. the required option "system" can be set to amiga, vms or bsd.
  188.  
  189. After you've decided what values you want the required options to
  190. have, you should look for options files with the first part of the
  191. names being the values you've chosen. For example, if you wanted
  192. system to be "amiga", you would look for "amiga.options". This file
  193. will list more options that are available for the program if it's
  194. configured with "system" as "amiga". You should read through that file
  195. in the sa