contrib/top/INSTALL

   1                              TOP
   2                          Version 3.5
   3
   4                        William LeFebvre
   5                       and a cast of many
   6
   7 INSTALLATION
   8
   9 Configuration and installation of top is very straightforward.  After
  10 unpacking the sources, run the script "Configure".  It will present you
  11 with a series of questions, all of which should be explained in the
  12 presentation.  After you have answered all the questions, "Configure" will
  13 perform all the necessary configuration.  Once this is finished, type
  14 "make install".  Make will compile the sources then install the resulting
  15 executable and manual page in the appropriate places.
  16
  17 The most difficult step in the configuration is the choice of an
  18 appropriate machine-specific module.  The Configure script gives you a
  19 list of choices complete with brief descriptions of when each choice is
  20 appropriate.  Each module is contained in a separate c file in the
  21 directory "machine".  The module contains all of the machine-specific code
  22 that makes top work correctly on the architecture in question.  All of the
  23 code in the top-level directory is machine-independent (or at least
  24 strives to be).  Hints for some module choices that are not obvious are
  25 given at the end of this file.
  26
  27 The first comment in each c file in that directory contains the synopsis
  28 AND a detailed description of the machines for which that module is
  29 appropriate.  It also contains a list of authors for that module.  If you
  30 are really stumped in this choice, use grep to find your machine
  31 manufacturer's name or operating system name in machine/*.c.  If you still
  32 can't find one that is appropriate, then chances are very good that one
  33 hasn't been written yet.  If that is the case, then you are out of luck.
  34
  35 HANDLING MULTIPLE ARCHITECTURES
  36
  37 If you need to recompile top for a different architecture (that is, using
  38 a different module) you need to reconfigure top.  A short cut is available
  39 to make this a little easier.  If all of your previous answers to the
  40 configuration questions (except for the module name of course) are
  41 adequate for the new architecture, then you can just use the command
  42 "Configure <modulename>".  The configuration script will reconfigure top
  43 using the new module and all the answers you gave last time.  It will
  44 finish with a "make clean".  Once that completes, type "make install"
  45 and make will compile the sources and do the installation.
  46
  47 HANDLING MULTIPLE OS VERSIONS
  48
  49 By far the most frequently received bug report for top is something like
  50 this: "We just upgraded our operating system to version 99.9.9.9 and top
  51 broke.  What should we do?"  The simple answer is "recompile".
  52
  53 Top is very sensitive to changes in internal kernel data structures
  54 (especially the proc and user structures).  Some operating systems
  55 (especially SunOS) are notorious for changing these structure in every
  56 minor release of the OS.  This means that a top executable made under one
  57 version of the OS will not always work correctly (if even at all) under
  58 another version.  This is just one of those tough facts of life.  There is
  59 really no way around it.
  60
  61 To make life even worse, some operating systems (SunOS again) will use
  62 slightly different proc and user structures on different models.  For
  63 example, "top" built on a SparcStation 2 will not run correctly on a
  64 SparcStation 10, even if they are both running SunOS 4.1.3.  These
  65 unfortunate circumstances make maintaining top very difficult, especially
  66 in an environment that runs several different versions of the same
  67 operating system.
  68
  69 But there is hope.  If your operating system has a properly functioning
  70 "uname" command then you can handle this problem rather gracefully.
  71 Included in the distribution is a shell file called "metatop".  All this
  72 shell file does is:
  73
  74         exec top-`uname -m`-`uname -r` "$@"
  75
  76 So when you run this script, it execs a filename that is unique to your
  77 specific machine architecture and your OS revision number.
  78
  79 To use "metatop", do the following:
  80
  81         . on any machine, run Configure and choose the module that is
  82           appropriate for the machine
  83         . for all machines which use the same module:
  84             . group machines according to machine architecture AND OS
  85               revision number (i.e.: sun4-4.1.1, sun4c-4.1.1, sun4c-4.1.2,
  86               sun4-4.1.3, sun4c-4.1.3, sun4m-4.1.3, ...)
  87             . for each group, choose one machine from that group and on it
  88               run "make clean; make installmeta".
  89
  90
  91 The "installmeta" rule in the makefile will insure that top is compiled,
  92 install the shell file "metatop" as "top", then install the executable
  93 "top" with a name appropriate to the machine architecture and OS revision.
  94
  95
  96 HINTS FOR CHOOSING THE CORRECT MODULE:
  97
  98 SOLARIS 2.x
  99
 100 All versions of Solaris will now work with the module sunos5.  Version
 101 specific modules (such as sunos54) no longer exist.
 102
 103
 104 SUNOS 4.x AND MULTIPROCESSOR ARCHITECTURES
 105
 106 First, we need to be speaking the same language:
 107
 108 sun4    a regular sparc sun 4 architecture machine (sparc station 1,
 109         sparc station 2, IPC, SLC, etc.)
 110
 111 sun4m   a multiprocessor sparc (Sparc 10, 4/670, 4/690)
 112
 113 I intended to write the sunos4 module so that an executable compiled on a
 114 sun4m machine would work correctly on a sun4 machine.  Unfortunately my
 115 experiments indicate that this cannot be done.  It turns out that the user
 116 structure is so different between these two architectures that nothing
 117 short of a serious hack will make the same executable work correctly on
 118 both machines.  I recommend that you use the separate module "sunos4mp"
 119 when making an executable for a sun4m architecture, and use "sunos4" when
 120 making an executable for sun4 or sun4c architectures.
 121
 122 DIGITAL UNIX V4.0
 123
 124 This is the successor to DECOSF/1.  Use the module decosf1.
 125
 126 SOLBOURNE OPERATING SYSTEM (OS/MP)
 127
 128 If you are running OS/MP version 4.1A, then use the module "osmp4.1a".
 129
 130 If you are running a version of OS/MP OLDER than 4.1A (that is, one
 131 of its predecessors), use the module "sunos4".
 132
 133 If you are running OS/MP 4.1B or LATER, use the module "sunos4mp".
 134
 135 HP/UX OPERATING SYSTEM
 136
 137 The module hpux8 works on all version 8 systems.  Some say that it works
 138 with version 9 as well, but one user did send me a separate module for
 139 version 9.  This module has only been tested on series 800 machines.  I
 140 would recommend the following for those running version 9: try hpux9 and
 141 if it doesn't work then try hpux8.  If neither work, then send mail to me
 142 and/or the modules' authors.  Another note:  we have a model 730 supposedly
 143 running version 9.01.  The module hpux9 did not compile successfully, but
 144 the module hpux8 worked fine.  The module hpux10 works on all revisions of
 145 HP/UX 10 except 10.10, where HP removed the definition of the proc structure
 146 from the system include files.
 147
 148 NET/2 386BSD SYSTEMS
 149
 150 If your version of the operating system has patchkit 2.4 installed,
 151 then you will need to modify machine/m_386bsd.c and uncomment the
 152 definition of PATCHED_KVM.  This patchkit makes what more than a few
 153 people believe to be a wholly unnecessary patch to the way the kvm
 154 routines work.
 155
 156 A/UX SYSTEMS
 157
 158 There is a module for A/UX 3.0 and 3.1.  Whether or not it works for
 159 any other version is not known.  Proceed at your own risk.
 160
 161 Although AUX does not generally have a renice systemcall, it can be
 162 implemented by tweeking kernel memory.  The flag IMPLEMENT_SETPRIORITY
 163 controls the inclusion of this code.  It is off be default.  While
 164 such a simple hack should not be difficult to get right, USE THIS
 165 FEATURE AT YOUR OWN RISK!
 166