Developer Notes

Documentation

Documentation may be generated by running doxygen:

doxygen Doxyfile

Then check the doc/ directory. Documentation is currently sparse.

Debugging

When debugging, it will be helpful to use the Shadow option --cpu-threshold=-1. It disable the automatic virtual CPU delay measurement feature. This feature may introduce non-deterministic behaviors, even when running the exact same experiment twice, by the re-ordering of events that occurs due to how the kernel schedules the physical CPU of the experiment machine. Disabling the feature with the above option will ensure a deterministic experiment, making debugging easier. (See this issue)

Build Shadow with debugging symbols by using the -g flag. See the help menu with python setup.py build --help.

You will need to set LD_PRELOAD when running in gdb. Its value should contain a colon separated list of every 'preload' library (generally prefixed with libshadow-preload and installed to ~/.shadow/lib):

gdb shadow-bin
> set environment LD_PRELOAD=/home/rob/.shadow/lib/libshadow-preload.so
> set args --echo
> run

If this doesn't work and you just see "exited with code 1", instead set LD_PRELOAD in gdb as follows:

> set exec-wrapper env LD_PRELOAD=/home/rob/.shadow/lib/libshadow-preload.so

If you want to be able to run Shadow through valgrind and the application you are running in Shadow uses OpenSSL (i.e. the Scallion plug-in), you should configure OpenSSL with the additional option: -DPURIFY. This fixes OpenSSL so it doesn't break valgrind. You may also want to ensure that debugging symbols are included in the GLib that Shadow links to, and any library used by the plug-in. This can be achieved with the compiler flag -g when manually building a local version of GLib.

Tagging new versions

The following commands can be used to tag a new version of Shadow, after which an archive and signature can be uploaded to github's download section, and linked from the Shadow website.

git tag -s v1.5.0
git push --tags
git checkout release
git merge v1.5.0
git archive --prefix=shadow-v1.5.0/ --format=tar v1.5.0 | gzip > shadow-v1.5.0.tar.gz
gpg -a -b shadow-v1.5.0.tar.gz
gpg --verify shadow-v1.5.0.tar.gz.asc