kconf  -  Linux Kernel Configurator      Version 0.2      by Werner Almesberger
====================================================== almesber@bernina.ethz.ch

kconf is a user-friendly versatile kernel configuration utility. It is
specifically designed to meet the conceptual requirements of configuring the
Linux kernel. The primary advantages of kconf over the current script-based
configuration are its capability to use settings from previous sessions, better
granularity of configuration file modifications yielding faster recompilations
and last but not least a more user-friendly interface.


    ***********************************************************************
    * This is experimental software. It may have dangerous bugs. Future   *
    * versions may be changed in incompatible ways without prior warning. *
    ***********************************************************************


  NOTE: This file contains only the first four sections of the documentation.
        The file formats are only described in the LaTeX version.
  

Distribution
============

The kconf distribution contains the following files:

  README			short description in plain ASCII.
  Makefile			Makefile to build kconf.
  *.h, *.c			source files of kconf.
  mkdist			shell script used to generate the kconf
				distribution.
  linux13.patch			demonstrational patch for Linux 0.99pl13 that
				implements a functional configuration concept
				based on kconf.
  example/			directory containing the example used in this
				document.
  example/Makefile		Makefile to run the example (make) and to clean
				up after that (make clean).
  example/example.dsc		example description file.
  example/exp_keyb.template	example template for exp_keyb.h
  doc/				directory containing the documentation source.
  doc/Makefile			Makefile to build the documentation.
  doc/fullpage.sty		document style option by H. Partl to fill the
				paper just like Plain TeX.
  doc/kconf.tex			LaTeX source of the documentation.
  doc/rlatex			shell script to repeatedly invoke LaTeX until
				all references are correct.
  test/				regression tests.


Installation
============

Installation of kconf and of the demonstration kernel (assuming you use a
Bourne-style shell like bash):

 - go to a directory in which you want the kconf directory to be created.
 - extract kconf.VERSION.tar.gz in that directory.
 - cd  to the kconf directory and extract the Linux 0.99pl13 source tree there
   (i.e. the source tree is created in .../kconf/linux)
 - cd linux
 - apply the patch with  patch -s -p1 <../linux13.patch
 - build kconf:  (cd ..; make)
 - create the usual symbolic links in /usr/include to the  linux  and  asm
   directories, plus a new link for a directory  config :
     for n in linux asm config; do
       rm -f /usr/include/$n
       ln -s `pwd`/include/$n /usr/include/$n
     done
 - create a link for the kconf binary:  ln -s ../kconf kconf
 - make config

To create the documentation, do:

 - cd to the kconf directory.
 - cd doc; make
 - now enter the necessary command(s) to print a DVI file on your system, e.g.
     dvips -r1 -f1 kconf.dvi | lpr  or
     dvips -r1 -f1 kconf.dvi |
       gs -q -sDEVICE=deskjet -sPAPERSIZE=a4 -sOutputFile=- - | lpr

To run the regression tests simply type:

  make test


Invocation
==========

kconf is invoked as follows:

kconf [ -l ] [ -n ] [ -i input_config ] [ -o output_config ]
  [ -a default_output ] [ -m make_output] config_description ...

  -l
    Enter line mode. kconf runs in full-screen mode if -l is omitted.
  -n
    Do not mark new variables with an asterisk. This is typically used when
    running kconf without a configuration input file.
  -i input_config
    Read initial variable settings from the specified file. All variables
    assume their default values and are considered "new", if -i is omitted.
  -o output_config
    Write all variable settings to the specified file.
  -a default_output
    Write header file output of variables for which no header file has been
    specified to this file. The values of these variables are not written to
    header files (but to the Makefile and to the configuration output file, if
    specified) if -a is omitted.
  -m make_output
    Write output for inclusion by GNU Make to the specified file. No such
    output if generated if -m is omitted.

At least one description file has to be specified. kconf reads structure,
types, ranges and default values of configuration variables from description
files. If more than one file is specified, they are treated as if they were
concatenated to one large file.


User interface
==============

