### Install License File

Source: https://github.com/dynamorio/drmemory/blob/master/CMakeLists.txt

Installs the license.txt file to the installation prefix.

```cmake
install(FILES
  ${CMAKE_CURRENT_SOURCE_DIR}/license.txt
  DESTINATION "${INSTALL_PREFIX}.")
```

--------------------------------

### Install Documentation Directories

Source: https://github.com/dynamorio/drmemory/blob/master/docs/CMakeLists.txt

Installs documentation directories to the specified installation prefix. This includes HTML files generated during the build process.

```cmake
install(DIRECTORY
  ${CMAKE_CURRENT_BINARY_DIR}/html
  DESTINATION "${INSTALL_PREFIX}${toolname}/docs"
  )
```

```cmake
install(DIRECTORY
  ${CMAKE_CURRENT_BINARY_DIR}/embed/html
  DESTINATION "${INSTALL_PREFIX}${toolname}/docs_embed"
  )
```

--------------------------------

### Define Installation Paths for Samples

Source: https://github.com/dynamorio/drmemory/blob/master/framework/samples/CMakeLists.txt

Sets the installation directories for samples based on the architecture (64-bit or 32-bit) and the installation prefix.

```cmake
set(INSTALL_SAMPLES ${INSTALL_PREFIX}${DRMF_BASEDIR}/samples)
if (X64)
  set(INSTALL_SAMPLES_BIN ${INSTALL_SAMPLES}/bin64)
else (X64)
  set(INSTALL_SAMPLES_BIN ${INSTALL_SAMPLES}/bin32)
endif (X64)
```

--------------------------------

### Install README File

Source: https://github.com/dynamorio/drmemory/blob/master/CMakeLists.txt

Installs the README file to the installation prefix. On Windows, it first converts line endings to CRLF for better compatibility with Notepad.

```cmake
if (WIN32)
  # We want carriage returns for nice viewing in Notepad, etc.:
  file(READ ${CMAKE_CURRENT_SOURCE_DIR}/README readme_content)
  string(REPLACE "\n" "\r\n" readme_content ${readme_content})
  file(WRITE ${CMAKE_CURRENT_BINARY_DIR}/README.txt ${readme_content})
   install(FILES
    ${CMAKE_CURRENT_BINARY_DIR}/README.txt
    DESTINATION "${INSTALL_PREFIX}.")
else (WIN32)
  install(FILES
    ${CMAKE_CURRENT_SOURCE_DIR}/README
    DESTINATION "${INSTALL_PREFIX}.")
endif (WIN32)
```

--------------------------------

### Install CMake Configuration Files

Source: https://github.com/dynamorio/drmemory/blob/master/CMakeLists.txt

Installs the CMake configuration version and main configuration files.

```cmake
install(FILES ${framework_dir}/DrMemoryFrameworkConfigVersion.cmake
  ${framework_dir}/DrMemoryFrameworkConfig.cmake
  DESTINATION ${DRMF_INSTALL})
```

--------------------------------

### Install Framework Header

Source: https://github.com/dynamorio/drmemory/blob/master/CMakeLists.txt

Installs the main framework header file to the specified include directory.

```cmake
install(FILES
  ${framework_incdir}/drmemory_framework.h
  DESTINATION ${DRMF_INSTALL_INC})
```

--------------------------------

### Install strace Sample and Related Files

Source: https://github.com/dynamorio/drmemory/blob/master/framework/samples/CMakeLists.txt

Installs the strace executable, its source file, and the CMakeLists.txt file to their respective sample directories.

```cmake
install(TARGETS strace DESTINATION ${INSTALL_SAMPLES_BIN})
install(FILES strace.c DESTINATION ${INSTALL_SAMPLES})
install(FILES "${CMAKE_CURRENT_BINARY_DIR}/CMakeLists.txt"
  DESTINATION "${INSTALL_SAMPLES}")
```

--------------------------------

### Install 64-bit Support README

Source: https://github.com/dynamorio/drmemory/blob/master/CMakeLists.txt

Writes a README.txt file to the installation directory for 64-bit support, informing users about its current limitations and supported components.

```cmake
if (X64)
  install(CODE "file(WRITE \"${CMAKE_INSTALL_PREFIX}/${INSTALL_BIN}/README.txt\" \"Dr. Memory has preliminary 64-bit support that does not yet include detecting uninitialized reads.  The drstrace tool and the Dr. Syscall and Umbra libraries are fully supported for 64-bit.\n")")
endif (X64)
```

--------------------------------

### Install DynamoRIO License and Acknowledgements

Source: https://github.com/dynamorio/drmemory/blob/master/CMakeLists.txt

Copies the DynamoRIO license and acknowledgements files to the installation directory.

```cmake
install(CODE "configure_file(\"${DR_LICENSE_DIR}/License.txt\" \"${CMAKE_INSTALL_PREFIX}/${DR_install_dir}/License.txt\" COPYONLY)")
```

```cmake
install(CODE "configure_file(\"${DR_LICENSE_DIR}/ACKNOWLEDGEMENTS\" \"${CMAKE_INSTALL_PREFIX}/${DR_install_dir}/ACKNOWLEDGEMENTS\" COPYONLY)")
```

--------------------------------

### Install libunwind (Linux)

Source: https://github.com/dynamorio/drmemory/blob/master/drmemory/docs/using.dox

On Debian/Ubuntu based systems, install the libunwind library using apt.

```bash
sudo apt install libunwind8
```

--------------------------------

### Install Client Target

Source: https://github.com/dynamorio/drmemory/blob/master/CMakeLists.txt

Installs the main client target, placing its runtime, library, and executable components into specified destinations with defined permissions.

```cmake
install(TARGETS ${client_target}
  RUNTIME DESTINATION "${INSTALL_LIB}" # dll
  LIBRARY DESTINATION "${INSTALL_LIB}" # .so
  PERMISSIONS ${owner_access} OWNER_EXECUTE GROUP_READ GROUP_EXECUTE
  WORLD_READ WORLD_EXECUTE)
```

--------------------------------

### Install Tool Target

Source: https://github.com/dynamorio/drmemory/blob/master/CMakeLists.txt

Installs a specified tool target executable to the binary destination with defined permissions.

