Skip to content

Home

Jump to bottom
Gerome Matilla edited this page Sep 17, 2020 · 5 revisions

The Wiki

If you want to replicate my setups, you better read this.

Dependencies

You must install these!

Name Description Why/Where is it needed?
awesome-git Highly configurable framework window manager Isn't it obvious?
rofi Window switcher, application launcher and dmenu replacement Application launcher
picom-git A compositor for X11 A compositor with kawase-blur
inter-font A typeface specially designed for user interfaces Setup font

Optional Dependencies

Dependencies needed to achieve the setup's full potential. These are optional.

Name Description Will be used by
light-git RandR-based backlight control application Brightness widget and OSD
alsa-utils, pulseaudio, pulseaudio-alsa An alternative implementation of Linux sound support Volume widget and OSD
acpi,acpid,acpi_call Show battery status and other ACPI info Power/Battery Widgets. No need for this if you're not using a laptop
mpd Server-side application for playing music Music widget
mpc Minimalist command line interface to MPD Music widget
maim Make image Screenshot tool
feh Image viewer and wallpaper setter Screenshot previews, wallpapers
xclip Command line interface to the X11 clipboard Will be used in saving the screenshots to clipboard
xprop Property displayer for X Custom titlebars for each client
imagemagick An image viewing/manipulation program Music widget/Extracts hardcoded album cover from songs
blueman Manages bluetooth default launch application for bluetooth widget
redshift Sets color temperature of display according to time of day Blue light widget
xfce4-power-manager Manages power default launch application for battery widget
upower upower - UPower command line tool Battery widget
noto-fonts-emoji Google Noto emoji fonts Emoji support for notification center
FantasqueSansMono Nerd Font Patched font FantasqueSansMono from the nerd-fonts library Rofi unicode font
xdg-user-dirs Manage user directories like ~/Desktop and ~/Music xdg-folders widget
iproute2, iw Manage network connection Network widget
ffmpeg Complete solution to record, convert and stream audio and video Screen Recorder Widget

Recommended Packages

These are the packages I recommend for ricing!

  • Terminal emulators: kitty, urxvt
  • Web Browser: firefox with custom CSS. You can find CSS themes here r/FirefoxCSS and here r/unixporn. Because of the blurred design of the setups, this is the recommended CSS theme
  • File Manager: dolphin, nemo
  • Editors: vim, neovim, or sublime text with some plugins
  • Launchers: rofi
  • Music Player: ncmpcpp, mpd and mpc combination, or lollypop

Recommended Fonts

FAQs

The most common questions.

  • Configure theme's colors/aesthetics?

    • awesome/theme/default-theme.lua
    • awesome/theme/theme-name/init.lua

  • Configure panels and bars?

    • awesome/layout/

  • Configure start-up and default applications

    • awesome/configuration/apps.lua

  • Global configuration for modules and widgets?

    • awesome/configuration/config.lua

  • Configure Keybindings?

    You can check keybinds by pressing Super + F1.

    Client keybindings:

    • awesome/configuration/client/keys.lua

    Global keybindings:

    • awesome/configuration/keys/global.lua

  • Configure client rules/behaviour?

    • awesome/configuration/client/rules.lua

  • Configure client tags/workspaces?

    • awesome/configuration/tags/init.lua

  • Configure the compositor?

    • awesome/configuration/picom.conf

  • Configure rofi?

    • Rofi Application Launcher:

      • awesome/configuration/rofi/appmenu/rofi.rasi

    • Rofi Web Search:

      • awesome/configuration/rofi/global/rofi.rasi

    • Rofi Web Search History file:

      • awesome/configuration/rofi/global/history.txt

How Tos

How to fix the errors on start-up?

Make sure that you are using the git master branch of awesomewm.

How to fix the missing ruled library?

Make sure that you are using the git master branch of awesomewm.

How to fix the widgets and modules?

Download all the dependencies.

How to change clock mode?

Switch to 24-hour mode or vice-versa by editing awesome/configuration/config.lua.

How to fix the rofi?

  • If it's too small/big:

  • If it's not launching:

    • Regenerate your locale. How? Duckduckgo is your friend.

  • If its font is broken?

How to fix scaling?

Set your dpi in ~/.Xresources. Add Xft.dpi: N where N is your screen dpi. Then reload ~/.Xresources and awesomewm.

How to get a credentials for weather widget?

  • OpenWeatherMap is our weather provider. So go to the website.
  • Register, log-in, and then go here to generate your API keys.
  • Put your credentials in awesome/configuration/config.lua.

How to get a valid credentials for email widget?

The widget uses an IMAP, so it means that any email service provider that supports IMAP is supported by the widget.

  • You need an email address (well duh).
  • You must generate an app password for your account. Your account password WILL NOT WORK! An App Password is required!
  • Just search the instruction on the internet on how to generate an app password for your email account.
  • You need an imap_server.
    • Just get your email service provider's imap server. Gmail's imap server is imap.gmail.com. If you're not using gmail, well, you need to put some effort. Go search it yourself.
  • Provide the port. Again, you can just search it on the internet. Gmail's port is 993.
  • Put your credentials in awesome/configuration/config.lua.