There are two interface modes: a line mode for compatibility with the old
configuration script and a more convenient full-screen mode. Both modes offer
the same functionality, but the line mode is strictly sequential, so answers
can only be changed by re-running kconf.


General
-------

The display of kconf consists of the following items:
 - titles, usually associated with a section (see below).
 - boolean variables that can only assume the values "Yes" and "No".
 - numeric variables that can assume a non-negative integer number within a
   certain range.
 - choice variables that can assume one value from a (typically small) set of
   explicitly listed values.
 - set variables that can assume zero or more values from a set of values.
\end{items}

Each item can also have an associated section. A section is a list of items
which are related to their "parent" item. Sections are hidden if the parent
item is disabled. Sections of titles and of numeric variables are always
enabled. Sections of boolean variables are only enabled if the variable is set
to "Yes". Sections of choice and set variables are associated with the values
and are enabled if the corresponding value is selected.

Note that in the full-screen display, a section can also be invisible because
it has been folded and that sections associated with set values are only shown
if the cursor is on their value.

Before saving a configuration, kconf performs several consistency checks. If
such a check fails, an error message is displayed and the user can either
correct the problem or ask kconf to ignore that error and to proceed. This way,
it is feasible to generate warnings on very unusual and probably unintended
configurations (e.g. a kernel without hard disk support) without strictly
prohibiting such setups.


Full-screen mode
----------------

When entering kconf in full-screen mode, all top-level items are shown. Each
line contains from left to right a mark, a short text describing the item, a
summary of the sections hidden below it (if any) and one or more fields with
that item's value(s).

The mark on the left is either an asterisk, a plus sign or it is absent. An
asterisk indicates that the item or any item underneath it has never been
visited, e.g. it has been recently added and is new to the user. A plus sign
indicates items under the current one, which have been folded away.

Folding is an aid to reduce the number of items visible at one time. The
section of the current item can be folded by pressing [-]. This lets the entire
section (and possible sub-sections) disappear and a summary of the setting in
that section is added to the current item. Sections can be unfolded with [+].

The following keys are recognized in full-screen mode:
  up/down move the cursor to the next or previous item shown on the screen.
  left/right toggle the value from "Yes" to "No" and vice versa on boolean
    items, select the next or previous value on choice items, and move the
    cursor to the next or previous value without changing the selection on set
    items.
  [Enter] opens numeric items for editing. The number can be changed by adding
    digits or by removing them with [Delete] or [Backspace]. The change is
    accepted with [Enter] or cancelled with [Q].
  [+] unfolds the current item (if folded).
  [-] folds the current item. If the item can't be folded or if it is already
    folded, its parent item is folded instead.
  [Space] operates as "do what I mean" key. The action most likely wanted in
    the current context is performed:
     - on title items, the item's folding is toggled. No action is taken if
       the item can't be folded or unfolded.
     - on disabled boolean items, the value is changed to "Yes".
     - on enabled boolean items, the item's folding is toggled.
     - on numeric items, the item is opened for editing.
     - on choice items, the next value is selected.
     - on set items, the current value is switched on or off.
  [W] checks whether the current configuration is consistent and writes it to
    the specified files.
  [I] if a consistency error message is displayed, the corresponding error is
    ignored and the [W] is attempted again. Ignored errors continue to be
    ignored until the end of the configuration session.
  [Q] quits without saving the configuration.


Line mode
---------

The line mode is very similar to the Configure script currently used by Linux.
It iterates sequentially through all items and automatically enters enabled
sections.

For boolean, numeric and choice variables, the desired value has to be entered.
For set variables, kconf asks for each possible value whether it should be set
and then continues with the corresponding section, if necessary.

If no input is given, the default value (shown in square brackets) is taken. A
list of available values can be obtained by entering [?].

At the end of the questions, the configuration is saved. If kconf detects an
inconsistency, the respective error can either be ignored (like [I] in
full-screen mode) or the questions can be processed again.


Files
=====

The file formats are only described in the LaTeX version of the documentation.
