
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
sudo 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


Conky

Variables

Configuration settings

Lua API

About

Compiling

Contributing

Docker

Syntax Highlighting

Wiki