```cmake
install(TARGETS ${toolname} DESTINATION "${INSTALL_BIN}"
  PERMISSIONS ${owner_access} OWNER_EXECUTE GROUP_READ GROUP_EXECUTE
  WORLD_READ WORLD_EXECUTE)
```

--------------------------------

### Install Exported Targets

Source: https://github.com/dynamorio/drmemory/blob/master/CMakeLists.txt

Installs the exported targets for the framework.

```cmake
install(EXPORT ${exported_targets_name} DESTINATION ${DRMF_INSTALL})
```

--------------------------------

### Install Framework Binaries and Debug Symbols

Source: https://github.com/dynamorio/drmemory/blob/master/CMakeLists.txt

Installs framework binaries, including debug and PDB files, with specific permissions and exclusions.

```cmake
install(DIRECTORY ${framework_bindir}/
  DESTINATION ${DRMF_INSTALL_BIN}
  FILE_PERMISSIONS ${owner_access} OWNER_EXECUTE GROUP_READ GROUP_EXECUTE
  WORLD_READ WORLD_EXECUTE
  FILES_MATCHING
  PATTERN "*.debug"
  PATTERN "*.pdb"
  REGEX ".*.dSYM/.*DWARF/.*" # too painful to get right # of backslash for literal .
  PATTERN "*_int.pdb" EXCLUDE
  )
```

--------------------------------

### Create Installation Directories

Source: https://github.com/dynamorio/drmemory/blob/master/CMakeLists.txt

Ensures the necessary directories for DynamoRIO logs and code cache are created during the installation process.

```cmake
install(CODE "file(MAKE_DIRECTORY \"${CMAKE_INSTALL_PREFIX}/${INSTALL_PREFIX}${toolname}/logs/dynamorio\")")
```

```cmake
install(CODE "file(WRITE \"${CMAKE_INSTALL_PREFIX}/${INSTALL_PREFIX}${toolname}/logs/codecache/README.txt\" \"Default destination for DynamoRIO log files (for diagnostics only).\n\")")
```

--------------------------------

### Split Branch Using Development Script

Source: https://github.com/dynamorio/drmemory/wiki/Workflow

If the development setup script is installed, this command can be used to both split a branch and set its upstream in a single step.

```bash
git split tocheckin 35d4e9c87de22ec9b3a8a110cae2d83821c88ee0
```

--------------------------------

### Configure NSIS Installer Settings

Source: https://github.com/dynamorio/drmemory/blob/master/CMakeLists.txt

Sets up various NSIS installer properties, including the installation directory, registry key, and whether the package is relocatable. It also enables modifying the system PATH.

```cmake
set(CPACK_PACKAGE_INSTALL_DIRECTORY "${toolname_cap_spc}")
set(CPACK_PACKAGE_INSTALL_REGISTRY_KEY "${toolname_cap_spc}")
set(CPACK_PACKAGE_RELOCATABLE "true")
set(CPACK_NSIS_MODIFY_PATH ON)
```

--------------------------------

### Install DynamoRIO README

Source: https://github.com/dynamorio/drmemory/blob/master/CMakeLists.txt

Installs a customized README file for the DynamoRIO component, providing basic information and a link for more details.

```cmake
install(CODE "file(WRITE \"${CMAKE_INSTALL_PREFIX}/${DR_install_dir}/README.txt\" \"This is a copy of the parts of DynamoRIO needed to run ${toolname_cap_spc}.  See http://dynamorio.org for more information.\n\")")
```

--------------------------------

### Install Symquery Target

Source: https://github.com/dynamorio/drmemory/blob/master/CMakeLists.txt

Installs the 'symquery' target executable to the binary destination with specific file permissions.

```cmake
install(TARGETS symquery DESTINATION "${INSTALL_BIN}"
  PERMISSIONS ${owner_access} OWNER_EXECUTE GROUP_READ GROUP_EXECUTE
  WORLD_READ WORLD_EXECUTE)
```

--------------------------------

### Install DynamoRIO Binaries (Unix)

Source: https://github.com/dynamorio/drmemory/blob/master/CMakeLists.txt

Installs DynamoRIO binaries like drrun and nudgeunix on Unix-like systems, with conditional installation for drrun based on USER_SPECIFIED_DynamoRIO_DIR and nudgeunix based on platform.

```cmake
install(CODE "configure_file(\"${DynamoRIO_DIR}/../${BIN_ARCH}/drrun\" \"${CMAKE_INSTALL_PREFIX}/${DR_install_dir}/${BIN_ARCH}/drrun\" COPYONLY)")
```

```cmake
install(CODE "configure_file(\"${DynamoRIO_DIR}/../${BIN_ARCH}/nudgeunix\" \"${CMAKE_INSTALL_PREFIX}/${DR_install_dir}/${BIN_ARCH}/nudgeunix\" COPYONLY)")
```

--------------------------------

### Install Favicon Files

Source: https://github.com/dynamorio/drmemory/blob/master/docs/CMakeLists.txt

Installs favicon files (PNG and ICO) into the documentation's HTML directory. This ensures the website has a custom icon in the browser tab.

```cmake
install(FILES
  ${CMAKE_CURRENT_SOURCE_DIR}/favicon.png
  DESTINATION "${INSTALL_PREFIX}${toolname}/docs/html"
  )
```

```cmake
install(FILES
  ${CMAKE_CURRENT_SOURCE_DIR}/favicon.ico
  DESTINATION "${INSTALL_PREFIX}${toolname}/docs/html"
  )
```

--------------------------------

### Install Binary Directory

Source: https://github.com/dynamorio/drmemory/blob/master/CMakeLists.txt

Installs the binary directory, including debug and PDB files. It sets execute permissions for the owner and read/execute for group and world. Excludes specified PDB files.

```cmake
install(DIRECTORY ${PROJECT_BINARY_DIR}/${BUILD_BIN}/
  DESTINATION "${INSTALL_BIN}"
  FILE_PERMISSIONS ${owner_access} OWNER_EXECUTE
  GROUP_READ GROUP_EXECUTE WORLD_READ WORLD_EXECUTE
  FILES_MATCHING
  PATTERN "*.debug"
  PATTERN "*.pdb"
  REGEX ".*.dSYM/.*DWARF/.*" # too painful to get right # of backslash for literal .
  ${install_pdb_exclude}
  )
```