How to integrate PAM with the lockscreen module?

  • Clone the lua-pam library from here. Before building it make sure to read the next step.

  • Currently, awesomewm doesn't support lua5.4 so compiling the library on top of lua5.4 will break the lockscreen module. Make sure to change the CMakeLists.txt to build with lua5.3. Of course, you need to install lua5.3 first!

     cmake_minimum_required(VERSION 3.15)
 project(lua_pam)

 set(CMAKE_CXX_STANDARD 14)
 set(SOURCE_DIR src)

 include_directories(/usr/include/lua5.3)

 add_library(lua_pam SHARED ${SOURCE_DIR}/main.cpp)
 target_link_libraries(lua_pam lua5.3 pam)

  • If you're using an Arch-based distros, you can find it on the AUR. Don't forget to change the CMakeLists.txt. The library, liblua_pam.so, will be installed in /usr/lib/lua-pam/.

    • Reload awesome.

  • If you're running Debian or Debian-based distros, make sure to read and follow these:

    • Alter the CMakeLists.txt to build using lua5.3.
    • After building it, you can move or copy the library to awesome/library/.
    • Reload awesome.

About Widgets

More info about the widgets.

Calculator Widget

The calculator widget is a result of my boredom.

  • Supports:

    • Basic math operations
    • Keyboard support

  • Tips: Enable keyboard support by hovering your mouse above the calculator. Or toggle it on/off by pressing the keyboard button. Only numbers, arithmetic operators, and decimal point is accepted.

  • Keyboard Binding:

    • = and Return to evaluate.
    • BackSpace to delete the last digit.
    • Escape to clear the screen.
    • x stops the keygrabbing.

  • Note:

    • While in keygrabbing mode, your keyboard's focus will be on the calculator. So your awesomewm keybinding will stop working temporarily.

  • Stopping the keygrabbing mode:

    • Move away your cursor from the calculator.
    • Toggle it off using the keyboard button.
    • Press x.

Trash Widget

The trash widget.. well errm.. is actually useful! It monitors the trash directory using the awesomewms's awful.spawn.with_line_callback() and gio monitor trash:///, then updates the icon if there are changes.

  • Tip: Right-click to show the menu.

Music Widget

  • Depends:

    • mpd, mpc
    • A playlist with music

  • Optional Depends:

    • music file with metadata
    • music file with hardcoded album cover

Screen Recorder Widget

This is actually useful for basic screen recording.

  • Depends:

    • ffmpeg

  • Features:

    • You can toggle microphone on and off.
    • Change the settings on the main widget.

  • Note:

    • Change the default settings in awesome/configuration/config.lua

About Modules

More info about the modules.

Lockscreen Module

  • Depends:

    • ffmpeg (optional)
    • a webcam (optional)

  • Features:

    • PAM Integration!!! Thanks to RMTT's contribution, the lockscreen now supports PAM! Note that the library is not included by default. You need to compile it yourself. You can find its repo here. To implement it, read the How Tos above.
    • Using ffmpeg, it captures a picture using your webcam if the password is wrong. (Enabled by default)
      • Will store the images to $HOME/Pictures/Intruder/ folder.
    • Fallback password. The default fallback password is toor. You can change it in awesome/module/lockscreen.lua. You will only use this if the lua-pam library does not exist or returns an error. Read the note about the lua-pam library if you encountered an error.

  • Keyboard Binding:

    • Super + l - lock the screen
    • Control + u or Escape - clear the typed password
    • Return - validate password

  • Note:

    • You can set your profile image using mugshot or manually.

  • Vulnerabilities:

    • When you are logged-in in another TTY using the same account, running awesome-client "awesome.restart()" will reload awesomewm and unlock the locksreen. So yeah. Of course logging-in another TTY with your account and leaving your device unattended is the biggest security hole one can do. So be careful.

Dynamic Wallpaper Module

Another fruit of my boredom.

  • Note:
    • The wallpapers are in awesome/theme/wallpapers/
    • It has a four scheduled time:
      • morning, noon, night, midnight
    • You can change the time schedule and wallpaper to use in awesome/configuration/config.lua.
    • You can prevent the background from stretching on multihead setups by changing the value of stretch variable to true in awesome/configuration/config.lua.

Titlebar Module

The titlebar module is quite flexible (and messy). You can set the titlebar's position, color, and size for each client differently.

  1. Open awesome/modules/titlebar.lua.

  2. Find the Customize block.

  3. You can customize the titlebar of a client using its class, type, role, instance or name. Use xprop to get the needed value.

    For example, let's create a customized titlebar for kitty and xterm terminal emulator:

    if c.class == "kitty" then
	-- Create a left-side vertical titlebar with black color
	create_vertical_bar(c, buttons, 'left', '#000000', beautiful.titlebar_size)
