
Conky is a system monitor for X. 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.

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.

If you'd like to get involved, please visit the project on GitHub at
https://github.com/brndnmtthws/conky.


About


Using CMake to build Conky is pretty easy, and here is how I do it:

1. From the top level source dir, create a build working dir, and cd into it

```shell-session
$ mkdir build
$ cd build
```

2. Run the cmake configuration process

```shell-session
$ cmake ../ # pass the path to the sources to cmake
```

OR

```shell-session
$ ccmake ../ # you can also use the fance curses interface, or try cmake-gui
```

3. Compile as usual, and enjoy the out-of-source goodness

```shell-session
$ make
# make install # if you want
```

There are a number of build options for Conky, and the best way to discover
them is to use the `ccmake` (or `cmake-gui`) CMake tool for browsing them.

Certain Conky build time features (such as doc generation) require third-party
applications, which you should be notified of via CMake. In the case of doc
generation, you'll need the docbook2X package (available on most
distributions).


Compiling


Contributions are welcome from anyone.

## Pull Request Guidelines

When submitting PRs, please:

- Describe the changes, why they were necessary, etc
- Describe how the changes affect existing behaviour
- Describe how you tested and validated your changes
- Include unit tests when appropriate
- Include any relevant screenshots/evidence demonstrating that the changes work and have been tested
- Any new source files should include a GPLv3 license header
- All new code must be GPLv3 licensed
- Try to leave the code better than you found it
- PRs with failed checks may be ignored or closed; please make sure
  the build and checks pass if possible (and notify someone when the build
  system is not working)

_Patches submitted in issues, email, or elsewhere may be ignored._

## Coding Style

Code should be formatted using `clang-format`. By configuring Conky with `cmake -DCHECK_CODE_QUALITY=ON`, you will be able to run `make clang-format` to automatically format code.

## Git hooks