--------------------------------

### Install Drltrace Configuration File (CMake)

Source: https://github.com/dynamorio/drmemory/blob/master/drltrace/CMakeLists.txt

Installs the generated drltrace configuration file to the binary destination with read permissions.

```cmake
install(FILES ${conf_out} DESTINATION "${INSTALL_BIN}" PERMISSIONS ${owner_access}
        GROUP_READ WORLD_READ)
copy_target_to_device(${conf_out})
```

--------------------------------

### Install Library Directory

Source: https://github.com/dynamorio/drmemory/blob/master/CMakeLists.txt

Installs the library directory, including debug and PDB files. It uses file matching patterns and regular expressions to select files, and excludes specified PDB files.

```cmake
install(DIRECTORY ${CMAKE_LIBRARY_OUTPUT_DIRECTORY}/
  DESTINATION "${INSTALL_LIB}"
  FILE_PERMISSIONS ${owner_access} OWNER_EXECUTE GROUP_READ GROUP_EXECUTE
  WORLD_READ WORLD_EXECUTE
  FILES_MATCHING
  PATTERN "*.debug"
  PATTERN "*.pdb"
  REGEX ".*.dSYM/.*DWARF/.*" # too painful to get right # of backslash for literal .
  ${install_pdb_exclude}
  )
```

--------------------------------

### Example Error Message from Package Build

Source: https://github.com/dynamorio/drmemory/blob/master/drmemory/docs/new_release.dox

This is an example of an error message that might appear during a package build, specifically related to invalid heap arguments when using free.

```text
Error #4: INVALID HEAP ARGUMENT to free 0x00001230
```

--------------------------------

### Example Error Message with Symlink

Source: https://github.com/dynamorio/drmemory/wiki/New-Release

An example of how error messages appear when a symlink is correctly set up, showing the path to the replaced function.

```text
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
```

--------------------------------

### Install DynamoRIO Directories

Source: https://github.com/dynamorio/drmemory/blob/master/CMakeLists.txt

Installs DynamoRIO directories, excluding static libraries and decode libraries, for use by the main package.

```cmake
install(DIRECTORY ${DynamoRIO_DIR}/../${LIB_ARCH}/${build_type}
      DESTINATION ${INSTALL_PREFIX}${DR_install_dir}/${LIB_ARCH}
      FILE_PERMISSIONS ${owner_access} OWNER_EXECUTE GROUP_READ GROUP_EXECUTE
      WORLD_READ WORLD_EXECUTE
      PATTERN "libdrdecode*" EXCLUDE
      # Static DR is large and we do not need it.
      PATTERN "libdynamorio_static*" EXCLUDE)
```

--------------------------------

### Install DynamoRIO Binaries (Windows)

Source: https://github.com/dynamorio/drmemory/blob/master/CMakeLists.txt

Installs specific DynamoRIO executable and DLL files on Windows, conditionally based on the TOOL_DR_HEAPSTAT flag.

```cmake
install(CODE "configure_file(\"${DynamoRIO_DIR}/../${BIN_ARCH}/drconfig.exe\" \"${CMAKE_INSTALL_PREFIX}/${DR_install_dir}/${BIN_ARCH}/drconfig.exe\" COPYONLY)")
```

```cmake
install(CODE "configure_file(\"${DynamoRIO_DIR}/../${BIN_ARCH}/drinject.exe\" \"${CMAKE_INSTALL_PREFIX}/${DR_install_dir}/${BIN_ARCH}/drinject.exe\" COPYONLY)")
```

```cmake
install(CODE "configure_file(\"${DynamoRIO_DIR}/../${BIN_ARCH}/drrun.exe\" \"${CMAKE_INSTALL_PREFIX}/${DR_install_dir}/${BIN_ARCH}/drrun.exe\" COPYONLY)")
```

```cmake
install(CODE "configure_file(\"${DynamoRIO_DIR}/../${BIN_ARCH}/drconfiglib.dll\" \"${CMAKE_INSTALL_PREFIX}/${DR_install_dir}/${BIN_ARCH}/drconfiglib.dll\" COPYONLY)")
```

--------------------------------

### Install Debug Symbols and Libraries

Source: https://github.com/dynamorio/drmemory/blob/master/framework/samples/CMakeLists.txt

Installs debug symbols (.debug, .pdb, .dSYM) and libraries from the output directory to the samples' binary path, ensuring appropriate file permissions.

```cmake
install(DIRECTORY ${CMAKE_LIBRARY_OUTPUT_DIRECTORY}/
  DESTINATION ${INSTALL_SAMPLES_BIN}
  FILE_PERMISSIONS ${owner_access} OWNER_EXECUTE GROUP_READ GROUP_EXECUTE
  WORLD_READ WORLD_EXECUTE
  FILES_MATCHING
  PATTERN "*.debug"
  PATTERN "*.pdb"
  REGEX ".*.dSYM/.*DWARF/.*"
  )
```

--------------------------------

### Install DynamoRIO DLL for Tools

Source: https://github.com/dynamorio/drmemory/blob/master/CMakeLists.txt

Installs the dynamorio.dll for Windows systems when the tool build is enabled. This ensures that the coverage tools can find the necessary DynamoRIO library.

```cmake
install(CODE "configure_file(\"${DynamoRIO_DIR}/../${LIB_ARCH}/${build_type}/dynamorio.dll\" \"${CMAKE_INSTALL_PREFIX}/${DR_install_dir}/tools/${BIN_ARCH}/dynamorio.dll\" COPYONLY)")
```

--------------------------------

### Example drstrace Output

Source: https://github.com/dynamorio/drmemory/blob/master/drmemory/docs/tools.dox

This is an example of the output generated by drstrace, showing system calls and their arguments/return values. It includes details for NtGdiGetTextFaceW, NtOpenKeyEx, and NtQueryKey.

