====== Conky ======

Conky is the lightweight desktop widget system: a good fit for LXQt and this
hardware. Configs are Lua since Conky 1.10.

===== Install & run =====

<code bash>
sudo apt install conky conky-all
mkdir -p ~/.config/conky
cp /etc/conky/conky.conf ~/.config/conky/   # starting point
conky                                       # run it (it daemonizes)
conky -C > ~/.config/conky/conky.conf       # or dump default config
</code>

Autostart: ''lxqt-config-session'' → Autostart → add ''conky''. Or a ''.desktop''
file in ''~/.config/autostart/''.

===== Config structure (Lua syntax) =====

<code lua>
conky.config = {
    update_interval = 1,
    double_buffer = true,
    own_window = true,
    own_window_type = 'desktop',
    alignment = 'top_right',
    gap_x = 20, gap_y = 40,
    default_color = 'ebdbb2',
    font = 'DejaVu Sans Mono:size=10',
}

conky.text = [[
${alignr}${time %H:%M}
CPU: ${cpu}%  ${cpubar}
RAM: ${memperc}%  ${membar}
Temp: ${acpitemp}°C
Fan: ${execi 2 cat /sys/devices/platform/applesmc.768/fan1_input} rpm
]]
</code>

Useful objects: ''${cpu cpu1}'', ''${mem}'', ''${memperc}'', ''${swapperc}'',
''${acpitemp}'', ''${battery}'', ''${wireless_link_qual_perc wlp3s0}'',
''${downspeed}''/''${upspeed}'', ''${fs_used /}'', ''${top name 1}'',
''${exec cmd}'', ''${execi N cmd}'' (every N sec), ''${if_running mbpfan}'',
''${time %A %F}'', ''${alignr}'', ''${color red}'', ''${goto 100}'', ''${hr}''.

MacBook-specific goodies:

<code lua>
conky.text = [[
CPU ${cpu}%  ${hwmon coretemp temp 1}°C
Fan ${execi 2 cat /sys/devices/platform/applesmc.768/fan1_input} rpm
Turbo ${execi 5 cat /sys/devices/system/cpu/intel_pstate/no_turbo}
]]
</code>

===== Lua scripts (drawing, custom logic) =====

Load a script + hook it:

<code lua>
conky.config = {
    lua_load = '~/.config/conky/rings.lua',
    lua_draw_hook_pre = 'main',    -- calls conky_main() in rings.lua
    -- hooks: lua_draw_hook_pre/post, lua_startup_hook, lua_shutdown_hook,
    --        lua_mouse_hook
}
</code>

The Lua function must be named ''conky_<hook value>''. Drawing uses Cairo:

<code lua>
require 'cairo'

function conky_main()
    local surface = conky_surface()       -- nil in text mode
    if not surface then return end
    local cr = cairo_create(surface)

    -- read a conky variable from Lua:
    local cpu = tonumber(conky_parse('${cpu}')) or 0

    cairo_set_source_rgba(cr, 0.98, 0.74, 0.18, 0.8)   -- gruvbox yellow
    cairo_arc(cr, 60, 60, 40, -math.pi/2,
              -math.pi/2 + cpu/100*2*math.pi)
    cairo_set_line_width(cr, 8)
    cairo_stroke(cr)
    cairo_destroy(cr)
end
</code>

Gotchas:

  * ''conky_surface()'' is only valid inside the draw call: never cache it.
  * Guard early draws: ''${cpu}''-derived values are 0/NaN until the first update
  interval; skip when ''conky_parse('${updates}')'' < 3 or you'll crash.
  * Check Lua support: ''conky -v | grep -i lua''. The ''conky-all'' package has it.
  * Plain-text Lua output (no cairo): ''${lua conky_myfunc arg}'' calls
  ''conky_myfunc(arg)'' and prints its return value.

===== Standalone Lua =====

<code bash>
sudo apt install lua5.4 lua5.4-doc luarocks
lua5.4 -e 'print("hi")'
lua5.4 script.lua
luarocks install luasocket     # packages go to ~/.luarocks
</code>

===== Performance note =====

Conky itself is light, but ''execi'' every 1s on a 2-core adds up: prefer
built-in objects and ''execi 5''+ for shell-outs.


===== See Also =====

  * [[terminal:scripting:start|Scripting Index]]
  * [[terminal:tools:start|CLI Tools]]
  * [[terminal:start|Return to terminal]]
  * [[start|Return to wiki home]]