#!/bin/sh

# This directory (~jc/misc) contains an assortment of useful programs,

# Most of the programs here were  written  by  John  Chambers  on  an
# assortment  of  projects, often with a bit of help from friends and
# colleagues.  Some of these programs duplicate tools that are  found
# on  some (but not all) Unix systems; having them here makes it easy
# to install them on a system where they don't exist. Some are clones
# of   the  standard  Unix  library  programs,  but  with  "improved"
# functionality.  For example, see the "rm" command, which is  useful
# in  scripts because it doesn't harass the user like /bin/rm usually
# does these days.  There's also a Rm that renames the  files  rather
# than unlinking them.

# There is a Makefile entry to build the $(BIN) directory and fill  it
# with  the  programs  here.   You  should  note  that there are a few
# programs (addr, ping) here that need to be setuid or setgid; to make
# or install them, you need to be root.

# The tar kit for the misc directory is made relative to  the  parent,
# directory so to unpack it, you should do something like:

     gunzip <misc.tar.gz | tar xf -
     cd    misc
	 make
     make  test
     make  install

# Notes:
#    # - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - #
#    # The V package is used by nearly everything in misc, so  you #
#    # will  want  to unpack it first.  If V and misc are adjacent #
#    # directories, then you can do a make inside misc and it will #
#    # cd to ../V and do a make there.                             #
#    # - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - #
#    # First, before anything here will work, you need to create a #
#    # local.h  file.  There are a number of *_local.h files here; #
#    # pick one as a prototype and copy it to local.d;  then  edit #
#    # local.h file to handle the system-dependent stuff.          #
#    # - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - #

# Most of the C code here has been "dbgized" in a way that may not be
# familiar to many C programmers.  The main thing to note is that the
# "real" sources have .b as a suffix, not .c, and the Makefile builds
# the  .c file from the .b file by running it through the b-c script.
# This is a rather trivial little script, really just a call of  sed,
# but  it's convenient to put it in a scrit.  What it does is selects
# among the source lines with : in column 1. Such lines can be either
# included  in  the  .c source or blanked out.  This is a simpler and
# cleaner scheme than complex #ifdefs to make multiple versions  from
# the  same  source.   I  mostly just use it to enable or disable the
# debug lines.  This way, they take one line rather than three.

# Most of the programs here use the dbg package. If you don't have it,
# go get it and build it, and then come back here.  It should be found
# wherever you found the tar kit for the misc package.  The best place
# to install it is in ../dbg, i.e., next door to the misc package.

# Next, edit the Makefile and make sure it's right  for  your  system.
# Note  in  particular  that  it  needs a pointer to wherever you have
# installed the dbg package.

# To build the non-setuid programs, type:
# 	make
# 	make bin

# To build the rest, become super-user and type:
# 	make install

# There are also some test programs in the test subdirectory.  You can
# run them all by typing
#    make test
# Of course, you can just use this as the first make command.

# Note that most of these use the ../dbg/libdbg.a library, which must be
# present or not much will link. Make sure that you have the dbg package
# compiled ...

# There are some programs here  that  the  "make  all"  entry  doesn't
# build.    They   are   typically   the   ones  that  are  hopelessly
# system-dependent.  You might look around after the make  works,  and
# see what odds and ends are of interest.