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