create new tag
view all tags

Running Cluster Jobs

The clusterpush.pl script allows you to run a cluster regression on code that has not been committed to git.

Usage: clusterpush.pl [product] [user] [options]


Indicates which products are to be tested:

  • gs
  • pcl
  • xps
  • mupdf
  • mujstest

You can specify gs, pcl, and xps by themselves or in combation (i.e. clusterpush.pl gs pcl xps). mupdf and mujstest must be specified by themselves.

If you do not specify a product gs pcl xps will be tested if you are in a ghostpdl directory and mupdf if in mupdf.

Product can also be 'bmpcmp' (see below).


user is your cluster user name, if you don't specify one, clusterpush.pl uses, in order of preference, the value of one of the following environment variables: CLUSTER_USER, USER, and USERNAME This works as expected under Linux, Mac OS X, Msys, and probably cygwin.


Indicates that a bitmap comparison of your latest cluster run to that of the last git commit should be performed (see below).

Run only lowres (72 and 75 dpi) tests (by default both lowres and hires are run)

Run only hires (200 and 300 dpi) tests (by default both lowres and hires are run)

Relax the timeout for each job, from 5 minutes to 30 minutes. Note that the total time for the cluster job is still limited to 2 hours.

Limit jobs to those matching the specified parameter, for example filter=pgmraw will only test pgmraw files.
This option can be specified multiple times, in which case the filters are or'd together; i.e. filter=pgmraw filter=ppmraw will process both pgmraw and ppmraw files.
Separating multiple paramters seperated by a comma ands the filters together; i.e. filter=300,pbmraw processed only 300 dpi pbmraw files.

Add extra command line options to a cluster job, i.e. extras=-dEPSCROP.
This option can be specified multiple times.

Some example invocations:

  • clusterpush.pl
  • clusterpush.pl gs pcl
  • clusterpush.pl filter=ppmraw.300.0
  • clusterpush.pl filter=ppmraw.300.0 filter=pgmraw.300.0
  • clusterpush.pl extras=-dEPSCROP
  • clusterpush.pl filter=png.300.0 extras=-dDownScaleFactor=3 extras=-dDownScaleETS=1

Bitmap Comparison (bmpcmp):

To use the feature run clusterpush.pl with the option bmpcmp

toolbin/localcluster/clusterpush.pl bmpcmp 

This will queue a job that tests only the files that showed as differences in your most recent non-bmpcmp clusterpush job. It will generate bitmaps of the differences for (by default) the first 1000 differences listed in the report. These files can be found by following the bmpcmp link to the right of the your username on the regression dashboard (or at http://www.ghostscript.com/~regression/$USER).

When the job is complete you will get an email telling you that it's done. Since some of the test files are customer confidential this directory is password protected.

You can add bmpcmp to a normal clusterpush (i.e. 'clusterpush gs bmpcmp' or 'clusterpush gs pcl xps bmpcmp'). This will queue both jobs in the correct sequence.

There are some options you can use to control the jobs:

Test N files rather than 1000. (Still limited to 1000).

Rather than starting with the first difference listed in the previous non-bmpcmps clusterpush results, start with the Nth difference.

Set the "window" for the bmpcmp (default=1, sensible other values are 3, 5, 7 etc).

Set the "threshold" for the bmpcmp (default=1, value should be < 255, sensible values 8,16,33 or so). Do not use 32. 32 is a number with special meaning to the cluster, and it (and you) will be confused by what happens. Your job will go wrong. You will blame Robin. Robin will blame Marcos. Basically, no good can come of it.

So, if a job produced 2000 diffs, you can run:

  • clusterpush.pl bmpcmp

to see the first 1000 results, then once you've checked them:

  • clusterpush.pl bmpcmp -s1000

will test the second 1000 jobs.

By default bmpcmp is an exact bitmap equivalency test. By using -w and -t, you can make it a fuzzy test. -w allows for slight movements in features. -t allows for slight color changes.

Aborting a cluster job:

If you want to abort a queued or currently running cluster job you can specify abort as the clusterpush.pl option:

  • clusterpush.pl abort


The order of the options is not important.

You need to run clusterpush.pl from the top level directory (the same directory from where you normally run 'make'). Clusterpush prints an error if you try to run it from a different directory.

Results will be sent via email after the run is completed, which takes about 10 minutes, presuming the cluster isn't busy running other jobs. User jobs will take priority over non-user jobs, so even if there are many non-user jobs queued, you only ever need to wait for the current one to finish before the user queue will be processed.

Your code is compared to the most recent baseline, so for meaningful results you will want to sync your code with head if recent changes to head have resulted in output differences.

The first time you run clusterpush.pl it will take a long time to rsync your source to the master machine and then from the master to the nodes. After that things will go much quicker (unless, like me,you accidently leave giant .ppm files in the current directory).

-- Marcos Woehrmann - 2016-06-22


Edit | Attach | Watch | Print version | History: r8 < r7 < r6 < r5 < r4 | Backlinks | Raw View | Raw edit | More topic actions
Topic revision: r8 - 2018-06-26 - RobinWatts
This site is powered by the TWiki collaboration platform Powered by PerlCopyright 2014 Artifex Software Inc