[src/trunk]: src/sys/conf Document command line options and other inputs and ...

[apb <apb%NetBSD.org@localhost>]

details:   https://anonhg.NetBSD.org/src/rev/7fa361c00e47
branches:  trunk
changeset: 796700:7fa361c00e47
user:      apb <apb%NetBSD.org@localhost>
date:      Sat Jun 14 12:42:41 2014 +0000

description:
Document command line options and other inputs and outputs.

diffstat:

 sys/conf/newvers.sh |  72 ++++++++++++++++++++++++++++++++++++++++++++++++++++-
 1 files changed, 71 insertions(+), 1 deletions(-)

diffs (102 lines):

diff -r fc7d36ce3d48 -r 7fa361c00e47 sys/conf/newvers.sh
--- a/sys/conf/newvers.sh       Sat Jun 14 12:35:18 2014 +0000
+++ b/sys/conf/newvers.sh       Sat Jun 14 12:42:41 2014 +0000
@@ -1,6 +1,6 @@
 #!/bin/sh -
 #
-#      $NetBSD: newvers.sh,v 1.58 2014/06/14 12:35:18 apb Exp $
+#      $NetBSD: newvers.sh,v 1.59 2014/06/14 12:42:41 apb Exp $
 #
 # Copyright (c) 1984, 1986, 1990, 1993
 #      The Regents of the University of California.  All rights reserved.
@@ -31,6 +31,71 @@
 #
 #      @(#)newvers.sh  8.1 (Berkeley) 4/20/94
 
+# newvers.sh -- Create a "vers.c" file containing version information.
+#
+# The "vers.c" file in the current directory is the primary output.  It
+# contains C source code with several variables containing information
+# about the build.  This file is expected to be incorporated into a
+# kernel, and when that kernel is booted then the information can be
+# queried by the uname(8) command.
+#
+# Command line options:
+#
+#     -r                Reproducible build: Do not embed directory
+#                       names, user names, time stamps, or other dynamic
+#                       information into the output file.  This intended
+#                       to allow two builds done at different times and
+#                       even by different people on different hosts to
+#                       produce identical output.
+#
+#     -i <id>           Use the specified string as the value of the
+#                       kernel_ident variable
+#
+#     -n                Do not include an ELF note section in the output
+#                       file.
+# Environment variables:
+#
+#     BUILDID          If defined, ${BUILDID} is appended to the
+#                      default value of the kernel_ident string.
+#                      (If the -i command line option is used, then
+#                      BUILDID is not appended.)
+#
+# Output files:
+#
+#     vers.c            The "vers.c" file in the current directory is
+#                       the primary output.
+#
+#     version           The "version" file in the current directory
+#                       is both an input and an output.  See the
+#                       description under "Input files".
+#
+# Input files:
+#
+#     version           The "version" file in the current directory
+#                       contains an integer counter, representing the
+#                       number of times this script has been executed in
+#                       this directory, starting with "0" if the file
+#                       does not exist.  The serial number in the file
+#                       is incremented after the file is read. so that
+#                       the incremented serial number is an output from
+#                       the present build and an input to the next build
+#                       that is performed in the same directory.
+#
+#     copyright         The "copyright" file (in the same directory as
+#                       this script itself) contains a copyright notice,
+#                       which is embedded in the copyright variable in
+#                       the output file.
+#
+#     ident             The "ident" file in the current directory is optional.
+#                      If this file exists, then its contents override the
+#                      default value of the kernel_ident string.
+#
+# Input from external commands:
+#
+#     osrelease.sh      This script is expected to print the OS revision.
+#                       The result is stored in the osrelease variable.
+#
+
 if [ ! -e version ]; then
        echo 0 > version
 fi
@@ -46,13 +111,18 @@
 while [ $# -gt 0 ]; do
        case "$1" in
        -r)
+               # -r: Reproducible build
                rflag=true
                ;;
        -i)
+               # -i <id>: Use the secified string as the
+               # value of the kernel_ident variable
                id="$2"
                shift
                ;;
        -n)
+               # -n: Do not include a ELF note section
+               # in the output file.
                nflag=true
                ;;
        esac