Received-SPF: pass (google.com: domain of linux-kernel+bounces-213773-linux.lists.archive=gmail.com@vger.kernel.org designates 139.178.88.99 as permitted sender) client-ip=139.178.88.99;
From: Roman Storozhenko <romeusmeister@gmail.com>
Date: Thu, 13 Jun 2024 19:52:10 +0200
Subject: [PATCH] Improve cpupower utility build process description
Precedence: bulk
MIME-Version: 1.0
Content-Type: text/plain; charset="utf-8"
Content-Transfer-Encoding: 7bit
Message-Id: <20240613-fix-cpupower-doc-v1-1-9dcdee263af1@gmail.com>
To: Thomas Renninger <trenn@suse.com>, Shuah Khan <shuah@kernel.org>, 
 Javier Carrasco <javier.carrasco.cruz@gmail.com>
Cc: linux-pm@vger.kernel.org, linux-kernel@vger.kernel.org, 
 Roman Storozhenko <romeusmeister@gmail.com>

Describe more precisely build and install 'make' processes for the default
and the user defined directories. Show how to run the utility from the
custom installation directory.

Signed-off-by: Roman Storozhenko <romeusmeister@gmail.com>
---
Enhance cpupower build process description with the information on
building and installing the utility to the user defined directories
as well as with the information on the way of running the utility from
the custom defined installation directory.
This description is based on my experiments with building the utility
and each newly described step has been tested.
---
 tools/power/cpupower/README | 133 ++++++++++++++++++++++++++++++++++++++++----
 1 file changed, 123 insertions(+), 10 deletions(-)

diff --git a/tools/power/cpupower/README b/tools/power/cpupower/README
index 1c68f47663b2..ec0d5551ae96 100644
--- a/tools/power/cpupower/README
+++ b/tools/power/cpupower/README
@@ -22,16 +22,129 @@ interfaces [depending on configuration, see below].
 compilation and installation
 ----------------------------
 
-make
-su
-make install
-
-should suffice on most systems. It builds libcpupower to put in
-/usr/lib; cpupower, cpufreq-bench_plot.sh to put in /usr/bin; and
-cpufreq-bench to put in /usr/sbin. If you want to set up the paths
-differently and/or want to configure the package to your specific
-needs, you need to open "Makefile" with an editor of your choice and
-edit the block marked CONFIGURATION.
+There are 2 output directories - one for the build output and another for
+the installation of the build results, that is the utility, library, man pages,
+etc...
+
+default directory
+-----------------
+
+In the case of default directory, build and install process requires no
+additional parameters:
+
+build
+-----
+
+The output directory for the 'make' command is the current directory and its
+subdirs in the kernel tree:
+tools/power/cpupower
+
+$ make
+
+install
+-------
+
+'make install' command puts targets to default system dirs:
+libcpupower to /usr/lib
+cpupower, cpufreq-bench_plot.sh to /usr/bin
+cpufreq-bench to /usr/sbin
+man pages to /usr/man
+
+$ sudo make install
+
+To put it in other words it makes build results available system-wide, enabling
+any user to simply start using it without any additional steps
+
+custom directory
+----------------
+
+There are 2 make's command-line variables 'O' and 'DESTDIR' that setup
+appropriate dirs:
+'O' - build directory
+'DESTDIR' - installation directory. This variable could also be setup in
+the 'CONFIGURATION' block of the "Makefile"
+
+build
+-----
+
+$ make O=<your_custom_build_catalog>
+
+Example:
+$ make O=/home/hedin/prj/cpupower/build
+
+install
+-------
+
+$ make O=<your_custom_build_catalog> DESTDIR=<your_custom_install_catalog>
+
+Example:
+$ make O=/home/hedin/prj/cpupower/build DESTDIR=/home/hedin/prj/cpupower install
+
+Notice that both variables 'O' and 'DESTDIR' have been provided. The reason is
+that the build results are saved in the custom output dir defined by 'O'
+variable. So, this dir is the source for the installation step. If only 'DESTDIR'
+were provided then the 'install' target would assume that the build directory is
+the current one, build everything there and install from the current dir.
+
+
+clean and uninstall (default directory)
+---------------------------------------
+
+'clean' target is intended for cleanup the build catalog from build results
+'uninstall' target is intended for removing installed files from the installation
+catalog
+
+default directory
+-----------------
+
+This case is a straightforward one:
+$ make clean
+$ make uninstall
+
+custom directory
+----------------
+
+Use 'O' command line variable to remove previously built files from the build
+dir:
+
+$ make O=<your_custom_build_catalog> clean
+
+Example:
+$ make O=/home/hedin/prj/cpupower/build clean
+
+Use 'DESTDIR' command line variable to uninstall previously installed files from
+the given dir:
+
+$ make DESTDIR=<your_custom_install_catalog>
+
+Example:
+make DESTDIR=/home/hedin/prj/cpupower uninstall
+
+
+running the tool
+----------------
+
+default directory
+-----------------
+
+$ sudo cpupower
+
+custom directory
+----------------
+
+When it comes to run the utility from the custom build catalog things become a
+little bit complicated as 'just run' approach doesn't work.
+Assuming that the current dir is '<your_custom_install_catalog>/usr', issuing
+the following command:
+
+$ sudo ./bin/cpupower
+will produce the following error output:
+./bin/cpupower: error while loading shared libraries: libcpupower.so.1: cannot
+open shared object file: No such file or directory
+
+The issue is that binary cannot find the 'libcpupower' library. So, we shall
+point to the lib dir:
+sudo LD_LIBRARY_PATH=lib64/ ./bin/cpupower
 
 
 THANKS

---
base-commit: 6906a84c482f098d31486df8dc98cead21cce2d0
change-id: 20240613-fix-cpupower-doc-9f9365d15c16

Best regards,
-- 
Roman Storozhenko <romeusmeister@gmail.com>