New Release

Instructions for releasing a new version of Dr. Memory

Versioning

We use a 3-field version number, major.minor.patchlevel. We have a version for the Dr. Memory tool and a separate version for DRMF. For both version numbers, the major is incremented on a major feature addition (new platform, e.g.) or on an interface change that breaks backward compatibility (for Dr. Memory itself, that would mean something like a suppression format or runtime option change; the DRMF is versioned separately from the tool). The minor is incremented on an interface addition (i.e., new features) that does not break compatibility, although for minor compatibility breaks in non-core features we may increment only the minor version. The patchlevel is 0 for an official release or the subversion revision number for a developer build. If we put out a bugfix release, the patchlevel will be a small integer smaller than any revision number.

After releasing an official release, we leave the major.minor unchanged. Even if we add new features during development before the next release, we leave the major.minor the same. However, if we break backward compatibility during development, we expect to increment the major number on the next release and we immediately change the minor number to 90. A subsequent break before the next release would increment that to 91, and so forth. This allows users to perform dependence checking on the existing major.minor and not have interfaces change.

For DRMF, users must perform dependence checks only versus either an official release or the very latest development version. This allows us to release a bugfix version X.Y.1 and not have users who depend on that bugfix be confused by a development version X.Y.NNNN that does not have the fix yet has a higher version number.

Setup for Building Release Packages

First, set up a symlink or NTFS junction such that the source path to Dr. Memory looks "professional", for the replace_malloc frames. For example, here is what I did on Windows:

cd /d
cmd /c mklink /J drmemory_package 'd:\derek\withwiki\trunk'

And on Linux:

ln -s /work/drmemory/withwiki/trunk /work/drmemory_package

When I build pointing at d:/drmemory_package/package.cmake, error messages then look like this:

Error #4: INVALID HEAP ARGUMENT to free 0x00001230
# 0 replace_free               [# 1 main                       [d:\derek\drmemory\git\src\tests\malloc.c:175](d:\drmemory_package\common\alloc_replace.c:2352])
Note: @0:00:00.344 in thread 3224

Next, be sure to use doxygen >= 1.8.1 for high-quality documentation. On Windows, use a non-Cygwin build (I use ftp://ftp.stack.nl/pub/users/dimitri/doxygen-1.8.1.1.windows.bin.zip, with doxygen.exe placed in /usr/local/bin: see DR issue 815).

On Windows, we prefer our WIX-based MSI installer over the older NSIS installer. Ensure you have at least CMake 3.3.0, WIX is installed, and WIX's candle.exe is on your PATH. The configure status lines should then indicate the selection of WIX instead of NSIS for the installer build.

To instead build an NSIS-based installer, ensure you have NSIS installed with large string support so that the installer will be properly built. Configure status lines will indicate this. See the build instructions for more information.

Building Candidate Packages

Build using package.cmake, and ensure your drmemory_package sources are up to date. On Windows:

cd ~/drmemory/build_package/
compilerVS2010_32
ctest -V -S d:/drmemory_package/package.cmake,drmem_only\;build=4\;cacheappend=TOOL_VERSION_NUMBER:STRING=1.9.0\;cacheappend=DRMF_VERSION:STRING=1.0.0\;use_ninja\;cpackappend=set\(CPACK_PACKAGE_FILE_NAME\ DrMemory-Windows-1.9.0-4\)
chmod ugo+rx *.msi

On Linux:

cd /work/drmemory/build_package/
ctest -V -S /work/drmemory_package/package.cmake,drmem_only\;build=4\;cacheappend=TOOL_VERSION_NUMBER:STRING=1.9.0\;cacheappend=DRMF_VERSION:STRING=1.0.0\;cpackappend=set\(CPACK_PACKAGE_FILE_NAME\ DrMemory-Linux-1.9.0-4\)

On MacOS:

cd ~/drmemory/build_package
ctest -V -S /drmemory_package/package.cmake,drmem_only\;32_only\;build=4\;cacheappend=TOOL_VERSION_NUMBER:STRING=1.9.0\;cacheappend=DRMF_VERSION:STRING=1.0.0\;cpackappend=set\(CPACK_PACKAGE_FILE_NAME\ DrMemory-MacOS-1.9.0-4\)

Increment the build number for each RC.

Sanity Checks

Minimal tests on each platform include:

• Installing from the .msi installer
• Verifying that all of the Start Menu links work properly
• Verifying that Dr. Memory is added to the user's path
• Dragging calc.exe onto the Dr. Memory desktop icon (on Win10, drag notepad instead as calc is launched via service)
• Installing from the zip file
• Running something like tests/free.exe from the cygwin and cmd command line
• Ensure installer set up as a Visual Studio External Tool. Try running on a sample project that contains bugs. Try to test this with as many versions of Visual Studio ({2005, 2008, 2010, 2012, 2013} x {Professional, Express}) as possible.
• Run drstrace: drstrace -- calc and look at the log file
• Run symquery: symquery -e free.exe -s main

Tag and Post

Tag the release point:

git tag release_1.9.0 09e3d62
git push origin --tags

Then make a new release on github at https://github.com/DynamoRIO/drmemory/releases. Point at the precise changelist version in the online source viewer (look at prior releases for examples).

Update Downloads.wiki.

Then commit to the top-level CMakeLists.txt (yes, after the tag) to update the line that sets VERSION_NUMBER_DEFAULT, potentially the lines that set DynamoRIO_VERSION_REQUIRED and DRMF_VERSION_DEFAULT, and the release changelist.

Update Documentation

Update the online docs, though only I have access to drmemory.org currently.