New Release
#summary Instructions for releasing a new version of Dr. Memory #labels Phase-Implementation
= 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
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 [https://code.google.com/p/dynamorio/issues/detail?id=815 DR issue 815]).
On Windows, ensure you have NSIS installed with large string support so that the installer will be properly built. Configure status lines will indicate this. See [HowToBuild#Other_Tools the build instructions] for more information.
Finally, build the Windows package with Visual Studio 2008 so that it will run on Windows 2000 (see DR issue 1029). If 2008 is not the latest installed on your machine, pass generator=Visual\ Studio\ 9\ 2008 to package.cmake, or if using Ninja, just be sure to have the 2008 environment variables set up.
= Building Candidate Packages =
Build using package.cmake. On Windows:
{{{ cd ~/drmemory/withwiki svn update cd ~/drmemory/build_package/ compilerVS2008_32 ctest -V -S d:/drmemory_package/package.cmake,drmem_only;build=1;cacheappend=TOOL_VERSION_NUMBER:STRING=1.6.0;use_ninja }}}
On Linux:
{{{ cd /work/drmemory/withwiki svn update cd /work/drmemory/build_package/ ctest -V -S /work/drmemory_package/package.cmake,drmem_only;build=1;cacheappend=TOOL_VERSION_NUMBER:STRING=1.6.0 }}}
Increment the build number for each RC.
= Sanity Checks =
Minimal tests on each platform include:
- Installing from the NSIS installer
- Verifying that all of the Start Menu links work properly
- Dragging calc.exe onto the Dr. Memory desktop icon
- Installing from the zip file
- Running something like tests/free.exe from the cygwin and cmd command line
- Installing as a Visual Studio External Tool and running on a sample project with bugs. Try to test this with as many versions of Visual Studio ({2005, 2008, 2010, 2012} x {Professional, Express}) as possible.
= Upload Packages =
I use googlecode_upload.py rather than manually through a browser.
Include a source package, as some Linux distributions require it when packaging up Dr. Memory for their distros.
For example: {{{ googlecode_upload.py -s "Dr. Memory zip file (for portable/local installation) for Windows" -p drmemory -u -l Featured,Type-Archive,OpSys-Windows /work/drmemory/releases/DrMemory-Windows-1.6.0-2.zip googlecode_upload.py -s "Dr. Memory installer for Windows" -p drmemory -u -l Featured,Type-Installer,OpSys-Windows /work/drmemory/releases/DrMemory-Windows-1.6.0-2.exe googlecode_upload.py -s "Dr. Memory for Linux" -p drmemory -u [email protected] -l Featured,Type-Archive,OpSys-Linux /work/drmemory/releases/DrMemory-Linux-1.6.0-2.tar.gz googlecode_upload.py -s "Dr. Memory source code" -p drmemory -u [email protected] -l Type-Archive,Type-Source /work/drmemory/releases/DrMemory-1.6.0-2-Source.tar.gz }}}
Then I mark the prior releases as no longer "Featured".
Record somewhere which compiler version was used to build the package on Linux.
Update the subversion tag:
{{{ svn copy -r 1538 https://drmemory.googlecode.com/svn/trunk https://drmemory.googlecode.com/svn/tags/release_1.6.0 -m "release of version 1.6.0" }}}
= Update Documentation =
Update the online docs, though only I have access to drmemory.org currently.
