321 lines
11 KiB
XML
321 lines
11 KiB
XML
<?xml version="1.0" encoding="utf-8"?>
|
|
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
|
|
"http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd"
|
|
[
|
|
<!ENTITY command_options SYSTEM "command_options.xml">
|
|
<!ENTITY config_settings SYSTEM "config_settings.xml">
|
|
<!ENTITY variables SYSTEM "variables.xml">
|
|
<!ENTITY lua SYSTEM "lua.xml">
|
|
]>
|
|
<refentry>
|
|
<refentryinfo>
|
|
<address>
|
|
<email>brenden1@users.sourceforge.net</email>
|
|
</address>
|
|
<author>
|
|
<firstname>Brenden</firstname>
|
|
<surname>Matthews</surname>
|
|
</author>
|
|
<date>2009-08-01</date>
|
|
</refentryinfo>
|
|
<refmeta>
|
|
<refentrytitle>conky</refentrytitle>
|
|
<manvolnum>1</manvolnum>
|
|
</refmeta>
|
|
<refnamediv>
|
|
<refname>conky</refname>
|
|
<refpurpose>A system monitor for X originally based on the
|
|
torsmo code, but more kickass. It just keeps on given'er.
|
|
Yeah.</refpurpose>
|
|
</refnamediv>
|
|
<refsynopsisdiv>
|
|
<cmdsynopsis>
|
|
<command>conky</command>
|
|
<arg>
|
|
<replaceable>options</replaceable>
|
|
</arg>
|
|
</cmdsynopsis>
|
|
</refsynopsisdiv>
|
|
<refsect1>
|
|
<title>Description</title>
|
|
<para>Conky is a system monitor for X originally based on
|
|
torsmo. Since its inception, Conky has changed
|
|
significantly from its predecessor, while maintaining
|
|
simplicity and configurability. Conky can display just
|
|
about anything, either on your root desktop or in its own
|
|
window. Not only does Conky have many built-in objects, it
|
|
can also display just about any piece of information by
|
|
using scripts and other external programs.
|
|
</para>
|
|
<para>Conky has more than 250 built in objects, including
|
|
support for a plethora of OS stats (uname, uptime, CPU
|
|
usage, mem usage, disk usage, "top" like process stats, and
|
|
network monitoring, just to name a few), built in IMAP and
|
|
POP3 support, built in support for many popular music
|
|
players (MPD, XMMS2, BMPx, Audacious), and much much more.
|
|
Conky can display this info either as text, or using simple
|
|
progress bars and graph widgets, with different fonts and
|
|
colours.
|
|
</para>
|
|
<para>We are always looking for help, whether its reporting
|
|
bugs, writing patches, or writing docs. Please use the
|
|
facilities at SourceForge to make bug reports, feature
|
|
requests, and submit patches, or stop by #conky on
|
|
irc.freenode.net if you have questions or want to
|
|
contribute.</para>
|
|
<para>Thanks for your interest in Conky.
|
|
</para>
|
|
</refsect1>
|
|
<refsect1>
|
|
<title>Compiling</title>
|
|
<para>For users compiling from source on a binary distro, make sure you
|
|
have the X development libraries installed (Unless you configure
|
|
your build without X11). This should be a package along the lines
|
|
of "libx11-dev" or "xorg-x11-dev" for X11 libs, and similar "-dev"
|
|
format for the other libs required (depending on your build
|
|
options). You should be able to see which extra packages you need
|
|
to install by reading errors that you get from running `cmake'. The
|
|
easiest way to view the available build options is to run `ccmake' or
|
|
`cmake-gui' from the source tree, but be careful when disabling
|
|
certain features as you may lose desired functionality. E.g.,
|
|
with BUILD_MATH disabled you won't get errors but logarithmic
|
|
graphs will be normal graphs and gauges will miss their line.
|
|
</para>
|
|
<para>Conky has (for some time) been available in the
|
|
repositories of most popular distributions. Here are some
|
|
installation instructions for a few:
|
|
</para>
|
|
<para>Gentoo users -- Conky is in Gentoo's Portage...
|
|
simply use "emerge app-admin/conky" for
|
|
installation.
|
|
</para>
|
|
<para>Debian, etc. users -- Conky should be in your
|
|
repositories, and can be installed by doing "aptitude
|
|
install conky".
|
|
</para>
|
|
<para>Example to compile and run Conky with default
|
|
components (note that some build options may differ for
|
|
your system):
|
|
</para>
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term>
|
|
<command>
|
|
<option>cmake</option>
|
|
</command>
|
|
<option>-D CMAKE_INSTALL_PREFIX:string=/usr .</option>
|
|
</term>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>
|
|
<command>
|
|
<option>make</option>
|
|
</command>
|
|
</term>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>
|
|
<command>
|
|
<option>make install</option>
|
|
</command>
|
|
<option># Optional</option>
|
|
</term>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>
|
|
<command>
|
|
<option>src/conky</option>
|
|
</command>
|
|
</term>
|
|
</varlistentry>
|
|
</variablelist>
|
|
<para>Conky has been tested to be compatible with C99 C and C++0x C++,
|
|
however it has not been tested with anything other than gcc, and is
|
|
not guaranteed to work with other compilers.
|
|
</para>
|
|
<para>TIP: Try configuring Conky with `ccmake' or `cmake-gui' instead of
|
|
just `cmake'.
|
|
</para>
|
|
<para></para>
|
|
</refsect1>
|
|
<refsect1>
|
|
<title>You Should Know</title>
|
|
<para>Conky is generally very good on resources. That said,
|
|
the more you try to make Conky do, the more resources it is
|
|
going to consume.
|
|
</para>
|
|
<para>An easy way to force Conky to reload your ~/.conkyrc:
|
|
"killall -SIGUSR1 conky". Saves you the trouble of having
|
|
to kill and then restart. You can now also do the same with
|
|
SIGHUP.
|
|
</para>
|
|
</refsect1>
|
|
<refsect1>
|
|
<title>Options</title>
|
|
<para>Command line options override configurations defined in
|
|
configuration file.
|
|
</para>
|
|
&command_options;
|
|
</refsect1>
|
|
<refsect1>
|
|
<title>Configuration Settings</title>
|
|
<para>Default configuration file location is $HOME/.conkyrc or
|
|
${sysconfdir}/conky/conky.conf. On most systems, sysconfdir is
|
|
/etc, and you can find the sample config file there
|
|
(/etc/conky/conky.conf).
|
|
</para>
|
|
<para>You might want to copy it to $HOME/.conkyrc and then
|
|
start modifying it. Other configs can be found at
|
|
http://conky.sf.net/
|
|
</para>
|
|
&config_settings;
|
|
</refsect1>
|
|
<refsect1>
|
|
<title>Objects/Variables</title>
|
|
<para>Colours are parsed using XParsecolor(), there might be a
|
|
list of them: /usr/share/X11/rgb.txt.
|
|
Colour can be also in
|
|
#rrggbb format (hex).
|
|
</para>
|
|
<para>
|
|
Some objects may create threads, and sometimes these threads will
|
|
not be destroyed until Conky terminates. There is no way to
|
|
destroy or clean up threads while Conky is running. For example,
|
|
if you use an MPD variable, the MPD thread will keep running until
|
|
Conky dies. Some threaded objects will use one of the parameters
|
|
as a 'key', so that you only have 1 relevant thread running (for
|
|
example, the $curl, $rss and $weather objects launch one thread per
|
|
URI).
|
|
</para>
|
|
&variables;
|
|
</refsect1>
|
|
<refsect1>
|
|
<title>Lua API</title>
|
|
<para>Conky features a Lua Programming API, and also ships with Lua
|
|
bindings for some useful libraries. Conky defines certain global
|
|
functions and variables which can be accessed from Lua code running
|
|
in Conky.
|
|
</para>
|
|
<para>To use Lua Conky, you first need to make sure you have a version of Conky
|
|
with Lua support enabled (``conky -v'' will report this). Scripts
|
|
must first be loaded using the lua_load configuration option. You
|
|
then call functions in Lua via Conky's $lua, $lua_read, and Lua
|
|
hooks.
|
|
</para>
|
|
<para>
|
|
Be careful when creating threaded objects through the Lua API. You
|
|
could wind up with a whole bunch of threads running if a thread is
|
|
created with each iteration.
|
|
</para>
|
|
<para>
|
|
At this time, the Lua API should not be considered stable and may
|
|
change drastically from one release to another as it matures.
|
|
</para>
|
|
<para>
|
|
NOTE: In order to accommodate certain features in the cairo
|
|
library's API, Conky will export a few additional functions for the
|
|
creation of certain structures. These are documented below.
|
|
</para>
|
|
&lua;
|
|
</refsect1>
|
|
<refsect1>
|
|
<title>Examples</title>
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term>
|
|
<varname>conky</varname>
|
|
<option>-t '${time %D %H:%M}' -o -u 30</option>
|
|
</term>
|
|
<listitem>Start Conky in its own window with date
|
|
and clock as text and 30 sec update
|
|
interval.</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>
|
|
<varname>conky</varname>
|
|
<option>-a top_left -x 5 -y 500 -d</option>
|
|
</term>
|
|
<listitem>Start Conky to background at coordinates
|
|
(5, 500).</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>
|
|
<varname>conky</varname>
|
|
<option>-C > ~/.conkyrc</option>
|
|
</term>
|
|
<listitem>Do not start Conky, but have it output
|
|
the builtin default config file to ~/.conkyrc for
|
|
later customising.</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
</refsect1>
|
|
<refsect1>
|
|
<title>Files</title>
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term>
|
|
<filename>
|
|
${sysconfdir}/conky/conky.conf</filename>
|
|
</term>
|
|
<listitem>Default system-wide configuration file.
|
|
The value of ${sysconfdir} depends on the
|
|
compile-time options (most likely /etc).</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>
|
|
<filename>~/.conkyrc</filename>
|
|
</term>
|
|
<listitem>Default personal configuration
|
|
file.</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
</refsect1>
|
|
<refsect1>
|
|
<title>Bugs</title>
|
|
<para>Drawing to root or some other desktop window directly
|
|
doesn't work with all window managers. Especially doesn't
|
|
work well with Gnome and it has been reported that it
|
|
doesn't work with KDE either. Nautilus can be disabled from
|
|
drawing to desktop with program gconf-editor. Uncheck
|
|
show_desktop in /apps/nautilus/preferences/. There is -w
|
|
switch in Conky to set some specific window id. You might
|
|
find xwininfo -tree useful to find the window to draw to.
|
|
You can also use -o argument which makes Conky to create
|
|
its own window. If you do try running Conky in its own
|
|
window, be sure to read up on the own_window_type settings
|
|
and experiment.</para>
|
|
</refsect1>
|
|
<refsect1>
|
|
<title>See Also</title>
|
|
<para>
|
|
<ulink url="http://conky.sourceforge.net/">
|
|
http://conky.sourceforge.net/</ulink>
|
|
</para>
|
|
<para>
|
|
<ulink url="http://www.sourceforge.net/projects/conky">
|
|
http://www.sourceforge.net/projects/conky</ulink>
|
|
</para>
|
|
<para>
|
|
<ulink url="http://wiki.conky.be">
|
|
http://wiki.conky.be</ulink>
|
|
</para>
|
|
<para>#conky on irc.freenode.net</para>
|
|
</refsect1>
|
|
<refsect1>
|
|
<title>Copying</title>
|
|
<para>Copyright (c) 2005-2009 Brenden Matthews, Philip
|
|
Kovacs, et. al. Any original torsmo code is licensed under
|
|
the BSD license (see LICENSE.BSD for a copy). All code
|
|
written since the fork of torsmo is licensed under the GPL
|
|
(see LICENSE.GPL for a copy), except where noted
|
|
differently (such as in portmon code, timed thread code,
|
|
and audacious code which are LGPL, and prss which is an
|
|
MIT-style license).</para>
|
|
</refsect1>
|
|
<refsect1>
|
|
<title>Authors</title>
|
|
<para>The Conky dev team (see AUTHORS for a full list of
|
|
contributors).</para>
|
|
</refsect1>
|
|
</refentry>
|