Improve documentation for standalone binary creation (#2446)

* Add cmake based instructions to create standalone binary

* Specify standalone binary extraction path in doc.

* Add documentation to explain how to specify self-extraction path
  when building the standalone binary where contents of the binary
  are extracted during execution

* Pin Nuitka to version 2.6 for consistency in building standalone binary

projects/rocprofiler-compute/CMakeLists.txt

@@ -668,7 +668,7 @@ add_custom_target(
 set(STANDALONEBINARY_EXTRACT_DIR
     "/tmp"
     CACHE PATH
-    "Prefix path for standalone binary extraction"
+    "Absolute path to where the standalone binary will extract its contents"
 )
 
 # Standalone binary creation
@@ -677,7 +677,7 @@ add_custom_target(
     # Change working directory to src
     WORKING_DIRECTORY ${PROJECT_SOURCE_DIR}
     # Install nuitka
-    COMMAND ${Python3_EXECUTABLE} -m pip install nuitka
+    COMMAND ${Python3_EXECUTABLE} -m pip install nuitka==2.6
     # Install patchelf
     COMMAND ${Python3_EXECUTABLE} -m pip install patchelf
     # Check nuitka

projects/rocprofiler-compute/README.md

@@ -66,23 +66,46 @@ For manual testing, you can find the executable at `install/bin/rocprof-compute`
 
 ## Standalone binary
 
+### Create standalone binary using docker container
+
+This method uses the cmake target inside a docker container.
+
 To create a standalone binary, run the following commands:
 * `cd docker`
-* `docker compose -f docker-compose.standalone.yml build`
-* `docker compose -f docker-compose.standalone.yml up --force-recreate -d && docker attach docker-standalone-1`
+* Optionally, provide `--build-arg STANDALONEBINARY_EXTRACT_DIR=/<path>` option in build container command to change the absolute path where standalone binary will extract its contents. This option should be specified after the `build` keyword. Default is `/tmp`.
+* `docker compose -f docker-compose.standalone.yml build` (build container command)
+* `docker compose -f docker-compose.standalone.yml up --force-recreate -d && docker attach docker-standalone-1` (run container and attach to see its output)
+
+### Create standalone binary using cmake target locally without docker
+
+To create a standalone binary, run the following commands:
+* `pip install -r requirements.txt` (install python dependencies)
+* Optionally, provide `-D STANDALONEBINARY_EXTRACT_DIR=/<path>` option in cmake config. command to change the absolute path where standalone binary will extract its contents. Default is `/tmp`.
+* `cmake -B build -S .` (cmake config. command)
+* `cmake --build build --target standalonebinary` (call standalonebinary cmake target)
+
+### Standalone binary creation methodology
+
+To build the binary we follow these steps:
+* Use RHEL 8.10 docker image as the base image (only in docker method)
+* Install python3.9 (only in docker method)
+* Install runtime dependencies (only in docker method)
+* Install dependencies for building standalone binary
+* Call the standalonebinary cmake target which uses Nuitka to build the standalone binary
 
 You should find the rocprof-compute.bin standalone binary inside the `build` folder in the root directory of the project.
 
-To build the binary we follow these steps:
-* Use RHEL 8.10 docker image as the base image
-* Install python3.9
-* Install runtime dependencies
-* Install dependencies for building standalone binary
-* Call the make target which uses Nuitka to build the standalone binary
+### Things to note about standalone binary
 
-NOTE: Since RHEL 8 ships with glibc version 2.28, this standalone binary can only be run on environment with glibc version greater than 2.28.
+* [Nuitka](https://nuitka.net/user-documentation/) is used for compiling the python interpreter, python dependencies and source code into C and then to a executable. The whole process takes about 30 minutes. The self-extracting standalone binary itself is approximately 150 MB in size, however, the total size of the extracted compiled artifacts is approximately 650 MB.
+
+* By default, standalone binary extracts its contents to a directory `rocprof_compute_standalonebinary_<pid>` under `/tmp` parent directory upon execution, however, the parent directory can be configured as explained in standalone binary creation section.
+
+* When using docker method, since RHEL 8 ships with glibc version 2.28, this standalone binary can only be run on environment with glibc version greater than 2.28.
 glibc version can be checked using `ldd --version` command.
 
+* If not using docker, the minimum glibc version is determined by the OS where cmake is run.
+
 To test the standalone binary provide the `--call-binary` option to pytest.
 
 ## How to Cite

projects/rocprofiler-compute/docker/Dockerfile.standalone

@@ -14,14 +14,15 @@ RUN yum install -y python39 python39-devel && \
     python3 get-pip.py
 
 # Should be absolute path to where the standalone binary will extract its contents
-ENV ROCPROF_COMPUTE_BINARY_EXTRACT_DIR=/tmp
+ARG STANDALONEBINARY_EXTRACT_DIR=/tmp
+ENV STANDALONEBINARY_EXTRACT_DIR=${STANDALONEBINARY_EXTRACT_DIR}
 
 CMD ["/bin/bash", "-c", "\
     python3 -m pip install -r requirements.txt \
-    && python3 -m pip install nuitka patchelf \
+    && python3 -m pip install nuitka==2.6 patchelf \
     && git rev-parse HEAD > VERSION.sha \
     && python3 -m nuitka --mode=onefile --no-deployment-flag=self-execution \
-        --product-name=${ROCPROF_COMPUTE_BINARY_EXTRACT_DIR} \
+        --product-name=${STANDALONEBINARY_EXTRACT_DIR} \
         --onefile-tempdir-spec=/{PRODUCT}/rocprof_compute_standalonebinary_{PID} \
         --enable-plugin=no-qt \
         --include-data-files=VERSION*=./ \