README
1The cpupower package consists of the following elements:
2
3requirements
4------------
5
6On x86 pciutils is needed at runtime (-lpci).
7For compilation pciutils-devel (pci/pci.h) and a gcc version
8providing cpuid.h is needed.
9For both it's not explicitly checked for (yet).
10
11
12libcpupower
13----------
14
15"libcpupower" is a library which offers a unified access method for userspace
16tools and programs to the cpufreq core and drivers in the Linux kernel. This
17allows for code reduction in userspace tools, a clean implementation of
18the interaction to the cpufreq core, and support for both the sysfs and proc
19interfaces [depending on configuration, see below].
20
21
22compilation and installation
23----------------------------
24
25There are 2 output directories - one for the build output and another for
26the installation of the build results, that is the utility, library,
27man pages, etc...
28
29default directory
30-----------------
31
32In the case of default directory, build and install process requires no
33additional parameters:
34
35build
36-----
37
38$ make
39
40The output directory for the 'make' command is the current directory and
41its subdirs in the kernel tree:
42tools/power/cpupower
43
44install
45-------
46
47$ sudo make install
48
49'make install' command puts targets to default system dirs:
50
51-----------------------------------------------------------------------
52| Installing file | System dir |
53-----------------------------------------------------------------------
54| libcpupower | /usr/lib |
55-----------------------------------------------------------------------
56| cpupower | /usr/bin |
57-----------------------------------------------------------------------
58| cpufreq-bench_plot.sh | /usr/bin |
59-----------------------------------------------------------------------
60| man pages | /usr/man |
61-----------------------------------------------------------------------
62| systemd service | /usr/lib/systemd/system |
63-----------------------------------------------------------------------
64| systemd support script | /usr/libexec |
65-----------------------------------------------------------------------
66
67To put it in other words it makes build results available system-wide,
68enabling any user to simply start using it without any additional steps
69
70custom directory
71----------------
72
73There are 2 make's command-line variables 'O' and 'DESTDIR' that setup
74appropriate dirs:
75'O' - build directory
76'DESTDIR' - installation directory. This variable could also be setup in
77the 'CONFIGURATION' block of the "Makefile"
78
79build
80-----
81
82$ make O=<your_custom_build_catalog>
83
84Example:
85$ make O=/home/hedin/prj/cpupower/build
86
87install
88-------
89
90$ make O=<your_custom_build_catalog> DESTDIR=<your_custom_install_catalog>
91
92Example:
93$ make O=/home/hedin/prj/cpupower/build DESTDIR=/home/hedin/prj/cpupower \
94> install
95
96Notice that both variables 'O' and 'DESTDIR' have been provided. The reason
97is that the build results are saved in the custom output dir defined by 'O'
98variable. So, this dir is the source for the installation step. If only
99'DESTDIR' were provided then the 'install' target would assume that the
100build directory is the current one, build everything there and install
101from the current dir.
102
103The files will be installed to the following dirs:
104
105-----------------------------------------------------------------------
106| Installing file | System dir |
107-----------------------------------------------------------------------
108| libcpupower | ${DESTDIR}/usr/lib |
109-----------------------------------------------------------------------
110| cpupower | ${DESTDIR}/usr/bin |
111-----------------------------------------------------------------------
112| cpufreq-bench_plot.sh | ${DESTDIR}/usr/bin |
113-----------------------------------------------------------------------
114| man pages | ${DESTDIR}/usr/man |
115-----------------------------------------------------------------------
116| systemd service | ${DESTDIR}/usr/lib/systemd/system |
117-----------------------------------------------------------------------
118| systemd support script | ${DESTDIR}/usr/libexec |
119-----------------------------------------------------------------------
120
121If you look at the table for the default 'make' output dirs you will
122notice that the only difference with the non-default case is the
123${DESTDIR} prefix. So, the structure of the output dirs remains the same
124regardles of the root output directory.
125
126
127clean and uninstall
128-------------------
129
130'clean' target is intended for cleanup the build catalog from build results
131'uninstall' target is intended for removing installed files from the
132installation directory
133
134default directory
135-----------------
136
137This case is a straightforward one:
138$ make clean
139$ make uninstall
140
141custom directory
142----------------
143
144Use 'O' command line variable to remove previously built files from the
145build dir:
146$ make O=<your_custom_build_catalog> clean
147
148Example:
149$ make O=/home/hedin/prj/cpupower/build clean
150
151Use 'DESTDIR' command line variable to uninstall previously installed files
152from the given dir:
153$ make DESTDIR=<your_custom_install_catalog>
154
155Example:
156make DESTDIR=/home/hedin/prj/cpupower uninstall
157
158
159running the tool
160----------------
161
162default directory
163-----------------
164
165$ sudo cpupower
166
167custom directory
168----------------
169
170When it comes to run the utility from the custom build catalog things
171become a little bit complicated as 'just run' approach doesn't work.
172Assuming that the current dir is '<your_custom_install_catalog>/usr',
173issuing the following command:
174
175$ sudo ./bin/cpupower
176will produce the following error output:
177./bin/cpupower: error while loading shared libraries: libcpupower.so.1:
178cannot open shared object file: No such file or directory
179
180The issue is that binary cannot find the 'libcpupower' library. So, we
181shall point to the lib dir:
182sudo LD_LIBRARY_PATH=lib64/ ./bin/cpupower
183
184systemd service
185---------------
186
187A systemd service is also provided to run the cpupower utility at boot with
188settings read from a configuration file.
189
190If you want systemd to find the new service after the installation, the service
191unit must have been installed in one of the system unit search path directories
192(such as '/usr/lib/systemd/system/', which is the default location) and (unless
193you are willing to wait for the next reboot) you need to issue the following
194command:
195
196$ sudo systemctl daemon-reload
197
198If you want to enable this systemd service, edit '/etc/cpupower-service.conf'
199(uncommenting at least one of the options, depending on your preferences)
200and then issue the following command:
201
202$ sudo systemctl enable --now cpupower.service
203
204
205THANKS
206------
207Many thanks to Mattia Dongili who wrote the autotoolization and
208libtoolization, the manpages and the italian language file for cpupower;
209to Dave Jones for his feedback and his dump_psb tool; to Bruno Ducrot for his
210powernow-k8-decode and intel_gsic tools as well as the french language file;
211and to various others commenting on the previous (pre-)releases of
212cpupower.
213
214
215 Dominik Brodowski
216