Received-SPF: pass (google.com: domain of linux-kernel+bounces-216037-linux.lists.archive=gmail.com@vger.kernel.org designates 147.75.199.223 as permitted sender) client-ip=147.75.199.223;
Message-ID: <2ac9b1a3-fd42-48fc-b1c8-4c1986536ef9@linuxfoundation.org>
Date: Sat, 15 Jun 2024 17:05:39 -0600
Precedence: bulk
MIME-Version: 1.0
User-Agent: Mozilla Thunderbird
Subject: Re: [PATCH v2] cpupower: Improve cpupower build process description
To: Roman Storozhenko <romeusmeister@gmail.com>,
 Thomas Renninger <trenn@suse.com>, Shuah Khan <shuah@kernel.org>
Cc: Javier Carrasco <javier.carrasco.cruz@gmail.com>,
 linux-pm@vger.kernel.org, linux-kernel@vger.kernel.org,
 Shuah Khan <skhan@linuxfoundation.org>
References: <20240615125617.180521-1-romeusmeister@gmail.com>
Content-Language: en-US
From: Shuah Khan <skhan@linuxfoundation.org>
In-Reply-To: <20240615125617.180521-1-romeusmeister@gmail.com>
Content-Type: text/plain; charset=UTF-8; format=flowed
Content-Transfer-Encoding: 7bit

On 6/15/24 06:56, Roman Storozhenko wrote:
> 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.
> 
> Signed-off-by: Roman Storozhenko <romeusmeister@gmail.com>
> ---
> V1 -> V2:
>   - Improved commit description
>   - Make changed line lenghts 75 chars
>   - Refactored the description
>   - Link v1: https://lore.kernel.org/linux-pm/20240613-fix-cpupower-doc-v1-1-9dcdee263af1@gmail.com/
> ---
>   tools/power/cpupower/README | 160 +++++++++++++++++++++++++++++++++---
>   1 file changed, 150 insertions(+), 10 deletions(-)
> 
> diff --git a/tools/power/cpupower/README b/tools/power/cpupower/README
> index 1c68f47663b2..2678ed81d311 100644
> --- a/tools/power/cpupower/README
> +++ b/tools/power/cpupower/README
> @@ -22,16 +22,156 @@ 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
> +-----
> +
> +$ make
> +
> +The output directory for the 'make' command is the current directory and
> +its subdirs in the kernel tree:
> +tools/power/cpupower
> +
> +install
> +-------
> +
> +$ sudo make install
> +
> +'make install' command puts targets to default system dirs:
> +
> +-----------------------------------------------------------------------
> +| Installing file        |               System dir                   |
> +-----------------------------------------------------------------------
> +| libcpupower            | /usr/lib                                   |
> +-----------------------------------------------------------------------
> +| cpupower               | /usr/bin                                   |
> +-----------------------------------------------------------------------
> +| cpufreq-bench_plot.sh  | /usr/bin                                   |
> +-----------------------------------------------------------------------
> +| man pages              | /usr/man                                   |
> +-----------------------------------------------------------------------
> +
> +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.
> +
> +The files will be installed to the following dirs:
> +
> +-----------------------------------------------------------------------
> +| Installing file        |               System dir                   |
> +-----------------------------------------------------------------------
> +| libcpupower            | ${DESTDIR}/usr/lib                         |
> +-----------------------------------------------------------------------
> +| cpupower               | ${DESTDIR}/usr/bin                         |
> +-----------------------------------------------------------------------
> +| cpufreq-bench_plot.sh  | ${DESTDIR}/usr/bin                         |
> +-----------------------------------------------------------------------
> +| man pages              | ${DESTDIR}/usr/man                         |
> +-----------------------------------------------------------------------
> +
> +If you look at the table for the default 'make' output dirs you will
> +notice that the only difference with the non-default case is the
> +${DESTDIR} prefix. So, the structure of the output dirs remains the same
> +regardles of the root output directory.
> +
> +
> +clean and uninstall
> +-------------------
> +
> +'clean' target is intended for cleanup the build catalog from build results
> +'uninstall' target is intended for removing installed files from the
> +installation directory
> +
> +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

This "THANKS" doesn't belong in the patch.

thanks,
-- Shuah