mirror of
https://github.com/Llewellynvdm/conky.git
synced 2024-12-27 04:32:55 +00:00
265 lines
12 KiB
XML
265 lines
12 KiB
XML
<?xml version="1.0" encoding="utf-8"?>
|
|
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
|
|
"docbook-xml/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>2012-05-03</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, 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
|
|
<filename>~/.config/conky/conky.conf</filename>: "killall -SIGUSR1
|
|
conky". Saves you the trouble of having to kill and then
|
|
restart.</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
|
|
<filename>~/.config/conky/conky.conf</filename> or
|
|
<filename>${sysconfdir}/conky/conky.conf</filename>. On most systems,
|
|
sysconfdir is /etc, and you can find the sample config file there in
|
|
<filename>/etc/conky/conky.conf</filename>.</para>
|
|
<para>You might want to copy it to
|
|
<filename>~/.config/conky/conky.conf</filename> and then start modifying
|
|
it. Other configs can be found at
|
|
<filename>
|
|
https://github.com/brndnmtthws/conky</filename>.</para>&config_settings;</refsect1>
|
|
<refsect1>
|
|
<title>Objects/Variables</title>
|
|
<para>Colours are parsed using XParsecolor(), there might be a list of
|
|
them:
|
|
<filename>/usr/share/X11/rgb.txt</filename>. 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. Note that the bindings require
|
|
tolua++, which currently only compiles against Lua 5.1.</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). Conky
|
|
defines certain global functions and variables which can be accessed from
|
|
Lua code running in Conky. 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>
|
|
<option>conky -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>
|
|
<option>conky -a top_left -x 5 -y 500 -d</option>
|
|
</term>
|
|
<listitem>Start Conky to background at coordinates (5,
|
|
500).</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>
|
|
<option>conky -C > ~/.config/conky/conky.conf</option>
|
|
</term>
|
|
<listitem>Do not start Conky, but have it output the builtin
|
|
default config file to
|
|
<filename>~/.config/conky/conky.conf</filename> 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>~/.config/conky/conky.conf</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>
|
|
<filename>https://github.com/brndnmtthws/conky</filename>
|
|
</para>
|
|
<para>#conky on irc.freenode.net</para>
|
|
</refsect1>
|
|
<refsect1>
|
|
<title>Copying</title>
|
|
<para>Copyright (c) 2005-2019 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 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>
|