Using Niagara with Purify & Quantify

This is actually quite simple. However the final step can be a bit painful because the automake / autoconf system does not have a good way of changing the system default rules on a per-application basis. Ouch.

1. Read the directions on purifying and quantifying shore and build your own shore workspace that is setup that way.
2. Do a make install in your shore tree to "install" the libraries and include files and etc in the installed subtree.
3. Edit the shore PlatformDefines_gen.h file to put a '#ifndef' exclusion around _REENTRANT:

   #ifndef _REENTRANT
#define _REENTRANT
#endif

   You can find this file either in src/smlayer/sm/fc/ or installed/include/fc/PlatformDefines_gen.h If you don't do this the compilation will complain about definition errors. Just do it by hand for now. Note .. you'll need to repeat this performance if you change options in shore and rebuild it ... no big deal.
4. Edit your Niagara workspace's Makefile.common to refer to your purified / quantified shore workspace.

   SHORE_ROOT=/path/to/your/shore/installed

5. Edit your Makefile.common so the system libraries include -lpthread.
6. Build the normal version of niagara, which you already know how to do, or follow the directions.
7. Change directory to where you want to purify / quantify. Presumably this would be caesar:

   cd caesar

8. XXX see next step to decide which config files you want
   Symlink the shore config files to this directory which you plan to quantify and purify Niagara from. You could copy them if necessary, but then you'll have to propagate changes by hand between different directories. Yes, it hacks the files in your shore workspace, but that is why it is your shore workspace. You could also make copies of the files into your niagara workspace, and symlink from the individual build directories back to those niagara-only copies.
9. NEW -- I've put niagara-specific (aka shore + niagara-isms) config files in ~bolo/public/pure/niagara_3. Symlink (or copy) the .purify* to your Niagara build directory(ies) and use them to avoid niagara-isms that aren't errors.
10. Find the rule in the Makefile which builds the executable you want to instrument, and then copy it and make it look like the following example (see later). Basically you are adding extra commands in that will generate a purified or quantified executable named respectively exec.pure or exec.quant.
11. Build the instrumented executable -- remember to have linked or copies the config files into place first!
12. Run the instrumented executable, see the results. NOTE that you DO NOT want to load with a purified or quantified executable unless you want to analyze that behavior -- it will make an already painfully slow process even slower.

Fixing your Makefile

The problem is that the system defines rules to make programs. You can't add to them or expand them any in the rules for a particular program, such as Niagara. So, hack your Makefile like this.

Look for the line that builds the executable you are interested in. It will look something like:

exec: $(exec_OBJECTS) $(exec_DEPENDENCIES)
	@rm -f exec
	$(CXXLINK) $(exec_LDFLAGS) $(exec_OBJECTS) $(exec_LDADD) $(LIBS)

What you want to do here is _ADD_ additional entries to the Makefile based upon (copied from) this entry to build a Purified or Quantified executable. To do that, follow these steps

1. The first thing to do is to change the @rm -f exec entry to read @rm -f $@. This tells it to remove the target, which is what the generic rule should be doing in the first place, not having names hard-coded into it!
2. Once that is done, yank the three lines and copy them twice, once for purify, and once for quantify. In the first copied code, we'll setup for purify: Change the name of the executable for Purify from exec to exec.pure. Then, insert the string $(PURIFY_CMD) as the first item on the line containing the $(CXXLINK). The result will be a new entry to purify that target that looks like:

   exec.pure: $(exec_OBJECTS) $(exec_DEPENDENCIES)
   	@rm -f $@
   	$(PURIFY_CMD) $(CXXLINK) $(exec_LDFLAGS) $(exec_OBJECTS) $(exec_LDADD) $(LIBS)
   

3. To setup the target to be quantified, move to the second copy of the original that you made. We well be making changes very similar to those for purify. Change the name of the target from exec to exec.quant. Insert the string $(QUANTIFY_CMD) before the $(CXXLINK). The result will be a new entry for quantifying a target:

   exec.quant: $(exec_OBJECTS) $(exec_DEPENDENCIES)
   	@rm -f $@
   	$(QUANTIFY_CMD) $(CXXLINK) $(exec_LDFLAGS) $(exec_OBJECTS) $(exec_LDADD) $(LIBS)
   

If you want to Purify or Quantify caesar, you should just be able to apply the following patch to the Makefile in your caesar directory and be done with it:

	patch Makefile <~bolo/public/pure/niagara_3/caesar.diff

After that, assuming that you have symlinked or copied the purify config files as mentioned above ... you can just make the desired target and run it:

	make exec.quant
	./exec.quant

Have fun!