Awesome

Resources

Home

Package information

Wikipedia

GitHub

#awesome ( webchat )

Open Hub

awesome is a highly configurable, next generation, dynamic window manager for X . It is primarily targeted at power users, developers and any people dealing with every day computing tasks and who want to have fine-grained control on their graphical environment. It is extended using the Lua programming language.

Prerequisites

Services

Choose exactly one of:

• elogind : Standalone logind package, extracted from the systemd project for use with OpenRC or other init systems.
• systemd : Uses the session tracker part of systemd. Users of systemd do not need to take any other initiative here.

Miscellaneous

• D-Bus : Enables use of the D-Bus message bus system.
• polkit : Enables the polkit framework for controlling privileges for system-wide services.
• udisks : Enables support for some storage related services.

X server

Follow the instructions on Xorg/Guide to set up the X environment.

Starting the X server

One of the following methods can be used to start X :

• Display manager : Presents the user with a graphical login screen.
• X without Display Manager : When running a single-user system, one may find display managers an unnecessary waste of resources.

Installation

USE flags

Emerge

Install x11-wm/awesome :

Configuration

Starting

To start awesome , refer to Starting the X server or use the command startx .

To use startx with elogind support, setup elogind and create the following file:

exec dbus-launch --sh-syntax --exit-with-session awesome

Configuration file

The default configuration file of awesome is located in ~/.config/awesome/rc.lua . If such a directory or file does not exist then it needs to be created. A default, out of the box, configuration is distributed with awesome and can be found at /etc/xdg/awesome/rc.lua . Copy that configuration file to the user's home directory.

First create the awesome/ directory:

Next copy the rc.lua configuration file:

If x11-terms/xterm is not installed, either install it or change the default terminal emulator to the terminal emulator available on the system. Below, the default terminal emulator is set to konsole , part of kde-apps/konsole .

-- This is used later as the default terminal and editor to run.
terminal = "konsole"

After making changes it is useful to check the configuration file for errors:

✔ Configuration file syntax OK

Add wallpaper support through the media-gfx/feh package:

For instance, to use awsetbg to set the wallpaper, edit ~/.config/awesome/theme/theme.lua :

theme.wallpaper_cmd = { "awsetbg -f .config/awesome/themes/awesome-wallpaper.png" }

Or simply set the wallpaper property of the theme:

theme.wallpaper = ".config/awesome/themes/awesome-wallpaper.png"

Tags

In awesome , tags are the name given to virtual desktops under which one or more applications are running. It is possible to assign custom symbols to these tags:

-- {{{ Tags
tags = {}
for s = 1, screen.count() do
    tags[s] = awful.tag({ "➊", "➋", "➌", "➍" }, s, layouts[1])
end
-- }}}

Menu

Below is an example of a custom awesome menu:

-- {{{ Menu
myawesomemenu = {
   { "manual", terminal .. " -e man awesome" },
   { "edit config", editor_cmd .. " " .. awesome.conffile },
   { "reload", awesome.restart },
   { "quit", awesome.quit },
   { "reboot", "reboot" },
   { "shutdown", "shutdown" }
}
 
appsmenu = {
   { "urxvt", "urxvt" },
   { "sakura", "sakura" },
   { "ncmpcpp", terminal .. " -e ncmpcpp" },
   { "luakit", "luakit" },
   { "uzbl", "uzbl-browser" },
   { "firefox", "firefox" },
   { "chromium", "chromium" },
   { "thunar", "thunar" },
   { "ranger", terminal .. " -e ranger" },
   { "gvim", "gvim" },
   { "leafpad", "leafpad" },
   { "htop", terminal .. " -e htop" },
   { "sysmonitor", "gnome-system-monitor" }
}
 
gamesmenu = {
   { "warsow", "warsow" },
   { "nexuiz", "nexuiz" },
   { "xonotic", "xonotic" },
   { "openarena", "openarena" },
   { "alienarena", "alienarena" },
   { "teeworlds", "teeworlds" },
   { "frozen-bubble", "frozen-bubble" },
   { "warzone2100", "warzone2100" },
   { "wesnoth", "wesnoth" },
   { "supertuxkart", "supertuxkart" },
   { "xmoto" , "xmoto" },
   { "flightgear", "flightgear" },
   { "snes9x" , "snes9x" }
}
 
mymainmenu = awful.menu({ items = { { "awesome", myawesomemenu },
                                    { "apps", appsmenu },
				    { "games", gamesmenu },
                                    { "terminal", terminal },
				    { "web browser", browser },
				    { "text editor", geditor }
                                  }
                        })
 
mylauncher = awful.widget.launcher({ image = image(beautiful.awesome_icon),
                                     menu = mymainmenu })
-- }}}

