Changeset View
Changeset View
Standalone View
Standalone View
contrib/top/INSTALL
Property | Old Value | New Value |
---|---|---|
svn:keywords | FreeBSD=%H \ No newline at end of property | null |
TOP | TOP | ||||
Version 3.5 | Version 3.8beta1 | ||||
William LeFebvre | William LeFebvre | ||||
and a cast of many | and a cast of many | ||||
INSTALLATION | INSTALLATION | ||||
Configuration and installation of top is very straightforward. After | Configuration and installation of top is easy. Top version 3.6 | ||||
unpacking the sources, run the script "Configure". It will present you | comes with a configure script generated by gnu autoconf. After | ||||
with a series of questions, all of which should be explained in the | unpacking the tar file, simply run "./configure". The script will | ||||
presentation. After you have answered all the questions, "Configure" will | automatically perform a series of checks on the system and determine | ||||
perform all the necessary configuration. Once this is finished, type | what settings are appropriate for the Makefile and certain include | ||||
"make install". Make will compile the sources then install the resulting | files. Once configure completes, simply type "make install" and | ||||
executable and manual page in the appropriate places. | top will be compiled and installed. By default, the installation | ||||
location is /usr/local/bin. You can change the destination location | |||||
with the --prefix option to configure. | |||||
The most difficult step in the configuration is the choice of an | In addition to the standard options, top's configure script supports | ||||
appropriate machine-specific module. The Configure script gives you a | the following: | ||||
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 | --with-module=name | ||||
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 | Force the use of a particular module. Modules are located | ||||
in the subdirectory "machine". A module's name is derived | |||||
from the file's basename without the leading "m_". | |||||
If you need to recompile top for a different architecture (that is, using | --with-ext=name | ||||
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 | Compile with the extension "name", found in the subdirectory | ||||
"ext". At the present time, there are no extensions in the | |||||
standard distribution. | |||||
By far the most frequently received bug report for top is something like | --enable-debug | ||||
this: "We just upgraded our operating system to version 99.9.9.9 and top | --disable-debug | ||||
broke. What should we do?" The simple answer is "recompile". | |||||
Top is very sensitive to changes in internal kernel data structures | Default off. Include debugging output in the compilation, | ||||
(especially the proc and user structures). Some operating systems | which can be seen with the -D switch. | ||||
(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 | --enable-color | ||||
slightly different proc and user structures on different models. For | --disable-color | ||||
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 | Default on. Include code that allows for the use of color | ||||
"uname" command then you can handle this problem rather gracefully. | in the output display. Use --disable-color if you do not | ||||
Included in the distribution is a shell file called "metatop". All this | want this feature compiled in to the code. The configure | ||||
shell file does is: | script also recognizes the spelling "colour". | ||||
exec top-`uname -m`-`uname -r` "$@" | --enable-kill | ||||
--disable-kill | |||||
So when you run this script, it execs a filename that is unique to your | Default on. Include code that allows for renicing and sending | ||||
specific machine architecture and your OS revision number. | signals to processes from within top (the 'kill' and 'renice' | ||||
commands). Use --disable-kill if you do not want this feature | |||||
To use "metatop", do the following: | compiled in to the code. | ||||
. 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 | |||||
All versions of Solaris will now work with the module sunos5. Version | |||||
specific modules (such as sunos54) no longer exist. | |||||
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! | |||||