vcs.maemo.org Git - monky/blob - doc/docs.xml

   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"
   4 [
   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">
   9 ]>
  10 <refentry>
  11         <refentryinfo>
  12                 <address>
  13                         <email>brenden1@users.sourceforge.net</email>
  14                 </address>
  15                 <author>
  16                         <firstname>Brenden</firstname>
  17                         <surname>Matthews</surname>
  18                 </author>
  19                 <date>2010-10-05</date>
  20         </refentryinfo>
  21         <refmeta>
  22                 <refentrytitle>conky</refentrytitle>
  23                 <manvolnum>1</manvolnum>
  24         </refmeta>
  25         <refnamediv>
  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.
  29                         Yeah.</refpurpose>
  30         </refnamediv>
  31         <refsynopsisdiv>
  32                 <cmdsynopsis>
  33                         <command>conky</command>
  34                         <arg>
  35                                 <replaceable>options</replaceable>
  36                         </arg>
  37                 </cmdsynopsis>
  38         </refsynopsisdiv>
  39         <refsect1>
  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.
  49                 </para>
  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
  58                         colours.
  59                 </para>
  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
  65                         contribute.</para>
  66                 <para>Thanks for your interest in Conky.
  67                 </para>
  68         </refsect1>
  69         <refsect1>
  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
  83                         will miss their line.
  84                 </para>
  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:
  88                 </para>
  89                 <para>Gentoo users -- Conky is in Gentoo's Portage...
  90                         simply use "emerge app-admin/conky" for
  91                         installation.
  92                 </para>
  93                 <para>Debian, etc. users -- Conky should be in your
  94                         repositories, and can be installed by doing "aptitude
  95                         install conky".
  96                 </para>
  97                 <para>Example to compile and run Conky with all optional
  98                         components (note that some configure options may differ for
  99                         your system):
 100                 </para>
 101                 <variablelist>
 102                         <varlistentry>
 103                                 <term>
 104                                         <command>
 105                                                 <option>sh autogen.sh</option>
 106                                         </command>
 107                                         <option># Only required if building from the
 108                                                 git repo</option>
 109                                 </term>
 110                         </varlistentry>
 111                         <varlistentry>
 112                                 <term>
 113                                         <command>
 114                                                 <option>./configure</option>
 115                                         </command>
 116                                         <option>--prefix=/usr --mandir=/usr/share/man
 117                                                 --infodir=/usr/share/info --datadir=/usr/share
 118                                                 --sysconfdir=/etc --localstatedir=/var/lib
 119                                                 --disable-own-window
 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>
 126                                 </term>
 127                         </varlistentry>
 128                         <varlistentry>
 129                                 <term>
 130                                         <command>
 131                                                 <option>make</option>
 132                                         </command>
 133                                 </term>
 134                         </varlistentry>
 135                         <varlistentry>
 136                                 <term>
 137                                         <command>
 138                                                 <option>make install</option>
 139                                         </command>
 140                                         <option># Optional</option>
 141                                 </term>
 142                         </varlistentry>
 143                         <varlistentry>
 144                                 <term>
 145                                         <command>
 146                                                 <option>src/conky</option>
 147                                         </command>
 148                                 </term>
 149                         </varlistentry>
 150                 </variablelist>
 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
 154                         compilers.
 155                 </para>
 156                 <para></para>
 157         </refsect1>
 158         <refsect1>
 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
 162                         going to consume.
 163                 </para>
 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
 167                         SIGHUP.
 168                 </para>
 169         </refsect1>
 170         <refsect1>
 171                 <title>Options</title>
 172                 <para>Command line options override configurations defined in
 173                         configuration file.
 174                 </para>
 175                 &command_options;
 176         </refsect1>
 177         <refsect1>
 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).
 183                 </para>
 184                 <para>You might want to copy it to $HOME/.conkyrc and then
 185                         start modifying it. Other configs can be found at
 186                         http://conky.sf.net/
 187                 </para>
 188                 &config_settings;
 189         </refsect1>
 190         <refsect1>
 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).
 196                 </para>
 197                 <para>
 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
 205                         URI).
 206                 </para>
 207                 &variables;
 208         </refsect1>
 209         <refsect1>
 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
 214                         in Conky.
 215                 </para>
 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
 220                         hooks.
 221                 </para>
 222                 <para>
 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.
 226                 </para>
 227                 <para>
 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.
 230                 </para>
 231                 <para>
 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.
 235                 </para>
 236                 &lua;
 237         </refsect1>
 238         <refsect1>
 239                 <title>Examples</title>
 240                 <variablelist>
 241                         <varlistentry>
 242                                 <term>
 243                                         <varname>conky</varname>
 244                                         <option>-t '${time %D %H:%M}' -o -u 30</option>
 245                                 </term>
 246                                 <listitem>Start Conky in its own window with date
 247                                         and clock as text and 30 sec update
 248                                         interval.</listitem>
 249                         </varlistentry>
 250                         <varlistentry>
 251                                 <term>
 252                                         <varname>conky</varname>
 253                                         <option>-a top_left -x 5 -y 500 -d</option>
 254                                 </term>
 255                                 <listitem>Start Conky to background at coordinates
 256                                         (5, 500).</listitem>
 257                         </varlistentry>
 258                         <varlistentry>
 259                                 <term>
 260                                         <varname>conky</varname>
 261                                         <option>-C &gt; ~/.conkyrc</option>
 262                                 </term>
 263                                 <listitem>Do not start Conky, but have it output
 264                                         the builtin default config file to ~/.conkyrc for
 265                                         later customising.</listitem>
 266                         </varlistentry>
 267                 </variablelist>
 268         </refsect1>
 269         <refsect1>
 270                 <title>Files</title>
 271                 <variablelist>
 272                         <varlistentry>
 273                                 <term>
 274                                         <filename>
 275                                                 ${sysconfdir}/conky/conky.conf</filename>
 276                                 </term>
 277                                 <listitem>Default system-wide configuration file.
 278                                         The value of ${sysconfdir} depends on the
 279                                         compile-time options (most likely /etc).</listitem>
 280                         </varlistentry>
 281                         <varlistentry>
 282                                 <term>
 283                                         <filename>~/.conkyrc</filename>
 284                                 </term>
 285                                 <listitem>Default personal configuration
 286                                         file.</listitem>
 287                         </varlistentry>
 288                 </variablelist>
 289         </refsect1>
 290         <refsect1>
 291                 <title>Bugs</title>
 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>
 304         </refsect1>
 305         <refsect1>
 306                 <title>See Also</title>
 307                 <para>
 308                         <ulink url="http://conky.sourceforge.net/">
 309                                 http://conky.sourceforge.net/</ulink>
 310                 </para>
 311                 <para>
 312                         <ulink url="http://www.sourceforge.net/projects/conky">
 313                                 http://www.sourceforge.net/projects/conky</ulink>
 314                 </para>
 315                 <para>
 316                         <ulink url="http://wiki.conky.be">
 317                                 http://wiki.conky.be</ulink>
 318                 </para>
 319                 <para>#conky on irc.freenode.net</para>
 320         </refsect1>
 321         <refsect1>
 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>
 331         </refsect1>
 332         <refsect1>
 333                 <title>Authors</title>
 334                 <para>The Conky dev team (see AUTHORS for a full list of
 335                         contributors).</para>
 336         </refsect1>
 337 </refentry>