```text
NtGdiGetTextFaceW
        arg 0: 0x740122ad (type=HANDLE, size=0x4)
        arg 1: 0x20 (type=int, size=0x4)
        arg 2: 0x001fcd10 (type=<struct>*, size=0x4)
        arg 3: 0x0 (type=bool, size=0x4)
    succeeded =>
        arg 2: <NYI> (type=<struct>*, size=0x4)
        retval: 0x9 (type=int, size=0x4)
NtOpenKeyEx
        arg 0: 0x001fcd0c (type=HANDLE*, size=0x4)
        arg 1: 0x109 (type=unsigned int, size=0x4)
        arg 2: len=0x18, root=0x3c, name=150/152 "SOFTWARE\Microsoft\Windows NT\CurrentVersion\LanguagePack\SurrogateFallback", att=0x40, sd=0x00000000, sqos=0x00000000 (type=OBJECT_ATTRIBUTES*, size=0x4)
        arg 3: REG_OPTION_RESERVED or REG_OPTION_NON_VOLATILE (type=named constant, value=0x0, size=0x4)
    succeeded =>
        arg 0: 0x001fcd0c => 0x134 (type=HANDLE*, size=0x4)
        retval: 0x0 (type=NTSTATUS, size=0x4)
NtQueryKey.KeyCachedInformation
        arg 0: 0x134 (type=HANDLE, size=0x4)
        arg 1: 0x4 (type=named constant, size=0x4)
        arg 2: 0x001fcb5c (type=<struct>*, size=0x4)
        arg 3: 0xb0 (type=unsigned int, size=0x4)
        arg 4: 0x001fca34 (type=unsigned int*, size=0x4)
    succeeded =>
        arg 2: _KEY_CACHED_INFORMATION {_LARGE_INTEGER {0x1ca043f05a7a595}, int=0x0, int=0x4, int=0x1a, int=0x1, int=0xc, int=0x18, int=0x22} (type=<struct>*, size=0x4)
        arg 4: 0x001fca34 => 0x28 (type=unsigned int*, size=0x4)
        retval: 0x0 (type=NTSTATUS, size=0x4)
```

--------------------------------

### drltrace output example

Source: https://github.com/dynamorio/drmemory/blob/master/drltrace/drltrace.dox

This is an example of drltrace output, showing library calls, their arguments, and return values. It includes information about the library, function name, and argument details.

```text
~~3584~~ MSVCR110.dll!__getmainargs
    arg 0: 0x000000013f103028
    arg 1: 0x000000013f103030
~~3584~~ MSVCR110.dll!malloc
    arg 0: 0x0000000000000008
    arg 1: 0x00000000004245a0
~~3584~~ KERNEL32.dll!VirtualQuery
    arg 0: 0x0000000000427600
    arg 1: 0x000000000030fe30
~~3584~~ KERNELBASE.dll!VirtualQuery
    arg 0: 0x0000000000427600
    arg 1: 0x000000000030fe30
~~3584~~ MSVCR110.dll!free
    arg 0: 0x0000000000427c70
    arg 1: 0x0000000000000000
~~3584~~ MSVCR110.dll!printf
    arg 0: done (type=char *, size=0x0)
done
~~3584~~ MSVCR110.dll!exit
    arg 0: 0x0000000000000000
    arg 1: 0x000007fef147c5d0

```

--------------------------------

### Create HTML Redirect for Docs

Source: https://github.com/dynamorio/drmemory/blob/master/CMakeLists.txt

Installs an HTML file that redirects to the main DynamoRIO documentation index page.

```cmake
install(CODE "file(WRITE \"${CMAKE_INSTALL_PREFIX}/docs/DrMemory.html\" \"<html>\n<head>\n<meta http-equiv=\"refresh\" content=\"0; URL=../drmemory/drmemory/docs/html/index.html\">\n</head><body></body>\")")
```

--------------------------------

### Install Windows-Specific Targets and DLLs

Source: https://github.com/dynamorio/drmemory/blob/master/CMakeLists.txt

Installs Windows-specific targets like 'winsyms' and essential DLLs (dbghelp.dll, symsrv.dll, drconfiglib.dll, etc.) to both binary and library directories with appropriate permissions.

```cmake
if (WIN32)
  # XXX i#926: remove winsyms once we remove postleaks.pl.
  # Also removed its pdb below via: PATTERN "winsyms.pdb" EXCLUDE
  install(TARGETS winsyms DESTINATION "${INSTALL_BIN}"
    PERMISSIONS ${owner_access} OWNER_EXECUTE GROUP_READ GROUP_EXECUTE
    WORLD_READ WORLD_EXECUTE)
  install(FILES
    ${PROJECT_BINARY_DIR}/${BUILD_BIN}/dbghelp.dll
    ${PROJECT_BINARY_DIR}/${BUILD_BIN}/symsrv.dll
    DESTINATION "${INSTALL_BIN}"
    PERMISSIONS ${owner_access} OWNER_EXECUTE GROUP_READ GROUP_EXECUTE
    WORLD_READ WORLD_EXECUTE)
  install(FILES
    ${PROJECT_BINARY_DIR}/${BUILD_BIN}/symsrv.yes
    DESTINATION "${INSTALL_BIN}")
  install(FILES
    ${PROJECT_BINARY_DIR}/${BUILD_BIN}/dbghelp.dll
    DESTINATION "${INSTALL_LIB}"
    PERMISSIONS ${owner_access} OWNER_EXECUTE GROUP_READ GROUP_EXECUTE
    WORLD_READ WORLD_EXECUTE)
  install(FILES
    ${PROJECT_BINARY_DIR}/${BUILD_BIN}/drconfiglib.dll
    ${PROJECT_BINARY_DIR}/${BUILD_BIN}/drinjectlib.dll
    # frontend now imports from DR (i#885)
    ${PROJECT_BINARY_DIR}/${BUILD_BIN}/dynamorio.dll
    ${PROJECT_BINARY_DIR}/${BUILD_BIN}/drconfig.exe
    DESTINATION "${INSTALL_BIN}"
    PERMISSIONS ${owner_access} OWNER_EXECUTE GROUP_READ GROUP_EXECUTE
    WORLD_READ WORLD_EXECUTE)
  # We want carriage returns for nice viewing in Notepad, etc.:
  file(READ ${CMAKE_CURRENT_SOURCE_DIR}/README readme_content)
  string(REPLACE "\n" "\r\n" readme_content ${readme_content})
  file(WRITE ${CMAKE_CURRENT_BINARY_DIR}/README.txt ${readme_content})
   install(FILES
    ${CMAKE_CURRENT_BINARY_DIR}/README.txt
    DESTINATION "${INSTALL_PREFIX}.")
else (WIN32)
  install(FILES
    ${CMAKE_CURRENT_SOURCE_DIR}/README
    DESTINATION "${INSTALL_PREFIX}.")
endif (WIN32)
```

