
Conky is a system monitor for X. It can display almost anything, either on the
root window or in its own window. In addition to its many built-in objects,
Conky can also display information gathered through scripts and external
programs.

Conky includes more than 250 built-in objects, with support for a wide range of
system statistics including `uname`, uptime, CPU usage, memory usage, disk
usage, `top`-style process statistics, and network monitoring. It also includes
built-in IMAP and POP3 support, integration with several music players such as
MPD, XMMS2, and Audacious, and much more. Conky can present this information as
text or through simple progress bars and graph widgets, using a variety of
fonts and colors.

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


About


Building Conky with CMake is straightforward:

1. From the top-level source directory, create a build directory and change
   into it:

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

2. Run the CMake configuration step:

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

OR

```shell-session
ccmake ../ # use the ncurses interface instead, or try cmake-gui
```

3. Build and install as usual:

```shell-session
make
sudo make install # optional
```

Conky provides a number of build options. The easiest way to explore them is to
use `ccmake` or `cmake-gui`.

Some build-time features, such as documentation generation, require third-party
tools. CMake will usually tell you when one is missing. For documentation
generation, you will need the `docbook2X` package, which is available on most
distributions.


Compiling


Contributions are welcome from anyone.

## Pull Request Guidelines

When submitting PRs, please:

- Describe the changes and explain why they were necessary
- Describe how the changes affect existing behavior
- Explain how you tested and validated your changes
- Include unit tests when appropriate
- Include relevant screenshots or other evidence showing that the changes work
- Add a GPLv3 license header to any new source files
- Ensure that all new code is 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 let someone know when the build
  system is not working

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

## Coding Style

Code should be formatted with `clang-format`. If you configure Conky with
`cmake -DCHECK_CODE_QUALITY=ON`, you can run `make clang-format` to format the
code automatically.

## 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
lefthook](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 add new functions or methods, please consider adding unit
tests for them. Additional tests for existing code are also welcome.


Contributing


## Getting the image

Build the image with:

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

If you want the command-line version, use:

```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 command-line version is simpler:

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

To pass options to Conky, specify `conky` twice: once as the image name and
once as the command. For example:

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

This prints the Conky version. Because X is not required for this command, you
can also run:

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

If you want to experiment with the configuration first, run:

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

_Make any changes you want in the configuration._

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

See the Docker documentation for many other ways to use this container.

## Why?

Disadvantages of using Docker:

- You need to install Docker.
  This can be done by following the instructions in
  https://docs.docker.com/install/ to install Docker CE. Installing it through
  your distribution's package manager may also work.
- Much of the information displayed will reflect the current container rather
  than the entire host system.
- At the moment, the Docker image is still under development.

Advantages of using Docker:

- During installation, you do not need to worry as much about which compilers
  and libraries are installed, or how they are configured.
- Containerizing Conky makes it much less likely that problems with Conky will
  affect the rest of the system.
- Your Conky will run in exactly the same environment as everyone else's, so
  if it works for one person, it should work for others as well, regardless of
  distribution or host configuration. The Conky configuration itself, and the
  Conky version, still matter.
- Problems are easier for developers to reproduce, which can lead to faster
  debugging.


Docker


## Gedit

Note: this highlights syntax only and does **NOT** attempt to validate
arguments or keywords. It is unlikely to be 100% accurate, and improvements are
welcome.

Syntax highlighting is automatically applied to files with `conky` in their
name, for example `my_config.conky`. Unfortunately, it also matches the
`conky.lang` file itself, which you should set 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 starts. That
context then references other subcontexts. Each context can apply styles to
itself, to substrings matched by its regular expressions, or to its contents in
the case of `<start><end>` container contexts. If anything is unclear, search
the [`gtksourceview` docs][1] for the relevant XML attributes. If you run into
a particularly complex regex, try the Regex Tester linked above, and keep in
mind that `gtksourceview` adds some extra regex syntax, such as `\%[ ... ]`
and `\%{ ... }`.

---

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

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

For gedit v2.x:
`/usr/share/gtksourceview-2.0/language-specs/conky.lang`
or, for a 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 a 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