gkrellmGIMPS Installation Document

(by Jay Miller [jnmiller, cryptofreak dot org])

http://www.cryptofreak.org/projects/gkrellmgimps/

$Id: INSTALL,v 1.12 2003/03/25 02:44:22 jnmiller Exp $


Contents
~~~~~~~~
1. Compilation
2. GIMPS Client Pre-Config
3. Configuration
4. Bugs and Troubleshooting
5. FAQ (or How This Plugin Can Be Less Stupid)
6. Acknowledgements



1. Compilation
~~~~~~~~~~~~~~
gkrellmGIMPS has the ability to monitor many instances of a GIMPS
client for those of you with SMP machines.  The number of instances that
can be monitored is set at compile-time and defaults to 2.  For those of
you running more than 2 instances, you'll want to edit the following
line in krell.h to an appropriate number:

#define NUM_CPUS 2

(Note: If you're only running a single GIMPS client, you needn't worry
about this - you can disable extra instances in the config section.)

The default install directory is /usr/local/lib/gkrellm2/plugins.  If
this isn't correct, edit the makefile to suit your directory tree.  Then
just make it:

# make ; make install



2. GIMPS Client Pre-Config
~~~~~~~~~~~~~~~~~~~~~~~~~~
Before setting up the plugin, you need to know a couple things about
your GIMPS client.

- Note the directory in which its persistent data files reside.  In
  particular, GKrellM needs to have access to your worktodo.ini file and
  the temporary progress file (eg. 'pI174902').
- Also note the frequency at which your client does disk writes.  You're
  looking for the value of 'DiskWriteTime' in your prime.ini file.  If
  that line isn't there, the default value is 30 minutes.

  

3. Configuration
~~~~~~~~~~~~~~~~
If you reload GKrellM with the gkrellmGIMPS module in the correct
location, you should see a new entry in the list shown when 'Plugins'
is selected called 'GIMPS'.  When you select it, make sure the 'Enable'
checkbox is checked.  You should then see a new title under in the
configuration monitors list (on the left) called 'GIMPS'.

Like other GKrellM monitors, the 'Info' tab provides quick and dirty
help on configuration as well as a reference for format string syntax.
The 'About' tab displays gkrellmGIMPS version info.

The tabs labelled 'CPU/Instance n' contain an identical set of widgets
meant to adjust the preferences for monitoring the nth instance of your
GIMPS client.

'Show this instance'
   This checkbox decides whether to display any panels at all for the
   specified instance.  If off, no other config settings are considered.
'Minutes between progress updates'
   Sets the interval between disk reads to the GIMPS client's persistent
   data.  Note that it doesn't make sense to have this number be less
   than the 'DiskWriteTime' value found in section 2.
'Location of work-to-do file'
   Full name of the GIMPS client's work list.  The path will also be
   used to find the temporary progress file.

'Show incremental progress meter'
   Some jobs done by the GIMPS client have intemediate stages that can
   be measured.  This checkbox decides if such a panel will be visible.
'Show overall progress meter'
   This checkbox turns on (or off) the krell which displays overall work
   unit progress.
'Show completion time tooltip'
   On certain systems (see FAQ, below), a tooltip displaying the work
   unit's estimated completion time will be shown if this box is
   checked.

'Format string'
   In addition to the standard percentage krells, the following formatting
   codes may be entered in the `Format string' text entry boxes to reveal
   additional progress information.

   Code:  Meaning:

   $n      [All] The number currently being tested.
   $T      [All] Type of work underway. (eg. 'Factor')
   $t      [All] First letter of above.
   $B      [Factoring] Exponent limit for trial factoring.
   $b      [Factoring] Current exponent for trial factoring (<= $B).
   $i      [DC/LL] Current iteration for primality testing (<= $n).

   $[.?]P  [All] Percent complete for overall work unit.  This percentage
           can be modified by a '.' and any one digit to produce floating
           point output to the requested precision. (eg. '$.3P%' might
           produce '42.071%')
   $[.?]p  [All] Percent complete for current increment (see above).

   $$      [All] Produces a '$'. (shrug)



4. Bugs and Troubleshooting
~~~~~~~~~~~~~~~~~~~~~~~~~~~

If you happen to have trouble using gkrellmGIMPS, please let me know!
The development site linked to at the above address has a bug tracker -
please use it!

However, before submitting a bug, please try to compile gkrellmGIMPS
with the '-DDEBUG' flag specified in the makefile.  This will dump some
useful information to a log.  It may help you fix your problem without
needing to submit a bug and otherwise it'll help me track the bug down.
The log's filename defaults to '/tmp/gkrellmgimps.log' - change it in
debug.h if you like.

And of course, I'm all too happy to accept patches.



5. FAQ (or How This Plugin Can Be Less Stupid)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

- How can I read the remote GIMPS files on one computer?
  
At first, this plugin might seem more trouble than it's worth.  Most of
your GIMPS clients are probably running on computers that aren't
immediately visible - maybe they don't have monitors at all.

One solution: run GKrellM on the remote box, but export the window to
your desktop's display with the usual 'setenv DISPLAY :0'.

A better solution is to put all of your GIMPS persisent data in a single
exported directory - say your home directory.  Now adjust the 'NUM_CPUS'
define as I explain in section #1, above, to the number of clients you
run.  Each instance should now have its own tab in the configuration
section where you may specify the instance-specific information.

Another good solution: using the same exported directory, run multiple
GKrellM instances from a single script.  See also the next question.


- But wait, I saw your screenshots - you had the hostname of every box
  display on each GKrellM instance.  You can't do that if they all run
  from the same script.
  
True.  My answer to this problem is a patch to GKrellM - a very simple
patch.  If you're interested in making this work, check out the
'Documents' section of the web page at the top of this text.


- And speaking of screenshots, how come my GKrellM themes don't work
  with gkrellmGIMPS?

This happens because many themes aren't built with gkrellmGIMPS in mind.
Specifically, the themes with graphics sets (instead of standard krells)
need explicit entries for gkrellmGIMPS in their gkrellrc files.  It's
easy to correct this, though.  For themes that don't work, simply open
up the theme's gkrellrc file and copy any lines that apply to the 'mem'
module.  Here's one such line from the BlueMask theme:

StyleMeter mem.label_position = 0

To make the same style adjustments to the gkrellmGIMPS module, replace
'mem' with 'gimps':

StyleMeter gimps.label_position = 0

Make copies of all such lines, and hit 'F5' in GKrellM to refresh the
theme when you're finished.


- I have the 'tooltip' checkbox on, but my tooltip isn't working or is
  incorrect.

The estimated completion time tooltip currently works by exploiting the
undocumented '-s' switch of mprime versions 22.12 and later.  One problem
may be, then, that your version of mprime is not new enough.  Run 'mprime
-v' to check its version.

Another likely problem: the gkrellm process is unable to execute mprime.
If gkrellm is monitoring a target other than the machine on which gkrellm
is running (eg. Windows), or you happen to be using the '-W' switch to
refer to another directory, gkrellmGIMPS will be unable to gain
information from mprime.  There is no solution to the former issue, but
creating a soft link in the appropriate directory (to mprime) should
solve the latter.

Finally, if gkrellm is running on a machine other than the target, you
may get an inaccurate reading according to the differences in CPU
speeds.



6. Acknowledgements
~~~~~~~~~~~~~~~~~~~

Frank Solensky  provided me with a very thorough
patch bringing the code up to date with Gtk+-2.0 (as well as squashing
a small bug).  He is also largely responsible for the tooltip code and,
in general, prompting me to actually put out new releases.