--------------------------------

### Configure DynamoRIO in Batch Mode (Linux)

Source: https://github.com/dynamorio/drmemory/wiki/How-To-Build

Example of configuring DynamoRIO using CMake command-line arguments for a Debug build on Linux.

```bash
mkdir ../build
cd ../build
cmake -DCMAKE_BUILD_TYPE=Debug ../src
make
```

--------------------------------

### Configure CMake for Dr. Memory Framework

Source: https://github.com/dynamorio/drmemory/blob/master/drfuzz/drfuzz.dox

Example of setting CMake variables to locate the DynamoRIO and Dr. Memory Framework installations. This is necessary for CMake to find the required libraries and headers.

```bash
cmake -G"Ninja" -DDynamoRIO_DIR=c:/path/to/DynamoRIO-Windows-4.1.0-8/cmake -DDrMemoryFramework_DIR=c:/path/to/DrMemory-Windows-1.6.0-2/drmf ../mysrcs/
```

--------------------------------

### Configure NSIS Menu Links

Source: https://github.com/dynamorio/drmemory/blob/master/CMakeLists.txt

Defines the links that will appear in the NSIS installer's Start Menu folder. This includes entries for the main executable, documentation, and the Dr. Memory website.

```cmake
set(CPACK_NSIS_MENU_LINKS
  "bin/" "Explore ${toolname_cap_spc} (drag your app onto ${toolname}.exe)"
  "${toolname}/docs/html/index.html" "${toolname_cap_spc} documentation"
  "http://drmemory.org/" "${toolname_cap_spc} web page")
```

--------------------------------

### Visual Studio External Tool Configuration (VS 2005-2012)

Source: https://github.com/dynamorio/drmemory/blob/master/drmemory/docs/using.dox

Configure Dr. Memory as an external tool in Visual Studio 2005 through 2012. This setup allows running your application under Dr. Memory directly from the IDE. Ensure the path to drmemory.exe is correct for your installation.

```text
Title: Dr. Memory
Command: C:\ Program Files (x86)\Dr. Memory\bin\drmemory.exe
Arguments: -visual_studio -- $(TargetPath)
Initial Directory: $(TargetDir)
```

--------------------------------

### Execute Test Suite on Windows (Verbose)

Source: https://github.com/dynamorio/drmemory/wiki/Test-Suite

Example of running the test suite on Windows with verbose output. Includes setting up environment variables and navigating to the correct directories.

```bash
cd "c:\Program Files (x86)\Microsoft Visual Studio *"
VC\vcvarsall.bat

set DDKROOT=C:/derek/ddk
set FLEXROOT=C:/derek/flex_sdk_4.1

cd \derek\drmemory
git clone https://github.com/DynamoRIO/drmemory.git
cd drmemory
git submodule update --init

cd \derek\drmemory\build_suite

"c:\Program Files (x86)\CMake 2.8\bin\ctest.exe" -V -S c:/derek/drmemory/src/tests/runsuite.cmake
```

--------------------------------

### Install Coverage Helper Tool

Source: https://github.com/dynamorio/drmemory/blob/master/CMakeLists.txt

Installs the drcov2lcov tool, which is part of the -coverage feature. The installation path is determined by whether DynamoRIO was specified by the user.

```cmake
install(CODE "configure_file(\"${DynamoRIO_DIR}/../${covdir}/${BIN_ARCH}/${covhelper}\" \"${CMAKE_INSTALL_PREFIX}/${DR_install_dir}/tools/${BIN_ARCH}/${covhelper}\" COPYONLY)")
```

--------------------------------

### Sample Test Suite Results

Source: https://github.com/dynamorio/drmemory/wiki/Test-Suite

Example output from running the test suite, showing build and test statuses for different configurations. Note that certain errors are expected and can be ignored.

```text
### ============================================

RESULTS

drheapstat-dbg-32: all 19 tests passed
drheapstat-rel-32: build successful; no tests for this build
drmemory-dbg-32: all 23 tests passed
drmemory-rel-32: build successful; no tests for this build
final package: build successful; no tests for this build

Error in read script: /home/bruening/work/build/drmem_suite/src/tests/runsuite.cmake
```

--------------------------------

### Run Development Setup Script

Source: https://github.com/dynamorio/drmemory/wiki/Workflow

Execute this script after cloning to configure author information and aliases necessary for development. It is also used for updating and code reviews.

```bash
make/git/devsetup.sh
```

--------------------------------

### Install DynamoRIO Utilities

Source: https://github.com/dynamorio/drmemory/blob/master/CMakeLists.txt

Installs essential DynamoRIO utilities like drinjectlib, DRcontrol, and DRview. This is typically used for non-UNIX systems or when specific installation paths are required.

```cmake
install(CODE "configure_file(\"${DynamoRIO_DIR}/../${BIN_ARCH}/drinjectlib.dll\" \"${CMAKE_INSTALL_PREFIX}/${DR_install_dir}/${BIN_ARCH}/drinjectlib.dll\" COPYONLY)")
```

```cmake
install(CODE "configure_file(\"${DynamoRIO_DIR}/../${BIN_ARCH}/DRcontrol.exe\" \"${CMAKE_INSTALL_PREFIX}/${DR_install_dir}/${BIN_ARCH}/DRcontrol.exe\" COPYONLY)")
```

```cmake
install(CODE "configure_file(\"${DynamoRIO_DIR}/../${BIN_ARCH}/DRview.exe\" \"${CMAKE_INSTALL_PREFIX}/${DR_install_dir}/${BIN_ARCH}/DRview.exe\" COPYONLY)")
```

--------------------------------

### Create Build Directory and Configure CMake (Windows Cygwin)

Source: https://github.com/dynamorio/drmemory/wiki/How-To-Build

Standard procedure on Windows using Cygwin bash to create an out-of-source build directory and launch CMakeSetup for configuration.

```bash
mkdir build
cd build
CMakeSetup ..
```

--------------------------------

### Change Build Type and Clean

Source: https://github.com/dynamorio/drmemory/blob/master/drmemory/docs/build.dox