To make life easier, you can use
[lefthook](https://github.com/evilmartians/lefthook) to handle some basic
linting with a pre-commit hook, as defined in [lefthook.yml](lefthook.yml).
Follow the [installation guide for
lefhook](https://github.com/evilmartians/lefthook/blob/master/docs/install.md),
then run `lefthook install` to enable the hooks.

## Unit Testing

Conky uses the [Catch2](https://github.com/catchorg/Catch2) unit testing framework. If you are adding new functions or methods, please consider adding unit tests for that code. Additionally, if you'd like to add tests for existing code, that would be a welcome contribution.


Contributing


## Getting the image

Build the image with:

```shell-session
$ docker build --tag=conky .
```

or if you want the commandline version:

```shell-session
$ docker build --build-arg X11=no --tag=conkycmd .
```

## Running the container

After building you can run the graphical version with:

```shell-session
$ docker run --rm -ti --net=host -e DISPLAY -v ~/.Xauthority:/root/.Xauthority conky
```

The commandline version is easier:

```shell-session
$ docker run --rm -ti conkycmd
```

If you want to pass some options to conky you can just add them if you mention
'conky' twice. Once for the image and once for the command. For example:

```shell-session
$ docker run --rm -ti --net=host -e DISPLAY -v ~/.Xauthority:/root/.Xauthority conky conky --version
```

will show you the version of conky. Since you don't need X for this you could also do:

```shell-session
$ docker run --rm -ti conkycmd conky --version
```

If you want to fiddle around a bit with the configuration first you could do:

```shell-session
$ docker run --rm -ti --net=host -e DISPLAY -v ~/.Xauthority:/root/.Xauthority conky bash
```

_change things is in the configuration_

```shell-session
$ conky -c configurationfile ; exit
```

See the docker docs to a lot of other ways to (ab)use this container

## Why?

Disadvantages of using the docker:

- You'll have to install docker.
  This can be done by following the instructions in
  https://docs.docker.com/install/ to install docker CE. But just using the
  packagemanager of your distro like you would do with other software will work.
- A lot of info will be about the current container instead of the whole system
- At the moment our docker image is still in development fase.

Advantages of using docker:

- During the installation you won't have to care about which compilers,
  libraries, ... are installed. Neither should you care about how to use them.
- The containerization of conky will make it a lot harder to let problems with
  conky affect the rest of the system.
- Your Conky will run in exactly the same environment as everyone else's, so
  if it works for someone it will work for everyone. No matter which distro you
  are using or how you configured that distro. (The conky configuration itself
  will matter and also the version of conky)
- Problems will be easier to recreate by developers causing faster debugging.


Docker


## Gedit

Note: this highlights based on syntax and does **NOT** attempt to validate arguments or keywords. The syntax highlighting is unlikely to be 100% accurate and is open to improvement.

The syntax highlighting will automatically be applied to all files with `conky` in their name. eg. `my_config.conky` (unfortunately it also triggers for the `conky.lang` file itself, you should set it to XML manually)

- [`gtksourceview` Syntax Highlight documentation][1]
- [Regex Tutorial](http://www.rexegg.com/)
- [Regex Testing](https://regex101.com/)

Developers: The main context (`id="conkyrc"`) is where gedit begins. This main context then references other sub-contexts. Each context can apply styles to itself, sub-strings from its regexs, or its contents (in the case of `<start><end>` "container" contexts). If you are ever confused by something, try searching for XML attributes in the [`gtksourceview` docs][1]. If you find a particularly complex regex, try using the Regex Tester linked above, and bear in mind that `gtksourceview` adds some extra regex syntax (i.e. `\%[ ... ]` and `\%{ ... }`).

---

for medit v1.1.1:
` /usr/share/medit/language-specs/conky.lang`

for medit - older versions:
`/usr/share/medit-1/language-specs/conky.lang`

for gedit v2.x
` /usr/share/gtksourceview-2.0/language-specs/conky.lang`
or (for single user)
` ~/.local/share/gtksourceview-2.0/language-specs/conky.lang`

for gedit v3.x
` /usr/share/gtksourceview-3.0/language-specs/conky.lang`
or (for single user)
` ~/.local/share/gtksourceview-3.0/language-specs/conky.lang`

[1]: https://developer.gnome.org/gtksourceview/stable/lang-reference.html


Syntax Highlighting

alignment

append_file

background

border_inner_margin

border_outer_margin

border_width

colorN

console_bar_fill

console_bar_unfill

console_graph_ticks

cpu_avg_samples

default_bar_height

default_bar_width

default_color

default_gauge_height

default_gauge_width

default_graph_height

default_graph_width

default_outline_color

default_shade_color

detect_battery

disable_auto_reload

diskio_avg_samples

display

double_buffer

draw_blended

draw_borders

draw_graph_borders

draw_outline

draw_shades

extra_newline

font

fontN

forced_redraw

format_human_readable

gap_x

gap_y

github_token

hddtemp_host

hddtemp_port

http_port

http_refresh

if_up_strictness

imap

imlib_cache_flush_interval

imlib_cache_size

lua_mouse_hook

lowercase

lua_draw_hook_post

lua_draw_hook_pre

lua_load

lua_shutdown_hook

lua_startup_hook

mail_spool

max_port_monitor_connections

max_text_width

max_user_text

maximum_width

minimum_height

minimum_width

mpd_host

mpd_password

mpd_port

music_player_interval

mysql_db

mysql_host

mysql_password

mysql_port

mysql_user

net_avg_samples

no_buffers

nvidia_display

out_to_console

out_to_http

out_to_ncurses

out_to_stderr

out_to_wayland

out_to_x

override_utf8_locale

overwrite_file

own_window

own_window_argb_value

own_window_argb_visual

own_window_class

own_window_colour

own_window_hints

own_window_title

own_window_transparent

own_window_type

pad_percents

pop3

short_units

show_graph_range

show_graph_scale

graph_gradient_mode

stippled_borders

store_graph_data_explicitly

temperature_unit

templateN

text_buffer_size

Conky

Variables

Configuration settings

Lua API

About

Compiling

Contributing

Docker

Syntax Highlighting

Wiki