elseif c.class == "XTerm" then
	-- Create a horizontal top titlebar with purple color
	create_horizontal_bar(c, buttons, 'top', '#FF00FF', beautiful.titlebar_size)
end

Menu Module

Yes, this is somewhat useless when we're using a tiling window manager, buuut... awesomewm is not a tiling window manager. It's a framework! And it handles floating clients pretty well. Sooo...

  • Note:
    • Change/Set icon the theme by opening awesome/theme/default-theme.lua and setting the value of theme.icon_theme to your desired icon theme.

Exit Screen Module

  • Keyboard bindings:

    • s to suspend.
    • l to lock.
    • r to reboot.
    • p to power off.
    • e to exit/log out.
    • escape, x, q to close exit screen.

  • Note:

    • Holding down the XF86PowerOff button will probably power off your machine without showing the exit screen module. If you can reproduced this problem, fix it by:

      For systemd users:

      1. Open the logind.conf.

        # You need a root privilege to edit this file
$ ${EDITOR} /etc/systemd/logind.conf

      2. Uncomment and set the HandlePowerKey to ignore.

        HandlePowerKey=ignore

      3. Restart the logind service

        # You need a root privilege to do this
$ systemctl restart systemd-logind.service

      For non-systemd users:

      1. I don't know. I'm using Arch btw, so I'm stuck with systemd and cannot test it.

    • If you're using a power management program, make sure to unbind or remove the event for power button to make sure it cannot "steal" the XF86PowerOff button from AwesomeWM.

Quake Terminal Module

  • Depends:

    • Any terminal emulator

  • Note:

    • Will use the default terminal set in apps.lua.

  • Keyboard bindings

    • Super + ~

Extras

  • Rice Qt5 apps on non Plasma environment

    1. Install qt5ct and qt5-styleplugins. We need these tools to configure Qt5 apps under environments other than KDE Plasma. qt5ct provides a Qt5 QPA independent of the desktop environment and a configuration utility.

    2. Set the environment variable QT_QPA_PLATFORMTHEME="qt5ct" so that the settings are picked up by Qt applications. You can set the environment variable in your ~/.xprofile or /etc/environment for global settings.

    3. Log out, so the environment variable can take effect. Log in.

    4. Install kvantum-qt5. Kvantum manager is an SVG-based theme engine for Qt5. This will be the main tool that will provide us the full blur effect and those sweet eyecandies.

    5. Install a kvantum theme. I recommend the Inverse-dark theme, because it's clean and modern looking. An edited version is in my repo and it's the one I've used in my screenshots above.

    6. Open kvantummanager to set your desired kvantum theme. You can configure the active theme to make some changes like making the dolphin view transparent, disable tooltip shadows, etc., etc.

    7. Run qt5ct again. Change the style to kvantum to use the kvantum theme. Hit OK.

    8. Open a Qt5 app. Enjoy.

Anti-aliased edges

Anti-aliasing is pretty doable, but it requires a hackish way to do it. The code is convoluted and unmaintainable, so I did not implement it in my setups. Implementing it will probably break things.

Anti-aliasing can be applied to any wibox by making its background color transparent and putting all its items in a shaped container with the desired background color.

The explanation above is from elenapan's documentation.

It means we have to add more than one titlebar around the client with transparent background then put a shaped container inside it to act as the titlebar's background.

Code example on how to create an anti-aliased left titlebar:

-- A titlebar with a color of #00000000, a black color with full transparency.
awful.titlebar(c, {position = 'left', size = title_bar_size, bg = "#00000000"}) : setup {
	{   
		{
			awful.titlebar.widget.closebutton    (c),
			awful.titlebar.widget.maximizedbutton(c),
			awful.titlebar.widget.minimizebutton (c),
			layout  = wibox.layout.fixed.vertical
		},
		{
			buttons = buttons,
			layout  = wibox.layout.flex.vertical
		},
		{ 
			awful.titlebar.widget.floatingbutton (c),
			layout = wibox.layout.fixed.vertical
		},
		layout = wibox.layout.align.vertical,
	},
	-- Purple color, this will act as the titlebar's background color.
	bg = "#ff00ff",
	-- This is the anti-aliased shaped container that will have the purple color and will act as the titlebar's background with 9 as the corner radius.
	shape = function(cr, width, height)
		gears.shape.partially_rounded_rect(cr, width, height, true, false, false, true, 9) 
	end,
	widget = wibox.container.background
}

More awesomewm resources

More contribution from the awesomewm community

Having an issue, problem, errors, fixes, or suggestions?

If you think you're a noob or newbie, don't be shy. As Einstein said, "The important thing is not to stop questioning. Curiosity has its own reason for existing." But I said, "Read the effin manual!". Anyway, feel free to open an issue and pull request. :)

Epilogue

Welp... writing this is exhausting af. :) Anyway, thanks to all the contributors here! And also to the awesomewm devs! Appreciate it! <3

Thanks for stopping by and happy hacking!

Clone this wiki locally