INSTALL revision 24139
124139Sjoerg TOP 224139Sjoerg Version 3.4 324139Sjoerg 424139Sjoerg William LeFebvre 524139Sjoerg and a cast of dozens 624139Sjoerg 724139SjoergINSTALLATION 824139Sjoerg 924139SjoergConfiguration and installation of top is very straightforward. After 1024139Sjoergunpacking the sources, run the script "Configure". It will present you 1124139Sjoergwith a series of questions, all of which should be explained in the 1224139Sjoergpresentation. After you have answered all the questions, "Configure" will 1324139Sjoergperform all the necessary configuration. Once this is finished, type 1424139Sjoerg"make install". Make will compile the sources then install the resulting 1524139Sjoergexecutable and manual page in the appropriate places. 1624139Sjoerg 1724139SjoergThe most difficult step in the configuration is the choice of an 1824139Sjoergappropriate machine-specific module. The Configure script gives you a 1924139Sjoerglist of choices complete with brief descriptions of when each choice is 2024139Sjoergappropriate. Each module is contained in a separate c file in the 2124139Sjoergdirectory "machine". The module contains all of the machine-specific code 2224139Sjoergthat makes top work correctly on the architecture in question. All of the 2324139Sjoergcode in the top-level directory is machine-independent (or at least 2424139Sjoergstrives to be). Hints for some module choices that are not obvious are 2524139Sjoerggiven at the end of this file. 2624139Sjoerg 2724139SjoergThe first comment in each c file in that directory contains the synopsis 2824139SjoergAND a detailed description of the machines for which that module is 2924139Sjoergappropriate. It also contains a list of authors for that module. If you 3024139Sjoergare really stumped in this choice, use grep to find your machine 3124139Sjoergmanufacturer's name or operating system name in machine/*.c. If you still 3224139Sjoergcan't find one that is appropriate, then chances are very good that one 3324139Sjoerghasn't been written yet. If that is the case, then you are out of luck. 3424139Sjoerg 3524139SjoergHANDLING MULTIPLE ARCHITECTURES 3624139Sjoerg 3724139SjoergIf you need to recompile top for a different architecture (that is, using 3824139Sjoerga different module) you need to reconfigure top. A short cut is available 3924139Sjoergto make this a little easier. If all of your previous answers to the 4024139Sjoergconfiguration questions (except for the module name of course) are 4124139Sjoergadequate for the new architecture, then you can just use the command 4224139Sjoerg"Configure <modulename>". The configuration script will reconfigure top 4324139Sjoergusing the new module and all the answers you gave last time. It will 4424139Sjoergfinish with a "make clean". Once that completes, type "make install" 4524139Sjoergand make will compile the sources and do the installation. 4624139Sjoerg 4724139SjoergHANDLING MULTIPLE OS VERSIONS 4824139Sjoerg 4924139SjoergBy far the most frequently received bug report for top is something like 5024139Sjoergthis: "We just upgraded our operating system to version 99.9.9.9 and top 5124139Sjoergbroke. What should we do?" The simple answer is "recompile". 5224139Sjoerg 5324139SjoergTop is very sensitive to changes in internal kernel data structures 5424139Sjoerg(especially the proc and user structures). Some operating systems 5524139Sjoerg(especially SunOS) are notorious for changing these structure in every 5624139Sjoergminor release of the OS. This means that a top executable made under one 5724139Sjoergversion of the OS will not always work correctly (if even at all) under 5824139Sjoerganother version. This is just one of those tough facts of life. There is 5924139Sjoergreally no way around it. 6024139Sjoerg 6124139SjoergTo make life even worse, some operating systems (SunOS again) will use 6224139Sjoergslightly different proc and user structures on different models. For 6324139Sjoergexample, "top" built on a SparcStation 2 will not run correctly on a 6424139SjoergSparcStation 10, even if they are both running SunOS 4.1.3. These 6524139Sjoergunfortunate circumstances make maintaining top very difficult, especially 6624139Sjoergin an environment that runs several different versions of the same 6724139Sjoergoperating system. 6824139Sjoerg 6924139SjoergBut there is hope. If your operating system has a properly functioning 7024139Sjoerg"uname" command then you can handle this problem rather gracefully. 7124139SjoergIncluded in the distribution is a shell file called "metatop". All this 7224139Sjoergshell file does is: 7324139Sjoerg 7424139Sjoerg exec top-`uname -m`-`uname -r` "$@" 7524139Sjoerg 7624139SjoergSo when you run this script, it execs a filename that is unique to your 7724139Sjoergspecific machine architecture and your OS revision number. 7824139Sjoerg 7924139SjoergTo use "metatop", do the following: 8024139Sjoerg 8124139Sjoerg . on any machine, run Configure and choose the module that is 8224139Sjoerg appropriate for the machine 8324139Sjoerg . for all machines which use the same module: 8424139Sjoerg . group machines according to machine architecture AND OS 8524139Sjoerg revision number (i.e.: sun4-4.1.1, sun4c-4.1.1, sun4c-4.1.2, 8624139Sjoerg sun4-4.1.3, sun4c-4.1.3, sun4m-4.1.3, ...) 8724139Sjoerg . for each group, choose one machine from that group and on it 8824139Sjoerg run "make clean; make installmeta". 8924139Sjoerg 9024139Sjoerg 9124139SjoergThe "installmeta" rule in the makefile will insure that top is compiled, 9224139Sjoerginstall the shell file "metatop" as "top", then install the executable 9324139Sjoerg"top" with a name appropriate to the machine architecture and OS revision. 9424139Sjoerg 9524139Sjoerg 9624139SjoergHINTS FOR CHOOSING THE CORRECT MODULE: 9724139Sjoerg 9824139SjoergSOLARIS 2.x 9924139Sjoerg 10024139SjoergFor Solaris versions 2.0 thru 2.3, use the module sunos5. For Solaris 10124139Sjoergversions 2.4 and higher (including 2.5 and 2.5.1) use the module sunos54. 10224139Sjoerg 10324139SjoergSUNOS 4.x AND MULTIPROCESSOR ARCHITECTURES 10424139Sjoerg 10524139SjoergFirst, we need to be speaking the same language: 10624139Sjoerg 10724139Sjoergsun4 a regular sparc sun 4 architecture machine (sparc station 1, 10824139Sjoerg sparc station 2, IPC, SLC, etc.) 10924139Sjoerg 11024139Sjoergsun4m a multiprocessor sparc (Sparc 10, 4/670, 4/690) 11124139Sjoerg 11224139SjoergI intended to write the sunos4 module so that an executable compiled on a 11324139Sjoergsun4m machine would work correctly on a sun4 machine. Unfortunately my 11424139Sjoergexperiments indicate that this cannot be done. It turns out that the user 11524139Sjoergstructure is so different between these two architectures that nothing 11624139Sjoergshort of a serious hack will make the same executable work correctly on 11724139Sjoergboth machines. I recommend that you use the separate module "sunos4mp" 11824139Sjoergwhen making an executable for a sun4m architecture, and use "sunos4" when 11924139Sjoergmaking an executable for sun4 or sun4c architectures. 12024139Sjoerg 12124139SjoergDIGITAL UNIX V4.0 12224139Sjoerg 12324139SjoergThis is the successor to DECOSF/1. Use the module decosf1. 12424139Sjoerg 12524139SjoergSOLBOURNE OPERATING SYSTEM (OS/MP) 12624139Sjoerg 12724139SjoergIf you are running OS/MP version 4.1A, then use the module "osmp4.1a". 12824139Sjoerg 12924139SjoergIf you are running a version of OS/MP OLDER than 4.1A (that is, one 13024139Sjoergof its predecessors), use the module "sunos4". 13124139Sjoerg 13224139SjoergIf you are running OS/MP 4.1B or LATER, use the module "sunos4mp". 13324139Sjoerg 13424139SjoergHP/UX OPERATING SYSTEM 13524139Sjoerg 13624139SjoergThe module hpux8 works on all version 8 systems. Some say that it works 13724139Sjoergwith version 9 as well, but one user did send me a separate module for 13824139Sjoergversion 9. This module has only been tested on series 800 machines. I 13924139Sjoergwould recommend the following for those running version 9: try hpux9 and 14024139Sjoergif it doesn't work then try hpux8. If neither work, then send mail to me 14124139Sjoergand/or the modules' authors. Another note: we have a model 730 supposedly 14224139Sjoergrunning version 9.01. The module hpux9 did not compile successfully, but 14324139Sjoergthe module hpux8 worked fine. The module hpux10 works on all revisions of 14424139SjoergHP/UX 10 except 10.10, where HP removed the definition of the proc structure 14524139Sjoergfrom the system include files. 14624139Sjoerg 14724139SjoergNET/2 386BSD SYSTEMS 14824139Sjoerg 14924139SjoergIf your version of the operating system has patchkit 2.4 installed, 15024139Sjoergthen you will need to modify machine/m_386bsd.c and uncomment the 15124139Sjoergdefinition of PATCHED_KVM. This patchkit makes what more than a few 15224139Sjoergpeople believe to be a wholly unnecessary patch to the way the kvm 15324139Sjoergroutines work. 15424139Sjoerg 15524139SjoergA/UX SYSTEMS 15624139Sjoerg 15724139SjoergThere is a module for A/UX 3.0 and 3.1. Whether or not it works for 15824139Sjoergany other version is not known. Proceed at your own risk. 15924139Sjoerg 16024139SjoergAlthough AUX does not generally have a renice systemcall, it can be 16124139Sjoergimplemented by tweeking kernel memory. The flag IMPLEMENT_SETPRIORITY 16224139Sjoergcontrols the inclusion of this code. It is off be default. While 16324139Sjoergsuch a simple hack should not be difficult to get right, USE THIS 16424139SjoergFEATURE AT YOUR OWN RISK! 16524139Sjoerg 166