Date

Below is an example use of a custom date format. The format syntax used is %Y-%m-%d %H:%M . The second option, 60 , is the update interval in seconds.

-- {{{ Wibox
-- Create a text-clock widget
mytextclock = wibox.widget.textclock(" %Y-%m-%d %H:%M ", 60)
-- }}}

Volume control

media-sound/volumeicon can be used to handle volume keys automatically, and to show the volume level through a tray icon.

Autostart volumeicon from within ~/.xinitrc :

volumeicon &
exec [...]

Alternatively, a lightweight method is to add volume keys straight into the awesome configuration:

awful.key({ }, "XF86AudioLowerVolume", function () awful.util.spawn("amixer -q sset Master 5%-") end)
awful.key({ }, "XF86AudioRaiseVolume", function () awful.util.spawn("amixer -q sset Master 5%+") end)

MPD multimedia keys

Install media-sound/mpc to add multimedia key bindings for MPD :

Next update the awesome configuration to assign the multimedia keys to the proper command:

awful.key({ }, "XF86AudioNext",function () awful.util.spawn( "mpc next" ) end),
awful.key({ }, "XF86AudioPrev",function () awful.util.spawn( "mpc prev" ) end),
awful.key({ }, "XF86AudioPlay",function () awful.util.spawn( "mpc play" ) end),
awful.key({ }, "XF86AudioStop",function () awful.util.spawn( "mpc pause" ) end),

Removing window gaps

Gaps between windows can be visible, most noticeably between terminal windows. These can be removed by inserting the size_hints_honor = false property in the awful.rules.rules table like this:

awful.rules.rules = {
    { rule = { },
      properties = { size_hints_honor = false, -- Remove gaps
                     border_width = beautiful.border_width,
                     border_color = beautiful.border_normal,
      ...

Debugging the configuration with Xephyr

Xephyr is a useful tool for debugging new configuration files as it creates an instance of an X server within a client window.

This will open an 800x600 window. To run awesome within it open a new terminal and run the following:

This will run awesome within a window.

Keyboard shortcuts

These are the most useful default shortcuts:

• Super + Mouse1 = move client with mouse
• Super + Mouse2 = resize client with mouse

• Super + Enter = open terminal
• Super + r = run command
• Super + Shift + c = kill
• Super + m = maximize
• Super + n = minimize
• Super + Ctrl + n = restore minimized clients
• Super + f = full screen
• Super + Tab = switch to previous client
• Super + Ctrl + Space = float

• Super + j = highlight left client
• Super + k = highlight right client
• Super + Shift + j = move client right
• Super + Shift + k = move client left

• Super + l = resize tiled client
• Super + h = resize tiled client

• Super + left / right = change tag
• Super + 1-9 = change tag
• Super + Shift + 1-9 = send client to tag

Custom key bindings, like Alt + Tab , can be mapped to make the awesome experience even better. For instance, to use Alt + Tab to switch to the previous window:

-- {{{ Key bindings
globalkeys = awful.util.table.join(
...
    -- alt + tab
    awful.key({ "Mod1", }, "Tab",
        function ()
            awful.client.focus.history.previous()
            if client.focus then
                client.focus:raise()
            end
        end),
-- }}}

External resources

• User Configuration Files at awesome wiki (web.archive.org)
• Desktop profile switching USE default to elogind