AwesomeWM - A Brief Introduction

[shearn89]

UPDATE - 1st July 2008 This guide is terribly out of date... I'll try and update it soon - the awesomerc syntax has changed completely, but i'm not sure how long it will be before they release awesome-3, which will ruin this guide yet again... for now, post in one of the threads [link], [link], or the Arch subforums (where most of the awesome users are).

UPDATE 24/01: The guide has now been changed for 2.1. It should cover mostly everything - if there's something i missed out, just post at the end.

This guide has been written due to the increase of interest in tiling window managers such as Awesome, WMII, DWM, etc. It does not aim to be definitive, merely a starting point. PM me with questions, or post below. There are a number of other users of WMs like awesome on the forums, so a posted question in the right section should eventually get an answer!

This guide is based on the awesomeWM, but as awesome is a derivative of DWM, it should bear some relevance to both DWM and wmii.

Contents
1. Introduction
2. Disclaimer
3. Install
4. A brief tour
5. Autostarting
6. awesomerc
7. Statusbar scripts
8. Links


1. Introduction

Introduction to Tiling Window Managers
The window manager you're currently using (most likely gnome, or perhaps xfce or openbox. Or kde. Any of those) will probably be a floating window manager. This means that when a window is created (eg, opening nautilus/thunar), it is either maximised, or it "floats" on the desktop. It can be resized and moved freely. In a tiling window manager (twm), the windows are tiled on the desktop. For example, if I open my terminal program (urxvt), it opens fullscreen. If I open another one, they take up half the screen each. If I open a third, one will take half the screen, and the other two share the remaining space. This is the essence of a twm.

Why awesome is awesome
Awesome is a tiling window manager, but (in my opinion, among other things) one of the reasons it is my favourite is that you can set it to run as a normal floating window manager, albeit one whose windows have no borders. This, coupled with its very small size (114kb according to pacman on my system), make it a great choice for someone who doesn't need eye candy, and wants a fast system.

2. Disclaimer
A word of warning
The howto that follows should be totally safe, and in no way harm your system. However, I cannot be held responsible for anything that happens to your system.

3. Install

So, onto the guide!
NB - all entries in "code" tags should be entered into a terminal, like gnome-terminal or xterm.

Get awesome...

1. Install dependencies:

sudo apt-get install build-essential libxinerama-dev libxrandr-dev libcairo2-dev libxft-dev libconfuse-dev asciidoc xmlto doxygen

