diff options
Diffstat (limited to 'contrib/top/INSTALL')
| -rw-r--r-- | contrib/top/INSTALL | 165 |
1 files changed, 165 insertions, 0 deletions
diff --git a/contrib/top/INSTALL b/contrib/top/INSTALL new file mode 100644 index 000000000000..f4cfe49d3a50 --- /dev/null +++ b/contrib/top/INSTALL @@ -0,0 +1,165 @@ + TOP + Version 3.4 + + William LeFebvre + and a cast of dozens + +INSTALLATION + +Configuration and installation of top is very straightforward. After +unpacking the sources, run the script "Configure". It will present you +with a series of questions, all of which should be explained in the +presentation. After you have answered all the questions, "Configure" will +perform all the necessary configuration. Once this is finished, type +"make install". Make will compile the sources then install the resulting +executable and manual page in the appropriate places. + +The most difficult step in the configuration is the choice of an +appropriate machine-specific module. The Configure script gives you a +list of choices complete with brief descriptions of when each choice is +appropriate. Each module is contained in a separate c file in the +directory "machine". The module contains all of the machine-specific code +that makes top work correctly on the architecture in question. All of the +code in the top-level directory is machine-independent (or at least +strives to be). Hints for some module choices that are not obvious are +given at the end of this file. + +The first comment in each c file in that directory contains the synopsis +AND a detailed description of the machines for which that module is +appropriate. It also contains a list of authors for that module. If you +are really stumped in this choice, use grep to find your machine +manufacturer's name or operating system name in machine/*.c. If you still +can't find one that is appropriate, then chances are very good that one +hasn't been written yet. If that is the case, then you are out of luck. + +HANDLING MULTIPLE ARCHITECTURES + +If you need to recompile top for a different architecture (that is, using +a different module) you need to reconfigure top. A short cut is available +to make this a little easier. If all of your previous answers to the +configuration questions (except for the module name of course) are +adequate for the new architecture, then you can just use the command +"Configure <modulename>". The configuration script will reconfigure top +using the new module and all the answers you gave last time. It will +finish with a "make clean". Once that completes, type "make install" +and make will compile the sources and do the installation. + +HANDLING MULTIPLE OS VERSIONS + +By far the most frequently received bug report for top is something like +this: "We just upgraded our operating system to version 99.9.9.9 and top +broke. What should we do?" The simple answer is "recompile". + +Top is very sensitive to changes in internal kernel data structures +(especially the proc and user structures). Some operating systems +(especially SunOS) are notorious for changing these structure in every +minor release of the OS. This means that a top executable made under one +version of the OS will not always work correctly (if even at all) under +another version. This is just one of those tough facts of life. There is +really no way around it. + +To make life even worse, some operating systems (SunOS again) will use +slightly different proc and user structures on different models. For +example, "top" built on a SparcStation 2 will not run correctly on a +SparcStation 10, even if they are both running SunOS 4.1.3. These +unfortunate circumstances make maintaining top very difficult, especially +in an environment that runs several different versions of the same +operating system. + +But there is hope. If your operating system has a properly functioning +"uname" command then you can handle this problem rather gracefully. +Included in the distribution is a shell file called "metatop". All this +shell file does is: + + exec top-`uname -m`-`uname -r` "$@" + +So when you run this script, it execs a filename that is unique to your +specific machine architecture and your OS revision number. + +To use "metatop", do the following: + + . on any machine, run Configure and choose the module that is + appropriate for the machine + . for all machines which use the same module: + . group machines according to machine architecture AND OS + revision number (i.e.: sun4-4.1.1, sun4c-4.1.1, sun4c-4.1.2, + sun4-4.1.3, sun4c-4.1.3, sun4m-4.1.3, ...) + . for each group, choose one machine from that group and on it + run "make clean; make installmeta". + + +The "installmeta" rule in the makefile will insure that top is compiled, +install the shell file "metatop" as "top", then install the executable +"top" with a name appropriate to the machine architecture and OS revision. + + +HINTS FOR CHOOSING THE CORRECT MODULE: + +SOLARIS 2.x + +For Solaris versions 2.0 thru 2.3, use the module sunos5. For Solaris +versions 2.4 and higher (including 2.5 and 2.5.1) use the module sunos54. + +SUNOS 4.x AND MULTIPROCESSOR ARCHITECTURES + +First, we need to be speaking the same language: + +sun4 a regular sparc sun 4 architecture machine (sparc station 1, + sparc station 2, IPC, SLC, etc.) + +sun4m a multiprocessor sparc (Sparc 10, 4/670, 4/690) + +I intended to write the sunos4 module so that an executable compiled on a +sun4m machine would work correctly on a sun4 machine. Unfortunately my +experiments indicate that this cannot be done. It turns out that the user +structure is so different between these two architectures that nothing +short of a serious hack will make the same executable work correctly on +both machines. I recommend that you use the separate module "sunos4mp" +when making an executable for a sun4m architecture, and use "sunos4" when +making an executable for sun4 or sun4c architectures. + +DIGITAL UNIX V4.0 + +This is the successor to DECOSF/1. Use the module decosf1. + +SOLBOURNE OPERATING SYSTEM (OS/MP) + +If you are running OS/MP version 4.1A, then use the module "osmp4.1a". + +If you are running a version of OS/MP OLDER than 4.1A (that is, one +of its predecessors), use the module "sunos4". + +If you are running OS/MP 4.1B or LATER, use the module "sunos4mp". + +HP/UX OPERATING SYSTEM + +The module hpux8 works on all version 8 systems. Some say that it works +with version 9 as well, but one user did send me a separate module for +version 9. This module has only been tested on series 800 machines. I +would recommend the following for those running version 9: try hpux9 and +if it doesn't work then try hpux8. If neither work, then send mail to me +and/or the modules' authors. Another note: we have a model 730 supposedly +running version 9.01. The module hpux9 did not compile successfully, but +the module hpux8 worked fine. The module hpux10 works on all revisions of +HP/UX 10 except 10.10, where HP removed the definition of the proc structure +from the system include files. + +NET/2 386BSD SYSTEMS + +If your version of the operating system has patchkit 2.4 installed, +then you will need to modify machine/m_386bsd.c and uncomment the +definition of PATCHED_KVM. This patchkit makes what more than a few +people believe to be a wholly unnecessary patch to the way the kvm +routines work. + +A/UX SYSTEMS + +There is a module for A/UX 3.0 and 3.1. Whether or not it works for +any other version is not known. Proceed at your own risk. + +Although AUX does not generally have a renice systemcall, it can be +implemented by tweeking kernel memory. The flag IMPLEMENT_SETPRIORITY +controls the inclusion of this code. It is off be default. While +such a simple hack should not be difficult to get right, USE THIS +FEATURE AT YOUR OWN RISK! + |