README file for xosview version 1.6.0, NetBSD-specific. CVS Id: Revision: $Id$ NetBSD version written and maintained by Brian Grayson. Please direct all comments, criticisms, etc. to me at bgrayson@netbsd.org. An FAQ section is at the end of this file. If you have the pkg source tree (/usr/pkgsrc, by default) on your machine, simply "cd /usr/pkgsrc/sysutils/xosview && make && make install" should do the trick, and you can skip all of this mumbo jumbo. ***************************************************************************** Note: xosview needs to run 'setgid kmem' in order to access some of the kernel information (at least until some more statistics are added to the /kern or /proc file systems). If you do not have root or kmem permission on the machine, xosview will not run. ***************************************************************************** To make xosview: Unpack the tar file. It should create its own directory, named xosview-1.x.x, and place all of its files there. Now, cd to xosview-1.x.x, and run ./configure. This should set up acceptable Makefiles for you. Edit Makefile.config if desired (to enable debugging, or disable optimization, for example). Make sure CXX and CXXFLAGS are set up properly for your version of gcc (gcc 2.6.3 or higher is required. The code development was done using gcc 2.7.2). Only profiling (-p, -pg, -a) and debugging (-g, -ggdb) options should usually be modified in the CXXFLAGS definitions. The Makefile.config should include -lkvm in the LIBS definition. If not, configuration must have not worked properly. Mail me if this happens.... Run "make" with no options. (Since most people shouldn't need to mess with the source code, we haven't enabled automatic dependence checking. If you plan on modifying bits and pieces and recompiling, simply run configure with --enable-auto-depend. Unfortunately, the autodepend code requires the use of GNU make.) It should start compiling the netbsd directory files, create a library (libmeter.a) out of all the .o files, and then compile the main directory. Finally, it should link. Test the executable to make sure it works. You need to be root, or a member of group 'kmem', to test it at this stage. xosview will come up with the default compile-time resources. If there are no problems, then you can use 'make install' (run while 'root') to install a stripped, setgid copy of xosview and the Xdefaults into appropriate places. The configure script uses a little Imakefile magic to guess the proper locations (usually /usr/bin/X11 and /usr/lib/X11/app-defaults/XOsview, respectively). The man page can be installed by "make install-man". If you have /usr/local NFS-mounted from another computer, you may need to make sure that the mount has maproot=0 and is suid (or something like that. I'm not an NFS expert, but if I copy an xosview executable into my home directory, which is mounted nosuid, it does not run suid/sgid, whereas if I copy it into /usr/local/bin, which is mounted suid, it runs with no problem). Congratulations -- xosview has been installed on your system! If you wish, you may change the site-wide /usr/lib/X11/app-defaults/XOsview file, or you can use your local .Xdefaults file to change xosview's appearance. Notice that most of the command-line options use +foo to turn on foo, and -foo to turn off foo. This is contrary to most tradition, but is logical. :) I personally use a set of resources such that the idle field of each meter is black, and the other colors used for fields are fairly constant from one meter to the next. If you'd like a copy of our local .Xdefaults file (rather than modifying the 50 resources yourself), just mail me! xosview is able to accept the -name option, for you XResource aficionados. Stipple support: Also, NetBSD-mac68k people (and others) that have monochrome systems may want to try out the new stipple code -- set the enableStipple resource to true, and choose black and white for the various fields. The fields are automatically stippled 100%, 75%, 50%, and 25% in a fixed fashion (future versions may allow the user to specify the stipple percentage). Some resources were included with the xosview source code to allow an easy example. Type 'xrdb -merge Xdefaults.stipple', followed by 'xosview -name xosvstipple &' and 'xosview -name xosvstipplebw &'. This will bring up two xosview windows, one using stippling with color (xosvstipple) and one using only black and white (xosvstipplebw). The stipple support is fairly experimental, so provide any feedback you can -- positive, negative, etc. If this README was incomplete, or you feel an additional comment or two would be helpful to other users, please Email me -- I want this to be as complete and idiot-proof as possible! Enjoy! Brian Grayson (bgrayson@netbsd.org) Further information/FAQs: 1. Why does xosview need to be setgid kmem, i.e., why doesn't it use user-level system calls, and the optional-but-recommended /kern and /proc filesystems? Information such as the breakdown of CPU usage is not yet available (or not available in the kind of detail xosview desires/requires) through any system calls, sysctl, /kern, or /proc (at least not that I know! If not, let me know.) Thus, xosview occasionally needs to munge through the kernel's data structures to get its information. 2. Why does the cpumeter show user, nice, system, and idle/free, but not show interrupts? As far as I can tell (from looking at the kernel source code) the interrupt field is always 0, and is never set up properly for statistics (Look at the output from 'top' -- have you ever seen the %interrupt field be anything besides 0?). I decided that putting a field label for 'INTR' would imply that these statistics were correct, and that the interrupts were being correctly charged, which they are not. If anyone knows of an easy patch to the kernel source (ha ha) that would make the interrupt field in _cp_time be correct, let me know. 3. The swap meter doesn't seem to be working. When NetBSD went from 1.2F to 1.2G, the swap system was revamped. This means two things: the old xosview method of looking at kernel data structures no longer works, because the symbols have changed too much, and a new handy function swapctl() was added to make such munging unnecessary. This is all good. However, in order to be backwards compatible, xosview still needs to know how to do its munging. This way, an xosview compiled on a 1.2G or later system will still get correct swap values on pre-1.2G systems. In addition, new xosview's compiled on 1.2F or earlier systems have no way of adding support for a syscall that they don't even know about. I probably could have hacked up something, but it would have been ugly, so if xosview compiled on a pre-1.2G system is run on a system that it suspects may be 1.2G or later, it prints a helpful message saying a recompilation is needed. So, if swap isn't working, either: a) You aren't using /netbsd as the kernel, and forgot to use the -N option. b) You compiled xosview on a pre-1.2G system and are now running it on a 1.2G or later system. In this case, you should get a helpful message, if you are running 1.4.4beta or later, or no useful message if you are running 1.4.3beta or earlier. c) Anything else is a bug, I think. :) 4. The battery meter doesn't display. By default, the battery meter is not enabled. To enable it, put these resources in either your system-wide app-defaults file (probably /usr/X11R6/lib/X11/app-defaults/XOsview) or in your personal ~/.Xdefaults (feel free to change the color scheme!): ! Battery meter resources: xosview*battery: true xosview*batteryLeftColor: orange xosview*batteryUsedColor: orange xosview*batteryPriority: 50 xosview*batteryUsedFormat: autoscale Enjoy!