debian/rules: activate the new test.
[debian/cpulimit.git] / README
1 README for LimitCPU
2 ==========================
3
4 LimitCPU is a program to throttle the CPU cycles used by other applications.
5 LimitCPU will monitor a process and make sure its CPU usage stays at or
6 below a given percentage. This can be used to make sure your system
7 has plenty of CPU cycles available for other tasks. It can also be used
8 to keep laptops cool in the face of CPU-hungry processes and for limiting
9 virtual machines.
10
11 LimitCPU is the direct child of CPUlimit, a creation of Angelo Marletta,
12 which can be found at http://cpulimit.sourceforge.net.
13
14
15
16
17 Copying, License and Distribution
18 ===================================
19
20 LimitCPU is licensed under the GNU General Public License (version 2).
21 A copy of the license should be included with this program in a
22 file named LICENSE.
23
24 Copyright 2005, Angelo Marletta <marlonx80@hotmail.com>
25 Copyright 2011-2012, Jesse Smith <jessefrgsmith@yahoo.ca>
26
27
28
29
30
31 Where to get LimitCPU
32 ==========================
33
34 The LimitCPU program can be aquired from http://limitcpu.sourceforge.net
35
36
37
38
39 How to compile and install
40 ===========================
41
42 Once you have downloaded a copy of LimitCPU building should be fairly
43 straight forward. First we unpack the source code
44
45 tar zxf cpulimit-1.8.tar.gz
46
47 Then we run the makefile.
48
49 cd cpulimit-1.8
50 make
51
52 This should produce the executable file "cpulimit". If you would like
53 to install the program to make it available system-wide, run
54
55 make install
56
57
58 Later should you wish to remove the program from your system, run
59 the following command from the limitcpu directory
60
61 make deinstall
62
63
64
65 Note on compiling for non-Linux operating systems:
66 LimitCPU can be compiled on FreeBSD and OS X (though at this time
67 LimitCPU has not been tested and may not work properly on OS X).
68 To compile LimitCPU on these platforms, instead of running "make"
69 to build the executable, instead run either
70
71 make freebsd
72 or
73 make osx
74
75 in order to build on FreeBSD or OS X respectively.
76
77
78
79
80
81 Common usage
82 ==========================
83
84 The LimitCPU program is generally used to throttle the CPU usage of
85 one process. This can be done with the following command where
86 12345 is the process ID number of a running program and 25 is the
87 maximum percentage of the CPU we are willing to give that program
88
89 cpulimit -p 12345 -l 25
90
91 The above example will cause LimitCPU to keep an eye on the process
92 with ID number 12345 until the program exits. Should we wish to
93 run LimitCPU in the background we can use
94
95 cpulimit -p 12345 -l 25 -b
96
97 We can also limit running processes based on their name instead of
98 their process ID, as in this example:
99
100 cpulimit --exe /usr/bin/bigexe --limit 50
101
102 The above example will keep an eye on "bigexe" and, if the application
103 quits and another program called "bigexe" is run, LimitCPU will
104 monitor the new process too. Should we wish to only track the first
105 program and then exit, we can use 
106
107 cpulimit --exec /usr/bin/bigexe --limit 50 -z
108
109 The "-z" flag tells LimitCPU to stop running once its target is
110 no longer running itself.
111
112 The following example is useful for scripts where we want
113 to launch a program and then immediately throttle it
114 without knowing its process ID. The "$!" symbol refers to
115 the last program run and the -b flag tells cpulimit to
116 run in the background, returning control to the shell.
117
118 /usr/bin/someapp &
119 cpulimit -p $! -l 25 -b
120
121
122 Note: As of version 1.7 LimitCPU will attempt to guess the
123 number of CPUs available on the machine and limit usage
124 accordingly. For example, machines with dual-cores will
125 be able to run processes with 1-200% limits. In case the
126 automatic detection does not work, users can over-ride the
127 number of CPUs LimitCPU thinks are available using the
128 -c command line flag. For example
129
130 cpulimit -c 2 -p 12345 -l 150
131
132
133 Commands can be launched by LimitCPU by appending the command
134 to the end of of LimitCPU's argument list. For example, the
135 following command will launch Firefox and limit it to 10% CPU
136 usage:
137
138 cpulimit -l 10 firefox
139
140
141
142
143
144 Bugs and Feedback
145 =============================
146
147 Should you have comments, questions, or bugs to report, please send
148 an e-mail to jessefrgsmith@yahoo.ca with the word "LimitCPU" in the
149 subject line.
150