Next: Historical, Previous: Editing, Up: Top [Contents][Index]
This section provides the instructions for publishing a Daikon distribution,
a.k.a. making a release.
If you only want to
create the daikon.tar or daikon.tar.gz file in your own
directory, then simply run make daikon.tar
or make daikon.tar.gz
.
Official releases have even version numbers (e.g., 4.6.4) and intermediate work has odd version numbers (e.g., 4.7.3). This means as you prepare for a release the current version number is probably odd. It will be updated as one of the steps in the release process. After making the distribution, one of the final steps is to increment the version number again to prepare for subsequent development. This system has the useful side effect of allowing the build and test process to be repeated to fix a problem without having to worry about updating or resetting the version number. Another advantage is to reinforce, to people who are working from the version control repository, that they are not using the released version, because the version numbers differ.
The Daikon distribution site is located at http://plse.cs.washington.edu/daikon/ and is served from the UW CSE file system at /cse/web/research/plse/daikon. In order to be able to write to the distribution site, your CSE user id must be a member of the ‘plse_www’ Unix group.
For each of the major steps below, an approximate elapsed time is listed. These timings are up to date as of December 2015. They were measured on a quad x86-64 based machine at 3.4GHz with 16GB of memory (buffalo.cs.washington.edu). Barring any difficulties, the entire process will take at least two hours — but could be much more depending on the number of different platforms on which you test the release.
Each of the steps below assumes that you are using the Bash shell.
• Directory layout requirements: | ||
• Distribution setup instructions: | ||
• Updating dependencies: | ||
• The day before the release: | ||
• Distribution steps: |
Next: Distribution setup instructions, Up: Distribution [Contents][Index]
DAIKONDIR
must be set to a clone of
https://github.com/codespecs/daikon.
JAVA_HOME
must be set to the appropriate JDK installation.
travis login && travis token
. You might need to install the
travis
program first by running either gem install travis
or sudo apt-get install ruby-dev && sudo gem install travis
.
Make sure this file is not readable by others, for example by running
chmod og-rwx ~/private
.
BIBDIR
to a clone of
https://github.com/mernst/plume-bib.
Next: Updating dependencies, Previous: Directory layout requirements, Up: Distribution [Contents][Index]
The default version of the Java JDK on the majority of the CSE machines is now JDK 8. However, for the time being, we wish to continue to use JDK 7 for our distribution process; the intention is to maximize compatibility with our existing code base. You will find a suitable version (for an AMD64 based machine) at /homes/gws/markro/jdk7.
The recommended setup for the distribution process:
DAIKONDIR
as you would normally
export JAVA_HOME=/homes/gws/markro/jdk7
source $DAIKONDIR/scripts/daikon.bashrc
This should fulfill most of the directory layout requirements noted above.
Next: The day before the release, Previous: Distribution setup instructions, Up: Distribution [Contents][Index]
set -o pipefail (cd $DAIKONDIR && git pull && git log --branches --not --remotes && git status) (cd $DAIKONDIR/../fjalar && git pull && git log --branches --not --remotes && git status)
Each of the two commands should print exactly 4 lines:
Already up-to-date. On branch master Your branch is up-to-date with 'origin/master'. nothing to commit, working directory clean
[Time: moments]
CHECKERFRAMEWORK
environment
variable points to the location of your Checker Framework directory.
[Time: moments]
The Fjalar tool set (primarily, Kvasir) is built upon, or uses pieces from, two open source projects. The home page for the Valgrind instrumentation framework is http://www.valgrind.org. The home page for the GNU Binutils (a collection of binary tools, of which Kvasir uses only readelf) is http://www.gnu.org/software/binutils/.
File $DAIKONDIR/fjalar/valgrind/REVISION indicates the version of these tools that Kvasir uses. You can determine whether a newer version of these tools is available by comparing the REVISION file to http://valgrind.org/downloads/current.html and http://ftp.gnu.org/gnu/binutils/?C=M;O=D. If so, you should update the Fjalar source tree as soon as practical. For details, see the separate document “Merging newer versions of Valgrind into Fjalar”, which appears in the fjalar repository.
Next: Distribution steps, Previous: Updating dependencies, Up: Distribution [Contents][Index]
Do these steps the day before the release, so that tests have time to complete overnight.
cd $DAIKONDIR/doc diff -b -u -s --from-file /cse/web/research/plse/daikon/download/doc *.texinfo
Another good source of information are the repository logs since the last release:
cd $DAIKONDIR DAIKONVERSION=`wget -q http://plse.cs.washington.edu/daikon/download/doc/VERSION \ -O - | xargs echo -n` git log v$DAIKONVERSION..HEAD
In addition, you should run the same command in your Fjalar clone:
cd $DAIKONDIR/fjalar DAIKONVERSION=`wget -q http://plse.cs.washington.edu/daikon/download/doc/VERSION \ -O - | xargs echo -n` git log v$DAIKONVERSION..HEAD
When you have competed your updates, commit and push the changes.
[Time: a few minutes]
cd $DAIKONDIR/doc make spell-check
Any words that may be spelled incorrectly are output to standard out.
@nospellcheck
around it.
[Time: moments]
TODO: it would be good to build the staging release the day before, too, so that links can be fixed the day before the release or at least very early in the process.
Previous: The day before the release, Up: Distribution [Contents][Index]
Use JDK 7 for the release process.
For Travis CI,
all of the following jobs should be green:
https://travis-ci.org/codespecs/daikon
https://travis-ci.org/codespecs/fjalar
https://travis-ci.org/typetools/daikon-typecheck
https://travis-ci.org/typetools/daikon-typecheck-formatter
https://travis-ci.org/typetools/daikon-typecheck-interning
https://travis-ci.org/typetools/daikon-typecheck-nullness
https://travis-ci.org/typetools/daikon-typecheck-regex
https://travis-ci.org/typetools/daikon-typecheck-signature
If any of the jobs is not passing, then correct the problem and wait for the jobs to complete and pass. The delay to wait for this to happen is a reason that you should avoid making changes to Daikon on the release day. Instead, you should make changes the day before to permit the continuous integration jobs to run overnight.
cd $DAIKONDIR make very-clean make rebuild-everything
[Time: 20 min]
make check-repo
The result of the command above should be:
On branch master Your branch is up-to-date with 'origin/master'. nothing to commit (use -u to show untracked files)
If the command output lists any files, they need to be committed to the repository and pushed now. In that case, you will need to return to step 1 and wait for the Travis jobs to complete.
[Time: moments]
make update-dist-version-file
Note that if a new feature has been added, or if some change has made the current version incompatible from the previous release (such a change in the dtrace file format or revised names for tool options), then you should manually edit the VERSION file to increment the minor version number and reset the revision number to zero.
Optionally, override the distribution date (default: today) by
redefining the environment variable TODAY
:
export TODAY='November 1, 2013'
Now, update the appropriate files with the date and version number of the release and commit these changes back to the repository:
make update-and-commit-version
[Time: moments]
mkdir -p /tmp/$USER rm -rf /tmp/$USER/stage-daikon git clone https://github.com/codespecs/daikon /tmp/$USER/stage-daikon cd /tmp/$USER/stage-daikon export DAIKONDIR=`pwd` export JAVA_HOME=/homes/gws/markro/jdk7 source scripts/daikon.bashrc make staging
The final output of this command will be a list of files that were added/removed since the last release. If any of these differences is unexpected, then investigate. If any corrections are required, do so back in the main repository, commit the changes and then repeat this step.
[Time: 23 min]
make check-for-broken-doc-links
Review check.log and make corrections as appropriate.
In some cases a "403 Forbidden" error is transient, due to the website being down. You can check such links by hand.
If the URL is correct but cannot be checked (for example, because the website prohibits spiders or because the URL redirects to another URL but you prefer to keep the first URL in your document), then you may need to add lines to an appropriate part of file $DAIKONDIR/plume-lib/bin/checklink-args.txt.
In most cases (and for most 404 errors), you should fix the document with the incorrect link. Here is a workflow that may be used to deal with broken links:
Note that you must fix problems in the original repository, not in the drop directories. This means:
[Time: 8 min]
make test-staged-dist
[Time: 1 min]
NEW_VERSION=`cat doc/VERSION` $PLUMEBIN/trigger-travis.sh codespecs test-daikon-staging `cat ~/private/.travis-access-token` \ "Test staging distribution for release ${NEW_VERSION}" $PLUMEBIN/trigger-travis.sh codespecs test-daikon-staging-macosx `cat ~/private/.travis-access-token` \ "Test staging distribution for release ${NEW_VERSION}"
and then wait until the following
two URLs indicate success:
https://travis-ci.org/codespecs/test-daikon-staging
https://travis-ci.org/codespecs/test-daikon-staging-macosx
If there is a problem, fix it and start over.
[Time: 15 min]
$DAIKONDIR
defined!).
The output from the make command should show a number of lines beginning with "Processed" as dcomp_rt.jar is being built. Next it should indicate that Kvasir was not built because this is not a Linux platform. Then execution will continue with a test that runs Chicory/Daikon on the StackAr example. Success is indicated by invariant output being written to the screen.
export JAVA_HOME="/cygdrive/c/Program\\\ Files/Java/jdk1.7.0_45" export DAIKONBASEURL=http://plse.cs.washington.edu/staging-daikon mkdir -p ~/tmp cd ~/tmp curl --fail -O https://raw.githubusercontent.com/codespecs/daikon/master/scripts/test-distribution.sh sh test-distribution.sh
[Time: 10 min]
At this point we are done building and testing the release candidate and you should exit the Bash command shell created in step 5 and return to your original Bash shell.
cd $DAIKONDIR make staging-to-www
[Time: 1 min]
cd $DAIKONDIR DAIKONVERSION=`cat $DAIKONDIR/doc/VERSION | xargs echo -n` git tag -a v$DAIKONVERSION -m $DAIKONVERSION git push --tags cd fjalar git tag -a v$DAIKONVERSION -m $DAIKONVERSION git push --tags
[Time: moments]
cd $DAIKONDIR export -n TODAY make update-dist-version-file make update-doc-dist-date-and-version
[Time: moments]
cd $DAIKONDIR make rebuild-everything quick-test
Success is indicated by invariant output being written to the screen.
[Time: 5 min]
cd $DAIKONDIR git commit -a -m "Bump version number for ongoing development." git push cd fjalar git commit -a -m "Bump version number for ongoing development." git push
[Time: moments]
<to:> daikon-announce@googlegroups.com <subject:> Daikon version <version number> has been released Daikon version <version number> is now available. Please see the entry from the doc/CHANGES file that appears below for more details. You can download the latest version of Daikon at: http://plse.cs.washington.edu/daikon/download/ <your name> <a copy of the current entry from the doc/CHANGES file, with paragraphs refilled (remove unnecessary line breaks that trim lines to 80 columns for the CHANGES file but aren't desirable in email)>
Note that if you use Microsoft Outlook 2010 or 2013 as your mailer, by default it will insert hard breaks in your outgoing message. See http://blog.techhit.com/551102-how-to-prevent-outlook-2010-and-2013-from-adding-line-breaks-to-sent-plain-text-messages for a work around. You must quit and restart Outlook to activate the change.
Previous: The day before the release, Up: Distribution [Contents][Index]