From c5bfb3728973275de0e3e78f5a391cf77625e709 Mon Sep 17 00:00:00 2001 From: vedithal-amd Date: Fri, 9 Jan 2026 17:40:47 -0500 Subject: [PATCH] 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 | 4 +- projects/rocprofiler-compute/README.md | 41 +++++++++++++++---- .../docker/Dockerfile.standalone | 7 ++-- 3 files changed, 38 insertions(+), 14 deletions(-) diff --git a/projects/rocprofiler-compute/CMakeLists.txt b/projects/rocprofiler-compute/CMakeLists.txt index 79acebe9b3..e9daca6786 100644 --- a/projects/rocprofiler-compute/CMakeLists.txt +++ b/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 diff --git a/projects/rocprofiler-compute/README.md b/projects/rocprofiler-compute/README.md index 01f5fb504b..89e3f105b9 100644 --- a/projects/rocprofiler-compute/README.md +++ b/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=/` 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=/` 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_` 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 diff --git a/projects/rocprofiler-compute/docker/Dockerfile.standalone b/projects/rocprofiler-compute/docker/Dockerfile.standalone index 3262cf83ba..c8d709fc9e 100644 --- a/projects/rocprofiler-compute/docker/Dockerfile.standalone +++ b/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*=./ \