Download and compile confuse 2.6 (thanks mali2297:

cd
wget http://bzero.se/confuse/confuse-2.6.tar.gz
tar xf confuse-2.6.tar.gz
cd confuse-2.6
./configure
make
sudo make install

2. Download/install awesome:

cd
wget http://awesome.naquadah.org/download/awesome-2.1.tar.gz
tar xf awesome-2.1.tar.gz
cd awesome-2.1
./configure
make
sudo make install
cp awesomerc ~/.awesomerc

3. To add an entry to GDM, do the following (thanks to Gigamo):

"Just to help you, here is my GDM desktop entry (from when I was still running with GDM, ditched it now ) (this should be named awesome.desktop and put in /usr/share/xsessions)

[Desktop Entry]
Encoding=UTF-8
Name=Awesome
Comment=Log in using the Awesome window manager
Exec=/home/<username>/awesome.sh
Icon=
Type=Application

where awesome.sh is the file that exec'd all the autostarted applications AND awesome on the end:

#!/bin/bash
#AUTOSTARTED APPS AND SETTINGS

#STATUSBAR TEXT

#Launch awesome
sleep 1 && exec awesome

Then, make this file executable:

chmod +x awesome.sh

You can put awesome.sh anywhere you like, but make sure you change the "Exec" line in awesome.desktop to match it.
NB - Gigamo's original code is below, i've simply edited it to save space. He has a nice script for the statusbar which includes a battery level for laptops etc.

If you're not running gdm, then you just need to edit your ~/.xinitrc file (backup first!):

cp .xinitrc .xinitrc.old
nano .xinitrc
#remove/comment out any entries for other WMs, and add:
exec awesome

4. Restart X, and then use "startx" to launch awesome.
For GDM, simply logout, select awesome from the "sessions", and log back in.

5. Congratulations! Awesome should be sitting on your desktop! Now we'll move onto customising it, and making it really useable.
NB - this section was written with awesome-2.0. When i've had a chance to play with awesome-2.1, i'll rewrite it.

4. A brief tour
Welcome! The bar at the top of the screen is the "status bar", and contains tags (like workspaces), numbered 1 to 9. Next to these is the icon representing what layout you are currently using. Then is a space for the window title, then the status-text at the top right.

Tags
Tags are like workspaces, only better! In the awesome configuration file (more info later), you can assign tags to a program, so that it appears on 1, 2, or any number of different tags. So if you open xchat, you could get it to open on its own tag, and on an "internet" tag. Or whatever. They're much more powerful than workspaces.

Layouts
Awesome comes with 4 layouts - Right-tile, Left-tile, Maximised, and Floating. Right-tile means that it's in tiling mode, and the right-hand side is the secondary section, where windows that you're not focused on stack. Left-tile is the opposite, so they stack on the left. Maximised is maximised, and Floating is floating! You can also set different tags to be different layouts by default, so you could have a terminal tag which is tiled, a browser tag which is maximised, and an IM tag which is floating.

Status
At the moment your status-text won't say anything. Not very helpful. I'll show you how to change it a bit later.


5. Autostarting
Awesome has no autostart capabilities, so the easiest thing to do is make your own autostart script, call it something like autostart.sh, and add the following to it:

#!/bin/bash
sleep 1
conky &
nitrogen --restore

Or whatever. I put the "sleep" command in there to make sure that awesome has time to load before anything starts trying to use the desktop etc. I use nitrogen for my wallpapers, you may use something like feh instead, for which replace the nitrogen command with

~/.fehbg &

Then, to make awesome use your script, edit ~/.xinitrc again, and add this before "exec awesome":

/home/user/path/to/script &

That should make awesome launch and run all your stuff (conky, feh, etc.)


6. .awesomerc
All awesome-specific settings are controlled by ~/.awesomerc, which has a number of different sections.

general
This is general settings - in 2.1, you'll need to add the "general" and "colour" sections : mine are included.

border is whether or not to show a border around the windows. snap is (I think) the number of pixels within which windows will "snap" to edges when floating. I'm not sure what resize_hints does. opacity_unfocused is used in conjunction with xcompmgr to make unfocused windows truely transparent, and the number following it is the percentage. focus_move_pointer is to make the mouse follow the window focus. allow_lower_floats is to dis/allow windows to be floating underneath other, non-floating windows. font is the statusbar font.

  general
    {
        border = 1
        snap = 8
        resize_hints = true
        focus_move_pointer = false
        allow_lower_floats = false
        new_become_master = true
        new_get_focus = true
        font = "gelly-8"
    }

colors
Again, in 2.1, you need to add these:
Fairly self-explanatory, focused/unfocused window default colours, and border colours.

    colors
    {
        normal_border = "#000000"
        normal_bg = "#000000"
        normal_fg = "#ffffff"
        focus_border = "#e71b3c"
        focus_bg = "#000000"
        focus_fg = "#e71b3c"
    }

tags
This is an important section - it controls the names and layouts of the tags along the top left. I have this in my file:

tags{ 
	tag term {layout = "tile"} 
	tag opera {layout = "max"} 
	tag max {layout = "max"} 
	tag floats {layout = "floating"}
    }

Layout can be "tile","max", "floating", and "tileleft". In 2.1, they have also added "spiral" and "dwindle". Spiral is each window getting smaller, in a fibonacci spiral, dwindle is each window getting smaller towards the corner.

layouts
These are simply the icons for the different layouts. You can set them to what you like, but you'll have to make .png files for them.

statusbar
position - again, self-explanatory. You can also add "height = <value>" and "width = <value>", if you want a specific h/w.

taglist
These are the mouse controls for interaction with the tag list in the top left. Leave them as they are, but read through so you know what they do.
The "Mod4" key is the windows, or super, key. Mouse1 is left click, Mouse2 is right, Mouse3 is middle, mouse4 is wheel-up, mouse5 is wheel-down.

tasklist
the same as taglist - the mouse controls for interaction with the taskbar section.

textboxes
This section isn't in there by default, but if you want the status-text to say anything (top right), then add entries here. Each entry is a "widget" which text can be piped to. Loke has a post on it in this thread, a few posts down. I've covered it briefly a bit further down in the "status-text" section.
A typical entry is:

textbox mpd
      { text = "mpd" #gets changed by script }

rules
This is another important section - this is where you "tag" programs, and a typical entry looks like this:

rules{
	rule {name="xterm" tags="term"}
	rule {name="firefox" tags="internet"}
}

The other two sections are mouse and keys. These contain all the keybindings that are set by default, so the easiest way to start learning is to read through. There are A LOT of keybindings in there, and the thing to do is try and find the most useful ones and learn them first.
All mouse related bindings go in mouse, and keyboard shortcuts go in keys.
As an example, if you put the mouse in the tags section of the status bar and spin the wheel up, you'll flick through the tags. It doesn't work anywhere else.

You'll want to add some shortcuts for programs here, and the ones i use most regularly are here:

keys
{
    key
    {
        modkey = {"Mod4"}
        key = "t"
        command = "spawn"
        arg = "exec urxvt"
    }
    key
    {
        modkey = {"Mod4"}
        key = "o"
        command = "spawn"
        arg = "exec opera"
    }
    key
    {
        modkey = {"Mod4"}
        key = "f"
        command = "spawn"
        arg = "exec thunar"
    }
    key
    {
        modkey = {"Mod4"}
        key = "p"
        command = "spawn"
        arg = "exec pidgin"
    }
#MPC COMMANDS
    key
    {
        modkey = {"Mod4", "Control"}
        key = "space"
        command = "spawn"
        arg = "exec mpc toggle"
    }
    key
    {
        modkey = {"Mod4", "Control"}
        key = "Left"
        command = "spawn"
        arg = "exec mpc prev"
    }
    key
    {
        modkey = {"Mod4", "Control"}
        key = "Right"
        command = "spawn"
        arg = "exec mpc next"
    }
    key
    {
        modkey = {"Mod4", "Control"}
        key = "Up"
        command = "spawn"
        arg = "exec mpc volume +1"
    }
    key
    {
        modkey = {"Mod4", "Control"}
        key = "Down"
        command = "spawn"
        arg = "exec mpc volume -1"
    }
#END MPC

The mpc commands are especially useful.
You may find that occaisonally some bindings don't work, or conflict with a program. The only way round it is to change the keybindings. Also, as a note, never launch a program without the "exec" command, as it messes up and you have to log out and edit the .awesomerc file from the console to get it back to normal...


7. Statusbar scripts
My section looks like the following:

  textbox mpd
            {
                text = "mpd " #to be changed
            }
        textbox gmail
            {
                text = " gmail" #to be changed
            }

And the script that pipes text to it:

#!/bin/bash
while true
do
echo 0 widget_tell mpd "[mpd: `mpc | head -n1` @ `mpc | grep volume | cut -b8-11`] " | awesome-client
echo 0 widget_tell gmail " [`check_gmail`]" | awesome-client
sleep 10
done

This basically goes "echo <screen number> widget_tell <widget name> "text" | awesome-client".
Any script can be used to output to it. The awesome wiki has a few scripts that you can use.

8. Links
The website has more info, and a brief guided tour. They also have a link to their wiki, which is good for a few FAQs.
For menus and such, see the awesome wiki.

[urukrama]

It seems awesome is only in the Hardy repos, not in the Dapper, Edgy, Feisty or Gutsy repos, shearn89. On Gutsy etc. you'll have to compile from source.

This looks like a decent guide, otherwise. I've never been fond of tiling window managers (I want most of my windows fullscreen), but perhaps I'll give this another try.

[Gigamo]

Great guide already. Also, thanks for the MPC binds. Those are extremely useful indeed

[shearn89]

Originally Posted by urukrama It seems awesome is only in the Hardy repos, not in the Dapper, Edgy, Feisty or Gutsy repos, shearn89. On Gutsy etc. you'll have to compile from source. This looks like a decent guide, otherwise. I've never been fond of tiling window managers (I want most of my windows fullscreen), but perhaps I'll give this another try.

Blast - okay, edits coming up! Thanks though!

EDIT: changes made, just need to check the dependencies... And run it through myself! Maybe i'll set up an "AweBuntu" machine...

[Gigamo]

Originally Posted by shearn89 Blast - okay, edits coming up! Thanks though! EDIT: changes made, just need to check the dependencies... And run it through myself! Maybe i'll set up an "AweBuntu" machine...

Just to help you, here is my GDM desktop entry (from when I was still running with GDM, ditched it now ) (this should be named awesome.desktop and put in /usr/share/xsessions)

[Desktop Entry]
Encoding=UTF-8
Name=Awesome
Comment=Log in using the Awesome window manager
Exec=/home/gig/awesome.sh
Icon=
Type=Application

where awesome.sh is the file that exec'd all the autostarted applications AND awesome on the end:

#!/bin/bash
xsetroot -bg black
export OOO_FORCE_DESKTOP="gnome"
if which dbus-launch >/dev/null && test -z "$DBUS_SESSION_BUS_ADDRESS"; then
eval `dbus-launch --sh-syntax --exit-with-session`
fi

xcompmgr -cC -t-3 -l-5 -r5 &
urxvtd -o -q -f &
thunar --daemon &
gnome-settings-daemon &
update-notifier &
nitrogen --restore &
restricted-manager --check &
trayer --expand true --widthtype request --transparent true --alpha 255 --edge bottom --align right &
/opt/wicd/tray.py &
(sleep 7 && urxvt -e screen) &

while true
do
    sleep 10
    echo "0 setstatustext [MPD: `mpc | sed -n '1p'`] :: `mpc | grep "#" | cut -c 1-9` :: [Bat: `sh 'readbattery.sh'`] :: [`date '+%A %d/%m/%Y %H:%M'`]"
done | awesome-client &

sleep 1 && exec awesome

[shearn89]

excellent - thanks a lot Gigamo. I'm also putting a warning about 2.1 on here, as it could scare people away from awesome given how tricky it is...

[~LoKe]

In Awesome 2.1m, which you linked to, the ~/.awesomerc is completely different. Also, I feel I should make a note on the subject of setstatustext. Well, it's gone.

This is how you'd do it now:

while true
do
echo 0 widget_tell mpd "[MPD: `mpc | sed -n '1p'`] :: `mpc | grep "#" | cut -c 1-9`" | awesome-client
echo 1 widget_tell clock "[`date '+%a %b %d %r'`]" | awesome-client
sleep 1
done

Now, because that doesn't make any sense, I feel the need to explain it. Awesome 2.1 has support for multiple widgets, so now you can change the text on a lot of different things than before (it used to be only at the end of the status bar). Basically, "widget_tell", as the name implies, tells the widget something. In this case, we're telling the widget named "mpd" to echo the song information on screen 0. That means we need a widget named mpd in our ~/.awesomerc (careful with this, you have to position it in the order you'd like it to appear, so it has to be after the tag list and layouts). An example of ~/.awesomerc, for this to work:

screen "0"
{
	general
	{
	    # gen section
	}
	statusbar "mystatusbar"
	{
		#statusbar properties
		{
		#mousebinds and whatnot
    	}
		textbox mpd  #<-- The money
		{
			text = "-" #the - will be replaced by mpd playing
		}
  	}
  	tags
	{
		#tags
	}
	colors
	{
		#colors
	}
	layouts
	{
		layout "tile"		{image = "/usr/local/share/awesome/icons/layouts/tile.png"}
		layout "tileleft"	{image = "/usr/local/share/awesome/icons/layouts/tileleft.png"}
    	layout "max"		{image = "/usr/local/share/awesome/icons/layouts/max.png"}
	    layout "spiral"		{image = "/usr/local/share/awesome/icons/layouts/spiral.png"}
	    layout "dwindle"	{image = "/usr/local/share/awesome/icons/layouts/dwindle.png"}
		layout "floating"	{image = "/usr/local/share/awesome/icons/layouts/floating.png"}
	}
}

[Gigamo]

LoKe, could I have a look at your awesome 2.1 awesomerc? I'm thinking of upgrading too... But then I'm going to convert my awesomerc beforehand

[Lostincyberspace]

I am going through on a xubuntu testbed and it says I need CAIRO What cairo do I need? A complete list of dependencies should be made and the different version.


Edit: I got it not sure what it is though but now it needs confuse 2.6+ gutsy repositories only have 2.5

[Gigamo]

sudo apt-get install libcairo2-dev