Add source code for RMV 1.2 release.

Author: ahosier

CMakeLists.txt

@@ -39,6 +39,9 @@ IF(WIN32)
     # this warning is caused by the QT header files - use pragma to disable at source
     # disable warning C4127: conditional expression is constant
     add_compile_options(/wd4127)
+    # this warning is caused by QT header files and has been introduced by VS2019 16.9.6
+    # disable warning C5240: 'nodiscard': attribute is ignored in this syntactic position
+    add_compile_options(/wd5240)
     # bump the stack size
     add_link_options(/STACK:16777216)
 ELSEIF(UNIX)
@@ -101,17 +104,64 @@ IF(WIN32)
     set_property(DIRECTORY ${CMAKE_CURRENT_SOURCE_DIR} PROPERTY VS_STARTUP_PROJECT RadeonMemoryVisualizer)
 ENDIF(WIN32)
 
-## Copy Documentation and Samples to output directory
-add_custom_target(Documentation ALL)
+## Copy Documentation and Samples to output directory. Note - this target is intentionally not included in
+## the default project build. It needs to be explicitly built as a separate project
+
+# Determine where the build process will be placing the binary files
+# This is evaluated at project build time - not at CMake generation time
+set(BUILD_ROOT $<$<CONFIG:debug>:${CMAKE_RUNTIME_OUTPUT_DIRECTORY_DEBUG}>$<$<CONFIG:release>:${CMAKE_RUNTIME_OUTPUT_DIRECTORY_RELEASE}>)
+
+# Define the option to pass to the sphinx documentation job
+set(SPHINX_OPTION public)
+
+find_program(SPHINX_EXECUTABLE sphinx-build)
+if(NOT SPHINX_EXECUTABLE)
+  message(FATAL_ERROR "SPHINX_EXECUTABLE (sphinx-build) is not found!")
+endif()
+
+# group sphinx source files into a sphinx folder
+file(GLOB SPHINX_DOC_FILES ${SPHINX_DOC_FILES} ${CMAKE_SOURCE_DIR}/documentation/source/*.rst)
+set (SPHINX_DOC_MAIN ${CMAKE_SOURCE_DIR}/documentation/source/conf.py)
+source_group("sphinx" FILES ${SPHINX_DOC_FILES} ${SPHINX_DOC_MAIN})
+
+# group release documents into a release_docs folder
+set (RELEASE_DOCS_IN_ROOT
+     ${CMAKE_SOURCE_DIR}/README.md
+     ${CMAKE_SOURCE_DIR}/Release_Notes.txt
+     ${CMAKE_SOURCE_DIR}/NOTICES.txt
+     ${CMAKE_SOURCE_DIR}/License.txt
+)
+set (RELEASE_DOCS ${RELEASE_DOCS_IN_ROOT})
+source_group("release_docs" FILES ${RELEASE_DOCS})
+
+# hang the sphinx build on the conf.py file and specify a dummy output ("sphinx_output")
+# this ensures the sphinx docs are built everytime you ask to build the Documentation target
+# Sphinx has proper dependency checking, so this works as expected.
+# Once built, clean up any unneeded files.
+add_custom_target(Documentation SOURCES ${SPHINX_DOC_FILES} ${RELEASE_DOCS} DEPENDS sphinx_output)
+add_custom_command(MAIN_DEPENDENCY ${SPHINX_DOC_MAIN} OUTPUT sphinx_output
+    COMMAND ${CMAKE_COMMAND} -E echo "building Sphinx documentation"
+    COMMAND ${SPHINX_EXECUTABLE} ${CMAKE_SOURCE_DIR}/documentation/source ${BUILD_ROOT}/docs/help/rmv/html/. -t ${SPHINX_OPTION}
+    COMMAND ${CMAKE_COMMAND} -E remove_directory ${BUILD_ROOT}/docs/help/rmv/html/.doctrees
+    COMMAND ${CMAKE_COMMAND} -E remove ${BUILD_ROOT}/docs/help/rmv/html/allocation_explorer.html
+    COMMAND ${CMAKE_COMMAND} -E remove ${BUILD_ROOT}/docs/help/rmv/html/allocation_overview.html
+    COMMAND ${CMAKE_COMMAND} -E remove ${BUILD_ROOT}/docs/help/rmv/html/capture.html
+    COMMAND ${CMAKE_COMMAND} -E remove ${BUILD_ROOT}/docs/help/rmv/html/carousel.html
+    COMMAND ${CMAKE_COMMAND} -E remove ${BUILD_ROOT}/docs/help/rmv/html/heap_overview.html
+    COMMAND ${CMAKE_COMMAND} -E remove ${BUILD_ROOT}/docs/help/rmv/html/memory_leak_finder.html
+    COMMAND ${CMAKE_COMMAND} -E remove ${BUILD_ROOT}/docs/help/rmv/html/resource_details.html
+    COMMAND ${CMAKE_COMMAND} -E remove ${BUILD_ROOT}/docs/help/rmv/html/resource_list.html
+    COMMAND ${CMAKE_COMMAND} -E remove ${BUILD_ROOT}/docs/help/rmv/html/resource_overview.html
+    COMMAND ${CMAKE_COMMAND} -E remove ${BUILD_ROOT}/docs/help/rmv/html/settings.html
+    COMMAND ${CMAKE_COMMAND} -E remove ${BUILD_ROOT}/docs/help/rmv/html/snapshot_delta.html
+    COMMAND ${CMAKE_COMMAND} -E remove ${BUILD_ROOT}/docs/help/rmv/html/timeline.html
+)
+
 add_custom_command(TARGET Documentation POST_BUILD
-    COMMAND ${CMAKE_COMMAND} -E echo "copying documentation to output directory"
-    COMMAND ${CMAKE_COMMAND} -E make_directory $<TARGET_FILE_DIR:RadeonMemoryVisualizer>/docs
-    COMMAND ${CMAKE_COMMAND} -E copy_if_different ${CMAKE_SOURCE_DIR}/documentation/License.htm     $<TARGET_FILE_DIR:RadeonMemoryVisualizer>/docs/.
-    COMMAND ${CMAKE_COMMAND} -E copy_if_different ${CMAKE_SOURCE_DIR}/README.md                     $<TARGET_FILE_DIR:RadeonMemoryVisualizer>/.
-    COMMAND ${CMAKE_COMMAND} -E copy_if_different ${CMAKE_SOURCE_DIR}/Release_Notes.txt             $<TARGET_FILE_DIR:RadeonMemoryVisualizer>/.
-    COMMAND ${CMAKE_COMMAND} -E copy_if_different ${CMAKE_SOURCE_DIR}/NOTICES.txt                   $<TARGET_FILE_DIR:RadeonMemoryVisualizer>/.
-    COMMAND ${CMAKE_COMMAND} -E copy_if_different ${CMAKE_SOURCE_DIR}/License.txt                   $<TARGET_FILE_DIR:RadeonMemoryVisualizer>/.
-    COMMAND ${CMAKE_COMMAND} -E echo "copying samples to output directory"
-    COMMAND ${CMAKE_COMMAND} -E make_directory $<TARGET_FILE_DIR:RadeonMemoryVisualizer>/samples
-    COMMAND ${CMAKE_COMMAND} -E copy_if_different ${CMAKE_SOURCE_DIR}/samples/sampleTrace.rmv       $<TARGET_FILE_DIR:RadeonMemoryVisualizer>/samples/.
+    COMMAND ${CMAKE_COMMAND} -E echo "copying Documentation to output directory"
+    COMMAND ${CMAKE_COMMAND} -E make_directory ${BUILD_ROOT}/docs
+    COMMAND ${CMAKE_COMMAND} -E copy_if_different ${RELEASE_DOCS_IN_ROOT}           ${BUILD_ROOT}/.
+    COMMAND ${CMAKE_COMMAND} -E echo "copying Samples to output directory"
+    COMMAND ${CMAKE_COMMAND} -E make_directory ${BUILD_ROOT}/samples
+    COMMAND ${CMAKE_COMMAND} -E copy_if_different ${CMAKE_SOURCE_DIR}/samples/sampleTrace.rmv  ${BUILD_ROOT}/samples/.
 )

README.md

@@ -51,23 +51,30 @@ git clone https://github.com/GPUOpen-Tools/radeon_memory_visualizer.git
 As a preliminary step, make sure that you have the following installed on your system:
 * CMake 3.11 or above.
 * Python 3.7 or above.
-* Qt® 5 or above (5.12.6 is the default and recommended).
-* Visual Studio® 2015 or above (2017 is the default).
+* Qt® 5 or above (5.15.2 is the default and recommended).
+* Visual Studio® 2015 or above (2019 is the default).
 
-Qt should be installed to the default location (C:\Qt\Qt5.12.6). The Qt 5.12.6 install package can be found at https://download.qt.io/archive/qt/5.12/5.12.6/.
-Make sure to select msvc2017 64-bit (under Qt 5.12.6 option) during Qt installation. Note that the expected installation will produce a C:\Qt\Qt5.12.6\5.12.6 folder.
+Qt V5.15.2 can be installed using the Qt online installer available from the Qt 5.15.2 release page here: https://www.qt.io/blog/qt-5.15.2-released
+As an alternative, the Qt 5.12.6 offline installer can be used here: https://download.qt.io/archive/qt/5.12/5.12.6/
+Qt should be installed to the default location (C:\Qt\Qt5.xx.x).
+Be sure to select msvc2017/msvc2019 64-bit during Qt installation, depending on the compiler you decide to use.
 A reboot is required after Qt is installed.
+
 Cmake can be downloaded from (https://cmake.org/download/).
-Python (V3.x) can be downloaded from (https://www.python.org/).
+Python (V3.x) can be downloaded from (https://www.python.org/). To build the documentation from Visual Studio, the Sphinx Python Document Generator is needed.
+This can be installed once Python is installed, as follows:
+* Open a command prompt and navigate to the scripts folder in the python install folder. Then type these 2 commands:
+* pip install -U sphinx
+* pip install sphinx_rtd_theme
 
-Run the python pre_build.py script in the build folder from a command prompt. If no command line options are provided, the defaults will be used (Qt 5.12.6 and Visual Studio 2017)
+Run the python pre_build.py script in the build folder from a command prompt. If no command line options are provided, the defaults will be used (Qt 5.15.2 and Visual Studio 2019)
 
 Some useful options of the pre_build.py script:
-* --vs <Visual Studio version>: generate the solution files for a specific Visual Studio version. For example, to target Visual Studio 2019, add --vs 2019 to the command.
+* --vs <Visual Studio version>: generate the solution files for a specific Visual Studio version. For example, to target Visual Studio 2017, add --vs 2017 to the command.
 * --qt <path>: full path to the folder from where you would like the Qt binaries to be retrieved. By default, CMake would try to auto-detect Qt on the system.
 
-Once the script has finished, in the case of Visual Studio 2017, a sub-folder called 'vs2017' will be created containing the necessary build files.
-Go into the 'vs2017' folder (build/win/vs2017) and double click on the RMV.sln file and build the 64-bit Debug and Release builds.
+Once the script has finished, in the case of Visual Studio 2019, a sub-folder called 'vs2019' will be created containing the necessary build files.
+Go into the 'vs2019' folder (build/win/vs2019) and double click on the RMV.sln file and build the 64-bit Debug and Release builds.
 The Release and Debug builds of RMV will be available in the build/release and build/debug folders.
 
 ## Support ##

build/dependency_map.py

@@ -10,12 +10,12 @@
 
 # To allow for future updates where we may have cloned the project somewhere other than gerrit, store the root of
 # the repo in a variable. In future, we can automatically calculate this based on the git config
-gitRoot = "https://github.com/GPUOpen-Tools/"
+git_root = "https://github.com/GPUOpen-Tools/"
 
 # Define a set of dependencies that exist as separate git projects.
 # each git dependency has a desired directory where it will be cloned - along with a commit to checkout
-gitMapping = {
-    gitRoot + "QtCommon"                : ["../external/qt_common",        "v3.6.0"],
-    gitRoot + "UpdateCheckAPI"          : ["../external/update_check_api", "v2.0.0"],
+git_mapping = {
+    git_root + "QtCommon"                : ["../external/qt_common",        "v3.7.0"],
+    git_root + "UpdateCheckAPI"          : ["../external/update_check_api", "v2.0.1"],
 }
 

build/fetch_dependencies.py

@@ -1,7 +1,7 @@
-#! /usr/bin/python
+#! python3
 # Copyright (c) 2020 Advanced Micro Devices, Inc. All rights reserved.
 #
-# Script to fetch all external git and/or downloable dependencies needed to build the project
+# Script to fetch all external git and/or downloadable dependencies needed to build the project
 #
 #   fetch_dependencies.py (--internal)
 #
@@ -26,82 +26,82 @@
     import urllib
 
 # to allow the script to be run from anywhere - not just the cwd - store the absolute path to the script file
-scriptRoot = os.path.dirname(os.path.realpath(__file__))
+script_root = os.path.dirname(os.path.realpath(__file__))
 
 # also store the basename of the file
-scriptName = os.path.basename(__file__)
+script_name = os.path.basename(__file__)
 
 # Print a message to the console with appropriate pre-amble
-def logPrint(message):
-    print ("\n" + scriptName + ": " + message)
+def log_print(message):
+    print ("\n" + script_name + ": " + message)
     sys.stdout.flush()
 
 # add script root to support import of URL and git maps
-sys.path.append(scriptRoot)
-from dependency_map import gitMapping
+sys.path.append(script_root)
+from dependency_map import git_mapping
 
 # Clone or update a git repo
-def updateGitDependencies(gitMapping, update):
-    for gitRepo in gitMapping:
+def update_git_dependencies(git_mapping, update):
+    for git_repo in git_mapping:
         # add script directory to path
-        tmppath = os.path.join(scriptRoot, gitMapping[gitRepo][0])
+        tmp_path = os.path.join(script_root, git_mapping[git_repo][0])
 
         # clean up path, collapsing any ../ and converting / to \ for Windows
-        path = os.path.normpath(tmppath)
+        path = os.path.normpath(tmp_path)
 
         # required commit
-        reqdCommit = gitMapping[gitRepo][1]
+        reqd_commit = git_mapping[git_repo][1]
 
-        doCheckout = False
+        do_checkout = False
         if not os.path.isdir(path):
             # directory doesn't exist - clone from git
-            logPrint("Directory %s does not exist, using 'git clone' to get latest from %s" % (path, gitRepo))
-            p = subprocess.Popen((["git", "clone", gitRepo ,path]), stderr=subprocess.STDOUT)
+            log_print("Directory %s does not exist, using 'git clone' to get latest from %s" % (path, git_repo))
+            p = subprocess.Popen((["git", "clone", git_repo ,path]), stderr=subprocess.STDOUT)
             p.wait()
             if(p.returncode == 0):
-                doCheckout = True
+                do_checkout = True
             else:
-                logPrint("git clone failed with return code: %d" % p.returncode)
+                log_print("git clone failed with return code: %d" % p.returncode)
                 return False
         elif update == True:
             # directory exists and update requested - get latest from git
-            logPrint("Directory %s exists, using 'git fetch --tags' to get latest from %s" % (path, gitRepo))
+            log_print("Directory %s exists, using 'git fetch --tags' to get latest from %s" % (path, git_repo))
             p = subprocess.Popen((["git", "fetch", "--tags"]), cwd=path, stderr=subprocess.STDOUT)
             p.wait()
             if(p.returncode == 0):
-                doCheckout = True
+                do_checkout = True
             else:
-                logPrint("git fetch failed with return code: %d" % p.returncode)
+                log_print("git fetch failed with return code: %d" % p.returncode)
                 return False
         else:
             # Directory exists and update not requested
-            logPrint("Git Dependency %s found and not updated" % gitRepo)
+            log_print("Git Dependency %s found and not updated" % git_repo)
 
-        if doCheckout == True:
-            logPrint("Checking out required commit: %s" % reqdCommit)
-            p = subprocess.Popen((["git", "checkout", reqdCommit]), cwd=path, stderr=subprocess.STDOUT)
+        if do_checkout == True:
+            log_print("Checking out required commit: %s" % reqd_commit)
+            p = subprocess.Popen((["git", "checkout", reqd_commit]), cwd=path, stderr=subprocess.STDOUT)
             p.wait()
             if(p.returncode != 0):
-                logPrint("git checkout failed with return code: %d" % p.returncode)
+                log_print("git checkout failed with return code: %d" % p.returncode)
                 return False
-            logPrint("Ensuring any branch is on the head using git pull --ff-only origin %s" % reqdCommit)
-            p = subprocess.Popen((["git", "pull", "--ff-only", "origin", reqdCommit]), cwd=path, stderr=subprocess.STDOUT)
+            log_print("Ensuring any branch is on the head using git pull --ff-only origin %s" % reqd_commit)
+            p = subprocess.Popen((["git", "pull", "--ff-only", "origin", reqd_commit]), cwd=path, stderr=subprocess.STDOUT)
             p.wait()
             if(p.returncode != 0):
-                logPrint("git merge failed with return code: %d" % p.returncode)
+                log_print("git merge failed with return code: %d" % p.returncode)
                 return False
 
     return True
 
 # Main body of update functionality
-def doFetchDependencies(update, internal):
+def do_fetch_dependencies(update, internal):
     # Print git version being used
-    gitCmd = ["git", "--version"]
-    gitOutput = subprocess.check_output(gitCmd, stderr=subprocess.STDOUT)
-    logPrint("%s" % gitOutput)
+    git_cmd = ["git", "--version"]
+    git_output = subprocess.check_output(git_cmd, stderr=subprocess.STDOUT)
+    log_print("%s" % git_output)
 
     # Update all git dependencies
-    if updateGitDependencies(gitMapping, update):
+    if update_git_dependencies(git_mapping, update):
         return True
     else:
         return False
@@ -114,4 +114,4 @@ def doFetchDependencies(update, internal):
     parser.add_argument("--internal", action="store_true", help="fetch dependencies required for internal builds of the tool (only used within AMD")
     args = parser.parse_args()
 
-    doFetchDependencies(True, args.internal)
+    do_fetch_dependencies(True, args.internal)