GPA 3.3 release

Author: chesik-amd

.gitignore

@@ -29,6 +29,7 @@ Doc/public
 *.so
 *.a
 *.pyc
+CMakeBuild*/
 
 # Visual Studo 2015 cache/options directory
 .vs/

BUILD.md

@@ -5,102 +5,91 @@
 * [Windows Build Information](#windows-build-information)
 * [Linux Build Information](#linux-build-information)
 * [PublicCounterCompiler Tool](#publiccountercompiler-tool)
-* [Building the Documentation](#building-the-documentation)
 
 ## Cloning/Updating Dependent Repositories
 GPUPerfAPI no longer uses git submodules to reference dependent repositories. Instead, you need to follow these instructions in
 order to clone/update any dependent repositories.
 
 #### Prerequisites
   * Python, which can be installed from https://www.python.org/
+  * CMake 3.5.1 or newer
+    * For Windows, this can be downloaded from https://cmake.org/download/
+    * For Linux, this can be installed using: sudo apt-get install cmake
+  * To build the documentation:
+    * Install Sphinx:
+      * `pip install Sphinx`
+    * Install Sphinx Read The Docs theme:
+      * `pip install sphinx-rtd-theme` (read the docs theme is not installed by default)
+    * Install spelling checker (optional)
+      * `pip install pyenchant`
+      * `pip install sphinxcontrib-spelling`
 
 #### Instructions
- * Simply execute the [UpdateCommon.py](Scripts/UpdateCommon.py) python script located in the [Scripts](Scripts) directory:
-   * `python Scripts/UpdateCommon.py`
+ * Simply execute the [PreBuild.py](PreBuild.py) python script located in the GPA directory:
+   * `python PreBuild.py`
  * This script will clone any dependent repositories that are not present on the system. If any of the dependent repositories are already
 present on the system, this script will instead do a "git pull" on those repositories to ensure that they are up to date. Please re-run
 this script everytime you pull new changes from GPA repository.
+ * NOTE: For GPA 3.3 or newer, if you are updating an existing clone of the GPA repo from an earlier GPA release, you will first need to delete the Common/Lib/Ext/GoogleTest directory. Starting with GPA 3.3, GPA is now using a fork of the official GoogleTest repo. Failure to remove this directory will lead to git errors when running PreBuild.py or UpdateCommon.py.
  * This script will also download and execute the Vulkan™ SDK installer.
    * On Windows, running the installer may require elevation.  If you've previously installed the required Vulkan version, UpdateCommon will simply copy the files form the default installation location into the correct place into the GPUPerfAPI directory tree.
    * UpdateCommon is set up to install the version of the Vulkan SDK which was used during development. If you want to use a newer version of the SDK, the following file will need to be updated:
      * [UpdateCommonMap.py](Scripts/UpdateCommonMap.py)
    * By default the build will expect the Vulkan SDK to be found in a directory pointed to by the `VULKAN_SDK` environment variable. This environment variable is automatically set by the Windows SDK installer, but you may need to set it manually after running the Linux SDK installer. The Linux SDK includes a script called `setup-env.sh` to aid in setting this environment variable:
      * `source ~/VulkanSDK/1.0.68.0/setup-env.sh` (adjust path as necessary)
+ * This script also executes cmake to generate all required files to build GPA.
+ * If you want to generate all cmake build files without trying to clone/pull dependent repos, you can add "--nofetch" to the PreBuild.py command line.
+ * Additional switches that can be used with the PreBuild.py script:
+   * `--vs=[2015,2017]`: Specify the Visual Studio version for which to generate projects. Default is 2017.
+    * `--config=[debug,release]`: Specify the config for which to generate makefiles. Default is both. A specific config can only be specified on Linux. On Windows, both configs are always supported by the generated VS solution and project files.
+   * `--platform=[x86,x64]`: Specify the platform for which to generate build files. Default is both.
+   * `--clean`: Deletes CMakeBuild directory and regenerates all build files from scratch
+   * `--internal`: Generates build files to build the internal version of GPA
+   * `--skipdx11`: Does not generate build files for DX11 version of GPA (Windows only)
+   * `--skipdx12`: Does not generate build files for DX12 version of GPA (Windows only)
+   * `--skipvulkan`: Does not generate build files for Vulkan version of GPA
+   * `--skipopengl`: Does not generate build files for OpenGL version of GPA
+   * `--skipopencl`: Does not generate build files for OpenCL version of GPA
+   * `--skiprocm`: Does not generate build files for ROCm version of GPA (Linux only)
+   * `--skiptests`: Does not generate build files for unit tests
+   * `--skipdocs`: Does not generate build files for documentation
+   * `--cmakecmd="CMD"`: Override the "cmake" command with "CMD"
 
 ## Windows Build Information
 
 ##### Prerequisites
- * Microsoft Visual Studio 2015 Community Edition or higher + Update 3 or Microsoft Visual Studio 2017
+ * Microsoft Visual Studio 2017
  * Windows 10 SDK Version 10.0.10586.0 from https://developer.microsoft.com/en-US/windows/downloads/windows-10-sdk
    * You can override the version of the Windows 10 SDK used by modifying Common/Lib/Ext/Windows-Kits/Global-WindowsSDK.props
  * Microsoft .NET 4.6.2 SDK from https://www.microsoft.com/en-us/download/details.aspx?id=53321
 
 ##### Build Instructions
- * Load Build\VS2015\GPUPerfAPI.sln into Visual Studio 2015
-   * If you are using VS2017, you should load Build\VS2017\GPUPerfAPI.sln instead
- * Build the 64-bit and/or 32-bit configuration
- * After a successful build, the GPUPerfAPI binaries can be found in `GPA\Output\$(Configuration)\bin` (for example GPA\Output\Release\bin)
+ * Load CMakeBuild\x64\GPUPerfAPI.sln into Visual Studio to build the 64-bit version of GPA
+ * Load CMakeBuild\x86\GPUPerfAPI.sln into Visual Studio to build the 32-bit version of GPA
+ * After a successful build, the GPUPerfAPI binaries can be found in `GPA\Output\$(Configuration)` (for example GPA\Output\Release)
 
 #### Additional Information
- * The Visual Studio solution includes a Documentation project that allows you to generate the HTML-based source code documentation using Doxygen. In order
-   to build that project, you'll need to modify [Build/VS2015/Documentation.vcxproj](Build/VS2015/Documentation.vcxproj) or [Build/VS2017/Documentation.vcxproj](Build/VS2017/Documentation.vcxproj)
-   to update the paths to the doxygen executable.
  * The Windows projects each include a .rc file that embeds the VERSIONINFO resource into the final binary. Internally within AMD, a Jenkins build system will dynamically update
    the build number. The version and build numbers can be manually updated by modifying the [GPAVersion.h](Src/GPUPerfAPI-Common/GPAVersion.h) file.
- * Information on building the Internal version:
-    * To generate the internal version, two environment variables are required to be set prior to building in Visual Studio:
-      * AMDT_BUILD=AMDT_INTERNAL
-      * AMDT_BUILD_SUFFIX=-Internal
-    * Each binary filename will have a "-Internal" suffix (for example GPUPerfAPIDX11-x64-Internal.dll)
+ * When building the internal version (using the --internal switch when calling PreBuild.py), each binary filename will have a "-Internal" suffix (for example GPUPerfAPIDX11-x64-Internal.dll)
 
 ## Linux Build Information
 
 ##### Prerequisites
  * Install the Mesa common development package: sudo apt-get install mesa-common-dev
  * For 32-bit builds, install the multilib packages: sudo apt-get install gcc-multilib g++-multilib
+ * In order to build the ROCm/HSA version of GPA, you will need all or part of the ROCm stack installed
+   * Follow the ROCm installation instructions to install either rocm-dkms or rocm-dev: https://rocm.github.io/ROCmInstall.html
+     * In addition, please make sure that the optional ROCm package "rocprofiler-dev" is installed:
+       * Ubuntu: sudo apt install rocprofiler-dev
+       * CentOS: sudo yum install rocprofiler-dev
 
 ##### Build Instructions
- * cd into the Build/Linux directory
- * Execute `./build.sh`
-   * By default this performs a from-scratch build of the release versions of GPUPerfAPI, both 32-bit and 64-bit binaries.
- * The following arguments can be passed to build.sh to alter the build:
-   * `debug`: performs a debug build
-   * `skip32bitbuild`: skips building the 32-bit binaries
-   * `skipopengl`: skips building the OpenGL version of GPUPerfAPI
-   * `skipopencl`: skips building the OpenCL version of GPUPerfAPI
-   * `skiphsa`: skips building the ROCm/HSA version of GPUPerfAPI
-   * `skipvulkan`: skips building the Vulkan version of GPUPerfAPI
-   * `doc`: builds the documentation
-   * `quick` or `incremental`: performs an incremental build (as opposed to a from-scratch build)
-   * `buildinternal`: builds the internal versions of GPUPerfAPI
-   * `hsadir`: overrides the location of the ROCm/HSA header files (by default they are expected to be in /opt/rocm/hsa)
-   * `gtestlibdir`: overrides the location of the GoogleTest libraries (by default they are expected to be in Common/Lib/Ext/GoogleTest/1-7/lib/gcc5/x64. There is also a gcc4.x-compatible version in Common/Lib/Ext/GoogleTest/1-7/lib/x64 for use when building on a system with gcc 4.x)
-   * `gtestlibdir32`: overrides the location of the 32-bit GoogleTest libraries (by default they are expected to be in Common/Lib/Ext/GoogleTest/1-7/lib/gcc5/x86. There is also a gcc4.x-compatible version in Common/Lib/Ext/GoogleTest/1-7/lib/x86 for use when building on a system with gcc 4.x)
-   * `vksdkdir`: overrides the location of the Vulkan SDK. If not specified, the build will use a `VULKAN_SDK` environment variable to determine where to look for the Vulkan SDK.
- * After a successful build, the GPUPerfAPI binaries can be found in Output/bin.
- * Example build command line (builds the debug versions of the binaries, skipping the HSA library):
-   * ./build.sh debug skiphsa
- * In addition to using the build.sh build script to build all of GPUPerfAPI, you can also build a single API library by executing `make` in that library's directory. This is useful when making localized changes in a single version of GPUPerfAPI. When using `make`, the following default targets are supported:
-   * `\<default\>`: makes the 64-bit release version
-   * `x86`: makes the 32-bit release version
-   * `Dbg`: makes the 64-bit debug version
-   * `Dbgx86`: makes the 32-bit debug version
-   * `Internal`: makes the 64-bit release Internal version
-   * `Internalx86`: makes the 32-bit release Internal version
-   * `DbgInternal`: makes the 64-bit debug Internal version
-   * `DbgInternalx86`: makes the 32-bit debug Internal version
- * `Make` is supported in the following directories (those marked with (*) are required to be built before the others, as they produce static libraries used by the others):
-   * DeviceInfo (*)
-   * GPUPerfAPI (*)
-   * GPUPerfAPI-Common (*)
-   * GPUPerfAPICounterGenerator (*)
-   * GPUPerfAPICounters
-   * GPUPerfAPICL
-   * GPUPerfAPIGL
-   * GPUPerfAPIHSA
-   * GPUPerfAPIVk
- * When using `make` to build the ROCM/HSA version of GPUPerfAPI, by default the HSA headers are expected to be in /opt/rocm/hsa. You can override this by specifying "HSA_DIR=<dir>" on the make command line:
-   * Example: make Dbg HSA_DIR=/home/user/hsa_dir
+ * Execute "make" in the CMakeBuild/x64/debug to build the 64-bit debug version of GPA
+ * Execute "make" in the CMakeBuild/x64/release to build the 64-bit release version of GPA
+ * Execute "make" in the CMakeBuild/x86/debug to build the 32-bit debug version of GPA
+ * Execute "make" in the CMakeBuild/x86/release to build the 32-bit release version of GPA
+ * After a successful build, the GPUPerfAPI binaries can be found in `GPA/Output/$(Configuration)` (for example GPA/Output/release)
  * When building the internal version, each binary filename will also have a "-Internal" suffix (for example libGPUPerfAPIGL-Internal.so)
 
 ## PublicCounterCompiler Tool
@@ -136,22 +125,3 @@ Counter formulas are expressed in a Reverse Polish Notation and are made up the
 * hardware params: The supported hardware params are "num_shader_engines". "num_simds", "su_clock_prim", "num_prim_pipes", and "TS_FREQ"
 
 For more details, see the "EvaluateExpression" function in the [GPAPublicCounters.cpp](Src/GPUPerfAPICounterGenerator/GPAPublicCounters.cpp) file.
-
-## Building the Documentation
-
-##### Prerequisites
- * A working python installation is required
- * Install Sphinx:
-   * `pip install Sphinx`
- * Install Sphinx Read The Docs theme:
-   * `pip install sphinx-rtd-theme` (read the docs theme is not installed by default)
- * Install spelling checker (optional)
-  * `pip install pyenchant`
-  * `pip install sphinxcontrib-spelling`
-
-##### Building
- * Once you have Sphinx installed, simply run the following command from the "docs" subdirectory:
-   * `make html`
- * To run the spelling checker:
-   * edit conf.py and uncomment the line adding in the `sphinxcontrib.spelling` extension
-   * `make spelling`