mirror of
https://github.com/Llewellynvdm/conky.git
synced 2024-11-16 01:57:09 +00:00
0dbd27d2de
The cairo/imlib2/rsvg bindings require tolua++ [1], which is currently only compatible with Lua 5.1 or earlier. We need to force Conky to compile against Lua 5.1 if the user chooses to build the bindings. This commit adds a separate pkg_search_module command specifically for Lua 5.1, along with a note in the documentation. The original pkg_search_module command was updated to include (and prefer) Lua 5.3+. Also, I threw in two other minor random fixes to the docs while I was at it. [1] https://github.com/LuaDist/toluapp
320 lines
11 KiB
XML
320 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>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, 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 ~/.config/conky/conky.conf:
|
|
"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/.config/conky/conky.conf 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/.config/conky/conky.conf 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. 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>
|
|
<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 > ~/.config/conky/conky.conf</option>
|
|
</term>
|
|
<listitem>Do not start Conky, but have it output
|
|
the builtin default config file to
|
|
~/.config/conky/conky.conf 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>
|
|
<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-2012 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>
|