Example of changing the build type and performing a clean build. Ensure 'make clean' is run after modifying configuration.

```bash
cmake -DCMAKE_BUILD_TYPE=RelWithDebInfo .
make clean
```

--------------------------------

### Install Annotation Headers (Conditional)

Source: https://github.com/dynamorio/drmemory/blob/master/CMakeLists.txt

Conditionally installs annotation-related header files if DR_ANNOTATIONS_SUPPORTED is enabled.

```cmake
if (DR_ANNOTATIONS_SUPPORTED)
  install(FILES
    ${framework_incdir}/drmemory_annotations.h
    ${framework_incdir}/dr_annotations.h
    ${framework_incdir}/dr_annotations_asm.h
    DESTINATION ${DRMF_INSTALL_INC})
endif ()
```

--------------------------------

### Install Drltrace Executable (CMake)

Source: https://github.com/dynamorio/drmemory/blob/master/drltrace/CMakeLists.txt

Installs the drltrace executable to the specified destination with defined permissions.

```cmake
install(TARGETS drltrace DESTINATION "${INSTALL_BIN}"
  PERMISSIONS ${owner_access} OWNER_EXECUTE GROUP_READ GROUP_EXECUTE
  WORLD_READ WORLD_EXECUTE)
```

--------------------------------

### Running Dr. Memory Test Suite on Windows

Source: https://github.com/dynamorio/drmemory/blob/master/drmemory/docs/test.dox

Example of setting up and running the Dr. Memory test suite on Windows using the command prompt. This includes setting environment variables and executing the test script with verbose output.

```batch
cd "c:\Program Files (x86)\Microsoft Visual Studio *"
VC\vcvarsall.bat

set DDKROOT=C:/derek/ddk
set FLEXROOT=C:/derek/flex_sdk_4.1

cd \derek\drmemory
git clone https://github.com/DynamoRIO/drmemory.git
cd drmemory
make/git/devsetup.sh

cd \derek\drmemory\build_suite

"c:\Program Files (x86)\CMake 2.8\bin\ctest.exe" -V -S c:/derek/drmemory/src/tests/runsuite.cmake
```

--------------------------------

### Android Device Binary Directory Setup

Source: https://github.com/dynamorio/drmemory/blob/master/CMakeLists.txt

Sets up the device binary directory for Android builds, caching the top-level binary directory and constructing the path on the device.

```cmake
set(TOP_BINARY_DIR ${PROJECT_BINARY_DIR})
get_filename_component(builddir ${TOP_BINARY_DIR} NAME)
set(DRM_DEVICE_BINARY_DIR ${DRM_DEVICE_BASEDIR}/${builddir})
```

--------------------------------

### Build DynamoRIO (Windows)

Source: https://github.com/dynamorio/drmemory/blob/master/drmemory/docs/build.dox

After configuration, use 'cmake --build .' to build DynamoRIO on Windows.

```bash
cmake --build .
```

--------------------------------

### Configure CMakeLists.txt for Building Samples

Source: https://github.com/dynamorio/drmemory/blob/master/framework/samples/CMakeLists.txt

Reads the CMakeLists.txt file, removes non-public and non-combined sections based on build flags, and writes the processed content to a new file for configuration.

```cmake
set(PROJECT_BINARY_DIR ${TOP_BINARY_DIR}) # fix Android paths
copy_target_to_device(strace)
copy_and_adjust_drpaths(${CMAKE_RUNTIME_OUTPUT_DIRECTORY} strace)

file(READ "${CMAKE_CURRENT_SOURCE_DIR}/CMakeLists.txt" string)
string(REGEX REPLACE "[^
]*NON-PUBLIC[^
]*\n" "" string "${string}")
if (BUILDING_SUB_PACKAGE)
  string(REGEX REPLACE "[^
]*# NON-COMBINED[^
]*\n" "" string "${string}")
else ()
  string(REGEX REPLACE "# NON-COMBINED" "" string "${string}")
endif ()
string(REGEX REPLACE "# START NON-EXPORTED SECTION.*$" "" string "${string}")
file(WRITE "${CMAKE_CURRENT_BINARY_DIR}/CMakeLists.txt.in" "${string}")
configure_file("${CMAKE_CURRENT_BINARY_DIR}/CMakeLists.txt.in"
  "${CMAKE_CURRENT_BINARY_DIR}/CMakeLists.txt"
  @ONLY)
```

--------------------------------

### Execute Test Suite

Source: https://github.com/dynamorio/drmemory/wiki/Test-Suite

Run the test suite from an empty directory. Creates subdirectories for each build configuration.

```bash
mkdir ../build_suite
cd ../build_suite
ctest -S ../drmemory/tests/runsuite.cmake
```

--------------------------------

### Build DynamoRIO (Windows)

Source: https://github.com/dynamorio/drmemory/wiki/How-To-Build

Command to build DynamoRIO on Windows after configuration. Use '--config' for specific build types like RelWithDebInfo.

```bash
cmake --build .
cmake --build . --config RelWithDebInfo
```

--------------------------------

### Install Android Tool

Source: https://github.com/dynamorio/drmemory/blob/master/CMakeLists.txt

Installs the Dr. Memory tool for Android if the ANDROID and TOOL_DR_MEMORY flags are set. Sets execute permissions.

```cmake
if (ANDROID AND TOOL_DR_MEMORY)
  install(FILES
    "${PROJECT_BINARY_DIR}/${BUILD_BIN}/${toolname}"
    DESTINATION "${INSTALL_BIN}"
    PERMISSIONS ${owner_access} OWNER_EXECUTE GROUP_READ GROUP_EXECUTE
    WORLD_READ WORLD_EXECUTE)
endif ()
```

--------------------------------

### Launching Dr. Heapstat Visualization Tool

Source: https://github.com/dynamorio/drmemory/blob/master/drheapstat/docs/using.dox

Launch the visualization tool with the -visualize option, specifying the application executable path and the directory containing the Dr. Heapstat log files.

```bash
~/DrHeapstat-$(PLATFORM)-$(TOOL_VERSION)-1/$(FRONT_END_PATH) -visualize -x path-to-app-exe -profdir path-to-logdir
```

--------------------------------

### Install Auxiliary Script

