Memory Debugger for Windows, Linux, and Mac
Dr. Memory
New Release

Versioning

We use the same versioning scheme as DynamoRIO.

Steps for Publishing a New Release

Sanity Testing

It is a good idea to perform some sanity tests on all platforms beyond what our CI tests to catch issues before a new release. 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

Update the Version and Changelist Changes

Update the following in the code and commit the change:

  • Update VERSION_NUMBER_DEFAULT
  • Potentially update DynamoRIO_VERSION_REQUIRED
  • Potentially update DRMF_VERSION_DEFAULT
  • Update the default version number in ci-package.yml
  • Update the release changelist.

Update download.dox

Make a new list of direct links for the new version.

Create a Pull Request

Create a new Pull Request with the version, changelist, and download changes listed above.

Trigger a Package Build

To create a new build:

  1. Go to the Actions tab for the DynamoRIO/drmemory repository.
  2. Click on "ci-package" on the list of workflows on the left.
  3. Click on "Run workflow" on the right.
  4. Select the branch for your Pull Request.
  5. Fill in the version number. For a test build or periodic build (i.e., not an official new-version-number release), use the current version major.minor and the date-based patchlevel. The patchlevel can be found from CMake's configuration output by running cmake .:
    -- Dr. Memory version number: 2.3.18609

For the build number, start at 0 for any given version number and add 1 for each attempt to produce a successful build. If the build number is 0 it is not appended to the version number.

Wait for the workflow to finish. It should create a new tag, a new Release, upload 4 binary packages to the Release, and update the online documentation.

Verify Package and Documentation Uploads

Double-check that all binary package files were uploaded to the new release on Github.

Merge the Pull Request

Merge the changes into master.

Trigger a Documentation Build

Run the "ci-docs" Action in the same manner as the "ci-package" action above. Double-check that the documentation was pushed to http://drmemory.org.

Update the Release Description

Once the build is finished and posted to https://github.com/DynamoRIO/drmemory/releases, edit the description to list the highlights of the new release. You can use markdown to make a bulleted list.

Add a New Changelist Section

Update the changelist in release.dox: create a new entry for the next release.

Old Instructions for Locally Building Packages

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\drmemory\trunk'

And on Linux:

ln -s /work/drmemory/drmemory/src /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 -VV -S d:/drmemory_package/package.cmake,drmem_only;build=2;cacheappend=TOOL_VERSION_NUMBER:STRING=1.11.0;cacheappend=DRMF_VERSION:STRING=1.0.0;use_ninja;cpackappend=set\(CPACK_PACKAGE_FILE_NAME\ DrMemory-Windows-1.11.0-2\);cacheappend=VERSION_NUMBER:STRING=6.2.0
chmod ugo+rx *.msi

On Linux:

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

ARM eabihf:

cd /work/drmemory/build_package/
ctest -D CMAKE_SYSTEM_PROCESSOR=arm -V -S /work/drmemory_package/package.cmake,drmem_only;32_only;build=2;cacheappend=TOOL_VERSION_NUMBER:STRING=1.11.0;cacheappend=DRMF_VERSION:STRING=1.0.0;cacheappend=CMAKE_TOOLCHAIN_FILE=/work/drmemory/git/src/dynamorio/make/toolchain-arm32.cmake;cpackappend=set\(CPACK_PACKAGE_FILE_NAME\ DrMemory-ARM-Linux-EABIHF-1.11.0-2\);cacheappend=VERSION_NUMBER:STRING=6.2.0

Android:

cd /work/drmemory/build_package/
ctest -D CMAKE_SYSTEM_PROCESSOR=arm -V -S /work/drmemory_package/package.cmake,drmem_only;32_only;build=2;cacheappend=TOOL_VERSION_NUMBER:STRING=1.11.0;cacheappend=DRMF_VERSION:STRING=1.0.0;cacheappend=CMAKE_TOOLCHAIN_FILE=/work/drmemory/git/src/dynamorio/make/toolchain-android-gcc.cmake;cacheappend=ANDROID_TOOLCHAIN=/work/toolchain/android-ndk-21;cpackappend=set\(CPACK_PACKAGE_FILE_NAME\ DrMemory-ARM-Android-EABI-1.11.0-2\);cacheappend=VERSION_NUMBER:STRING=6.2.0

On MacOS:

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

Increment the build number for each RC.

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 download.dox

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.