root/foundation-apps/grosview-maxx/README.netbsd

README file for xosview version 1.6.0, NetBSD-specific.

CVS Id:  Revision: $Id: README.netbsd,v 1.1.1.1 2008/05/04 15:53:48 emasson Exp $

  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!