Source: https://github.com/dynamorio/drmemory/blob/master/CMakeLists.txt

Installs an auxiliary script if one is defined. Ensures execute permissions are set for owner, group, and world.

```cmake
if (NOT "${script_aux}" STREQUAL "")
  install(FILES
    ${script_aux}
    DESTINATION "${INSTALL_BIN}"
    PERMISSIONS ${owner_access} OWNER_EXECUTE GROUP_READ GROUP_EXECUTE
    WORLD_READ WORLD_EXECUTE)
endif ()
```

--------------------------------

### Create Build Directory and Configure CMake (Linux)

Source: https://github.com/dynamorio/drmemory/wiki/How-To-Build

Standard procedure on Linux to create an out-of-source build directory and launch the CMake GUI for configuration.

```bash
mkdir build
cd build
cmake-gui ..
```

--------------------------------

### Configure Install Prefix

Source: https://github.com/dynamorio/drmemory/blob/master/CMakeLists.txt

Conditionally sets the CMAKE_INSTALL_PREFIX based on an override variable and architecture. This determines the base directory for all installed files.

```cmake
if (install_override)
  if (X64)
    set(EXP_DIR exports64)
  else (X64)
    set(EXP_DIR exports32)
  endif (X64)
  set(CMAKE_INSTALL_PREFIX "${PROJECT_BINARY_DIR}/../${EXP_DIR}"
    CACHE PATH "install path" FORCE)
endif (install_override)
```

--------------------------------

### Instruction-Based Suppression Example

Source: https://github.com/dynamorio/drmemory/blob/master/drmemory/docs/reports.dox

Example of a suppression for an uninitialized read, restricted by a specific instruction pattern. Wildcards can be used in the instruction pattern.

```text
UNINITIALIZED READ
name=bug #123 (deliberate uninitialized read to generate random number)
instruction=test   * $0x00000?00
myranlib.dll!GenRanHelper*
myranlib.dll!GenRan*
```

--------------------------------

### Symquery: Wildcard Symbol Search (Windows)

Source: https://github.com/dynamorio/drmemory/blob/master/drmemory/docs/tools.dox

Example of using symquery with the --searchall option on Windows to find symbols matching a wildcard pattern in a DLL. Note that --searchall is recommended over --search for PDB files.

```bash
% bin/symquery.exe -e c:/windows/syswow64/kernel32.dll -v --searchall -s Heap*
<debug info: type=PDB, has symbols, NO line numbers>
HeapDestroyStub +0x13557-0x13557
HeapUnlockStub +0x9444f-0x9444f
HeapQueryInformationStub +0x9442f-0x9442f
HeapSummary +0xbeb4c-0xbeb4c
HeapSetInformation +0x155fe-0x155fe
HeapLock +0xbeb36-0xbeb36
Heap32ListFirst +0x95651-0x95651
HeapValidateStub +0x2b11b-0x2b11b
HeapWalk +0xbeb62-0xbeb62
HeapCreate +0x149da-0x149da
HeapCompact +0x146c4-0x146c4
Heap32Next +0x9597e-0x9597e
HeapCreateStub +0x149cd-0x149cd
HeapWalkStub +0x9445f-0x9445f
HeapCompactStub +0x146b7-0x146b7
HeapSetInformationStub +0x155f1-0x155f1
HeapFree +0x11499-0x11499
HeapDestroy +0x13564-0x13564
HeapQueryInformation +0xbeb41-0xbeb41
Heap32ListNext +0x956fb-0x956fb
HeapSummaryStub +0x9443f-0x9443f
HeapUnlock +0xbeb57-0xbeb57
HeapLockStub +0x9441f-0x9441f
Heap32First +0x95793-0x95793
HeapValidate +0x2b128-0x2b128
```

--------------------------------

### LEAK Suppression Example

Source: https://github.com/dynamorio/drmemory/blob/master/drmemory/docs/reports.dox

Example of a suppression entry for a memory leak. The 'name=' field provides an identifier for the suppression, useful for tracking.

```text
LEAK
name=bug #456 (deliberately leaked object)
mylib.dll!LeakMe
mylib.dll!*
```

--------------------------------

### Create Redirect HTML for Documentation

Source: https://github.com/dynamorio/drmemory/blob/master/docs/CMakeLists.txt

Creates a directory and a redirect HTML file to provide a more visible access point to the main index.html. This is useful for older browsers or specific access patterns.

```cmake
install(CODE "file(MAKE_DIRECTORY \"\
${CMAKE_INSTALL_PREFIX}/${INSTALL_PREFIX}docs\")")
```

```cmake
install(CODE "file(WRITE \"\
${CMAKE_INSTALL_PREFIX}/${INSTALL_PREFIX}docs/${toolname}.html\" \"<html>\n<head>\n<meta http-equiv=\"refresh\" content=\"0; URL=../${toolname}/docs/html/index.html\">\n</head><body></body>\")")
```

--------------------------------

### DRFuzz Mutator Example with Random Seed

Source: https://github.com/dynamorio/drmemory/blob/master/drfuzz/drfuzz.dox

Example of specifying mutator options, including the random seed for repeating fuzz tests.

```shell
-fuzz_mutator "r|b|r|1|0x17a3cd8648a6ab1f"
```

--------------------------------

### Compile Linux Application with Debug Info

Source: https://github.com/dynamorio/drmemory/blob/master/drmemory/docs/using.dox

Sample command line for compiling a Linux application with recommendations for debugging information and callstack quality.

```bash
gcc -g -O0 -fno-inline -o myapp myapp.c
```

--------------------------------

### Install DynamoRIO Directories in CMake

Source: https://github.com/dynamorio/drmemory/blob/master/CMakeLists.txt

Installs DynamoRIO directories, excluding static libraries for package targets. This is used when DynamoRIO is not explicitly specified by the user.

