1 <?xml version="1.0" encoding="utf-8"?>
2 <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
3 "http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd"
5 <!ENTITY command_options SYSTEM "command_options.xml">
6 <!ENTITY config_settings SYSTEM "config_settings.xml">
7 <!ENTITY variables SYSTEM "variables.xml">
8 <!ENTITY lua SYSTEM "lua.xml">
13 <email>brenden1@users.sourceforge.net</email>
16 <firstname>Brenden</firstname>
17 <surname>Matthews</surname>
19 <date>2010-10-05</date>
22 <refentrytitle>conky</refentrytitle>
23 <manvolnum>1</manvolnum>
26 <refname>conky</refname>
27 <refpurpose>A system monitor for X originally based on the
28 torsmo code, but more kickass. It just keeps on given'er.
33 <command>conky</command>
35 <replaceable>options</replaceable>
40 <title>Description</title>
41 <para>Conky is a system monitor for X originally based on
42 torsmo. Since its inception, Conky has changed
43 significantly from its predecessor, while maintaining
44 simplicity and configurability. Conky can display just
45 about anything, either on your root desktop or in its own
46 window. Not only does Conky have many built-in objects, it
47 can also display just about any piece of information by
48 using scripts and other external programs.
50 <para>Conky has more than 250 built in objects, including
51 support for a plethora of OS stats (uname, uptime, CPU
52 usage, mem usage, disk usage, "top" like process stats, and
53 network monitoring, just to name a few), built in IMAP and
54 POP3 support, built in support for many popular music
55 players (MPD, XMMS2, BMPx, Audacious), and much much more.
56 Conky can display this info either as text, or using simple
57 progress bars and graph widgets, with different fonts and
60 <para>We are always looking for help, whether its reporting
61 bugs, writing patches, or writing docs. Please use the
62 facilities at SourceForge to make bug reports, feature
63 requests, and submit patches, or stop by #conky on
64 irc.freenode.net if you have questions or want to
66 <para>Thanks for your interest in Conky.
70 <title>Compiling</title>
71 <para>For users compiling from source on a binary distro,
72 make sure you have the X development libraries installed
73 (Unless you provide configure with "--disable-x11"). This
74 should be a package along the lines of "libx11-dev" or
75 "xorg-x11-dev" for X11 libs, and similar "-dev" format for
76 the other libs required (depending on your configure
77 options). You should be able to see which extra packages
78 you need to install by reading errors that you get from
79 './configure'. You can enable/disable stuff by giving
80 options to configure, but be careful with disabling. For
81 example: with --disable-math you won't get errors but
82 logarithmic graphs will be normal graphs and gauges
85 <para>Conky has (for some time) been available in the
86 repositories of most popular distributions. Here are some
87 installation instructions for a few:
89 <para>Gentoo users -- Conky is in Gentoo's Portage...
90 simply use "emerge app-admin/conky" for
93 <para>Debian, etc. users -- Conky should be in your
94 repositories, and can be installed by doing "aptitude
97 <para>Example to compile and run Conky with all optional
98 components (note that some configure options may differ for
105 <option>sh autogen.sh</option>
107 <option># Only required if building from the
114 <option>./configure</option>
116 <option>--prefix=/usr --mandir=/usr/share/man
117 --infodir=/usr/share/info --datadir=/usr/share
118 --sysconfdir=/etc --localstatedir=/var/lib
120 --enable-audacious[=yes|no|legacy]
121 --enable-bmpx --disable-hddtemp --disable-mpd
122 --enable-xmms2 --disable-portmon
123 --disable-network --enable-debug --disable-x11
124 --disable-double-buffer --disable-xdamage
125 --disable-xft</option>
131 <option>make</option>
138 <option>make install</option>
140 <option># Optional</option>
146 <option>src/conky</option>
151 <para>Conky has been tested to be compatible with C99 C,
152 however it has not been tested with anything other than
153 gcc, and is not guaranteed to work with other
159 <title>You Should Know</title>
160 <para>Conky is generally very good on resources. That said,
161 the more you try to make Conky do, the more resources it is
164 <para>An easy way to force Conky to reload your ~/.conkyrc:
165 "killall -SIGUSR1 conky". Saves you the trouble of having
166 to kill and then restart. You can now also do the same with
171 <title>Options</title>
172 <para>Command line options override configurations defined in
178 <title>Configuration Settings</title>
179 <para>Default configuration file location is $HOME/.conkyrc or
180 ${sysconfdir}/conky/conky.conf. On most systems, sysconfdir is
181 /etc, and you can find the sample config file there
182 (/etc/conky/conky.conf).
184 <para>You might want to copy it to $HOME/.conkyrc and then
185 start modifying it. Other configs can be found at
191 <title>Objects/Variables</title>
192 <para>Colours are parsed using XParsecolor(), there might be a
193 list of them: /usr/share/X11/rgb.txt.
194 Colour can be also in
195 #rrggbb format (hex).
198 Some objects may create threads, and sometimes these threads will
199 not be destroyed until Conky terminates. There is no way to
200 destroy or clean up threads while Conky is running. For example,
201 if you use an MPD variable, the MPD thread will keep running until
202 Conky dies. Some threaded objects will use one of the parameters
203 as a 'key', so that you only have 1 relevant thread running (for
204 example, the $curl, $rss and $weather objects launch one thread per
210 <title>Lua API</title>
211 <para>Conky features a Lua Programming API, and also ships with Lua
212 bindings for some useful libraries. Conky defines certain global
213 functions and variables which can be accessed from Lua code running
216 <para>To use Lua Conky, you first need to make sure you have a version of Conky
217 with Lua support enabled (``conky -v'' will report this). Scripts
218 must first be loaded using the lua_load configuration option. You
219 then call functions in Lua via Conky's $lua, $lua_read, and Lua
223 Be careful when creating threaded objects through the Lua API. You
224 could wind up with a whole bunch of threads running if a thread is
225 created with each iteration.
228 At this time, the Lua API should not be considered stable and may
229 change drastically from one release to another as it matures.
232 NOTE: In order to accommodate certain features in the cairo
233 library's API, Conky will export a few additional functions for the
234 creation of certain structures. These are documented below.
239 <title>Examples</title>
243 <varname>conky</varname>
244 <option>-t '${time %D %H:%M}' -o -u 30</option>
246 <listitem>Start Conky in its own window with date
247 and clock as text and 30 sec update
252 <varname>conky</varname>
253 <option>-a top_left -x 5 -y 500 -d</option>
255 <listitem>Start Conky to background at coordinates
260 <varname>conky</varname>
261 <option>-C > ~/.conkyrc</option>
263 <listitem>Do not start Conky, but have it output
264 the builtin default config file to ~/.conkyrc for
265 later customising.</listitem>
275 ${sysconfdir}/conky/conky.conf</filename>
277 <listitem>Default system-wide configuration file.
278 The value of ${sysconfdir} depends on the
279 compile-time options (most likely /etc).</listitem>
283 <filename>~/.conkyrc</filename>
285 <listitem>Default personal configuration
292 <para>Drawing to root or some other desktop window directly
293 doesn't work with all window managers. Especially doesn't
294 work well with Gnome and it has been reported that it
295 doesn't work with KDE either. Nautilus can be disabled from
296 drawing to desktop with program gconf-editor. Uncheck
297 show_desktop in /apps/nautilus/preferences/. There is -w
298 switch in Conky to set some specific window id. You might
299 find xwininfo -tree useful to find the window to draw to.
300 You can also use -o argument which makes Conky to create
301 its own window. If you do try running Conky in its own
302 window, be sure to read up on the own_window_type settings
303 and experiment.</para>
306 <title>See Also</title>
308 <ulink url="http://conky.sourceforge.net/">
309 http://conky.sourceforge.net/</ulink>
312 <ulink url="http://www.sourceforge.net/projects/conky">
313 http://www.sourceforge.net/projects/conky</ulink>
316 <ulink url="http://wiki.conky.be">
317 http://wiki.conky.be</ulink>
319 <para>#conky on irc.freenode.net</para>
322 <title>Copying</title>
323 <para>Copyright (c) 2005-2010 Brenden Matthews, Philip
324 Kovacs, et. al. Any original torsmo code is licensed under
325 the BSD license (see LICENSE.BSD for a copy). All code
326 written since the fork of torsmo is licensed under the GPL
327 (see LICENSE.GPL for a copy), except where noted
328 differently (such as in portmon code, timed thread code,
329 and audacious code which are LGPL, and prss which is an
330 MIT-style license).</para>
333 <title>Authors</title>
334 <para>The Conky dev team (see AUTHORS for a full list of
335 contributors).</para>