```cmake
install(DIRECTORY "${DynamoRIO_DIR}/../${LIB_ARCH}"
      DESTINATION "${DR_install_dir}"
      # Static DR is large and we do not need it.
      PATTERN "dynamorio_static*" EXCLUDE)
    # we don't need ext/ at all b/c we use static libs
  else (NOT USER_SPECIFIED_DynamoRIO_DIR)
    # don't take time and space copying: user can pass same dr to frontend,
    # so we only copy for package target
    if (DEBUG_BUILD)
      set(CPACK_INSTALLED_DIRECTORIES
        "${DynamoRIO_DIR}/../${LIB_ARCH};${DR_install_dir}/${LIB_ARCH}"
        "${DynamoRIO_DIR}/../ext/${LIB_ARCH};${DR_install_dir}/ext/${LIB_ARCH}")
    else (DEBUG_BUILD)
      set(CPACK_INSTALLED_DIRECTORIES
        "${DynamoRIO_DIR}/../${LIB_ARCH}/release;${DR_install_dir}/${LIB_ARCH}/release"
        "${DynamoRIO_DIR}/../ext/${LIB_ARCH}/release;${DR_install_dir}/ext/${LIB_ARCH}/release")
    endif (DEBUG_BUILD)
  endif (NOT USER_SPECIFIED_DynamoRIO_DIR)
endif (WIN32 AND NOT BUILDING_SUB_PACKAGE)
```

--------------------------------

### Symquery: Address to Symbol Lookup (Windows)

Source: https://github.com/dynamorio/drmemory/blob/master/drmemory/docs/tools.dox

Demonstrates how to use symquery to convert a module-relative address to its corresponding source file, line number, and offset on Windows. The address must be an offset from the module base.

```bash
% bin/symquery.exe -e tests/free.exe -a 0x1077
d:\checkout\drmemory\git\src\tests\free.c:48+0x7
```

--------------------------------

### Install ARM Cross-Compiler on Linux

Source: https://github.com/dynamorio/drmemory/wiki/How-To-Build

Installs the necessary GCC toolchain for cross-compiling for the ARM 32-bit hard-float ABI (gnueabihf) target on Debian/Ubuntu-based systems.

```bash
$ sudo apt-get install gcc-arm-linux-gnueabihf binutils-arm-linux-gnueabihf g++-arm-linux-gnueabihf
```

--------------------------------

### Build Release Configuration (Windows)

Source: https://github.com/dynamorio/drmemory/blob/master/drmemory/docs/build.dox

To build a release configuration on Windows, use 'cmake --build . --config RelWithDebInfo'.

```bash
cmake --build . --config RelWithDebInfo
```

--------------------------------

### Install Dr. Memory Tool and Suppress File

Source: https://github.com/dynamorio/drmemory/blob/master/CMakeLists.txt

Installs the Dr. Memory tool and its default suppress file. Sets read permissions for the suppress file.

```cmake
if (TOOL_DR_MEMORY)
  install(FILES
    ${PROJECT_BINARY_DIR}/${BUILD_BIN}/suppress-default.txt
    DESTINATION "${INSTALL_BIN}"
    PERMISSIONS ${owner_access} GROUP_READ WORLD_READ)
  if (UNIX)
    install(FILES
      ${PROJECT_BINARY_DIR}/${BUILD_BIN}/valgrind2drmemory.pl
      DESTINATION "${INSTALL_PREFIX}bin"
      PERMISSIONS ${owner_access} OWNER_EXECUTE GROUP_READ GROUP_EXECUTE
      WORLD_READ WORLD_EXECUTE)
  endif (UNIX)
endif (TOOL_DR_MEMORY)
```

--------------------------------

### Assembly Support Setup

Source: https://github.com/dynamorio/drmemory/blob/master/CMakeLists.txt

Configures assembly support by including a support script and setting necessary defines. It ensures debug information is generated and handles platform-specific assembler directives.

```cmake
set(old_debug ${DEBUG})
set(DEBUG ON) # ensure we get debug info
include(${DynamoRIO_DIR}/cpp2asm_support.cmake)
set(DEBUG ${old_debug})
```

--------------------------------

### Set Installation Prefix

Source: https://github.com/dynamorio/drmemory/blob/master/CMakeLists.txt

This snippet defines the installation prefix based on whether a sub-package is being built. If BUILDING_SUB_PACKAGE is true, the prefix is 'drmemory/', otherwise it is an empty string.

```cmake
if (BUILDING_SUB_PACKAGE)
  set(INSTALL_PREFIX "drmemory/")
else ()
  set(INSTALL_PREFIX "")
endif()
```

--------------------------------

### Configure DynamoRIO in Batch Mode (Windows)

Source: https://github.com/dynamorio/drmemory/wiki/How-To-Build

Example of configuring DynamoRIO using CMake command-line arguments for a Debug build with Visual Studio 9 2008.

```bash
mkdir ../build
cd ../build
cmake -G"Visual Studio 9 2008" -DCMAKE_BUILD_TYPE=Debug ../src
cmake --build .
```

--------------------------------

### UNADDRESSABLE ACCESS Suppression Example

Source: https://github.com/dynamorio/drmemory/blob/master/drmemory/docs/reports.dox

Example of a suppression for an unaddressable access error. This format is specific to Windows and allows matching based on the instruction causing the error.

```text
Error #8: UNADDRESSABLE ACCESS beyond heap bounds: reading 0x001338a8-0x001338ac 4 byte(s)
...
Note: instruction: mov    (%eax) -> %eax
```

--------------------------------

### Build with MSBuild and Parallelism

Source: https://github.com/dynamorio/drmemory/wiki/How-To-Build

Use this command to build with MSBuild and enable parallel builds. The /m flag is crucial for parallel execution.

```bash
cmake --build . --target RelWithDebInfo -- /m
```

--------------------------------

### Initialize and Exit drsyscall

Source: https://github.com/dynamorio/drmemory/blob/master/drsyscall/drsyscall.dox

Your client must call drsys_init() before using any drsyscall API routines and drsys_exit() at process exit. These functions handle the setup and cleanup of the extension.

```c++
drsys_init();
// ... your client code ...
drsys_exit();
```

--------------------------------

### Install Visual Studio External Tool

Source: https://github.com/dynamorio/drmemory/blob/master/CMakeLists.txt

Installs the 'vs_external_tool' target to the specified destination with defined permissions. This is part of the integration for Dr. Memory as a Visual Studio External Tool.

```cmake
install(TARGETS vs_external_tool DESTINATION "${INSTALL_BIN}"
  PERMISSIONS ${owner_access}
  OWNER_EXECUTE GROUP_READ GROUP_EXECUTE  WORLD_READ WORLD_EXECUTE)
```