My first awesome

This little tutorial is for people who never used a tiling window manager before and don't have fancy hacking skills. We will explore the awesome world of awesome step by step and finally come up with a working desktop, providing some basic knowledge on how to configure awesome in the process. We will start with the default rc.lua that comes with awesome, play around a little and try to make it more beautiful and useful with widgets. For this tutorial you don't need any programming skills besides using a text editor.

Explore Awesome
I will assume that you properly installed awesome through your distro's package manager or compiled it from source. You should now add exec awesome to your ~/.xinitrc. As already mentioned, awesome provides a default config file which will be our starting point. You will usually find this rc.lua file in /etc/xdg/awesome/. Copy it to ~/.config/awesome/, and then start X. /!\ You should copy the whole directory, copying only the rc.lua will probably cause it to be ignored!

Move your Mouse to the upper left corner and click on the awesome logo. A little menu opens. Browse through the menu, then click the logo again to close it. Next to the awesome menu you see numbers 1-9. These are your tags (or desktops if you want). You can click on these to change them but nothing will happen because we have not opened any programs. On the top right you see the time/date and a symbol showing the current layout. You can also click on the symbol to change the active layout.

One of awesome's big advantages over other tiling window managers is its good mouse support. Awesome can act as a full floating window manager (almost like openbox) if you want. For this basic tutorial we will mainly focus on keyboard control, so let's learn some key bindings now.

Let's open a terminal: press Mod4+Enter. Mod4 is your "Windows key", the key between Ctrl and Alt. You can change the modkey if you want, but we'll get to that later. An xterm window will pop up. You can of course use your favourite terminal if you like. Again, more on that later. Now press Mod4+Shift+c to close the terminal. This is the command which lets you close any application. Awesome has a very elegant way to launch programs: press Mod4+r. Now you will see a Run: prompt in the status bar. Start anything you like, it also features Tab-completion!

Open another application. And another (another...) to see the tiling features. You can now press Mod4+Space to cycle through all the possible tiling (and floating) modes. Note that the icon in the upper right changes.

Also try Mod4+h, Mod4+l, Mod4+Shift+h and Mod4+Shift+l to resize Windows. You can also resize with Mod4+Button3 (right click). Mod4+f will make your current window fullscreen.

With Mod4+Number (1-9) you can browse through your tags. With Mod4+Shift+Number (1-9) you can send a window to a specific tag. Mod4+Left and Mod4+Right moves to the next tag in the specified direction.

Use Mod4+k and Mod4+j to toggle your focused client - moving your mouse will also do that if you haven't figured that out yet.

Mod4+Shift+q quits awesome, but don't do that now.

Read the man page for all key bindings (type man awesome in console), you will find many more useful ones. The man page is accessible through the awesome menu as well - press Mod4+w to bring it up.

Change the theme
Awesome has three themes you can choose from: default, sky and zenburn. There are also many user contributed themes you can find in Beautiful_themes.

To change the theme, open your rc.lua and edit this line near the beginning of the file:

beautiful.init("/usr/share/awesome/themes/default/theme.lua")

For this tutorial, I will stick with the default theme. Read the Beautiful wiki to find out more about theming.

Change the background image
Your desktop background image is handled in your theme file (theme.lua in your theme's directory). To change it, edit this line in your theme file:

theme.wallpaper_cmd = { "awsetbg /usr/share/awesome/themes/default/background.png" }

Personalize your tags
To optimize our workflow, we now want to give names to our tags and set the specific tiling or floating mode for each one. Open your rc.lua and find the layouts section. It should look like this:

layouts = {     awful.layout.suit.tile, awful.layout.suit.tile.left, awful.layout.suit.tile.bottom, awful.layout.suit.tile.top, awful.layout.suit.fair, awful.layout.suit.fair.horizontal, awful.layout.suit.spiral, awful.layout.suit.spiral.dwindle, awful.layout.suit.max, awful.layout.suit.max.fullscreen, awful.layout.suit.magnifier, awful.layout.suit.floating }

These are all possible tiling and floating options awesome has. Personally, I don't find all of the layouts useful (for example the spiral layout). You can comment or delete some if you think you never use them.

This is my personal opinion and may be different from yours, so carefully test each layout first. I will leave them unchanged for now.

Next, we want to name our tags. This is the default tag screen with numbers from 1 to 9:

--

Now we want to change the tag names and assign a specific layout to each one of them. By default, each tag has a floating layout. To change this, we define a specific tiling or floating layout for each tag. Replace the above with this code: --



We use layouts to set the layout for each tag. The Number in "[]" is the number of the layout. In this example we set main to the tile layout, www to tile.left, im to floating, etc. Edit this as you like.

While we're at it, we can also change the default terminal, editor and assign the modkey to a different key:

terminal = "xterm" editor = os.getenv("EDITOR") or "nano" modkey = "Mod4"

Change these settings to your liking, it's pretty self-explanatory and well-documented in the comments.

Save your rc.lua and restart awesome. Now your screen should resemble the screenshot on the right. Note that awesome is very sensitive to mistakes in your rc.lua. Even minor errors can crash it. You can save yourself some of the trouble caused by a bad configuration by checking for syntax errors with awesome -k.

Add widgets
Now we want to add some useful information to our status bar. This is done through widgets. Such as widgets for displaying memory usage, CPU temperature, battery status, etc. You can learn all about widgets, and how to create them on the Widgets in awesome page.

Some users created widget libraries applying the above principles, they try to simplify widget creation for others. Another advantage of widget libraries is the big number of system monitors they are distributed with, so you don't have to write your own. Many different libraries exist, but for this guide we will stick to the Vicious widget library, since it provides everything we need. For more advanced widgets that do more complex tasks, explore the Obvious widget library. Read the wiki entry how to install Vicious (it's easy).

Then, add

vicious = require("vicious")

to the beginning of your rc.lua. We now want a widget indicating our current network download and upload rate. Vicious provides a netwidget which is perfect for us.

Add this code to your rc.lua right after "-- {{{ Wibox" and before the "textclock" widget which is already there:

-- {{{ Wibox -- Network usage widget -- Initialize widget, use widget({ type = "textbox" }) for awesome < 3.5 netwidget = wibox.widget.textbox -- Register widget vicious.register(netwidget, vicious.widgets.net, ' ${eth0 down_kb} ${eth0 up_kb} ', 3)

To actually see the widget, we have to add it to our wibox. Add netwidget so the wibox section looks like this:

-- Create the wibox mywibox[s] = awful.wibox({ position = "top", screen = s }) -- Add widgets to the wibox - order matters mywibox[s].widgets = { {             mylauncher, mytaglist[s], mypromptbox[s], layout = awful.widget.layout.horizontal.leftright },         mylayoutbox[s], mytextclock, netwidget,      --   ADD THIS, don't forget the comma! s == 1 and mysystray or nil, mytasklist[s], layout = awful.widget.layout.horizontal.rightleft } end -- }}}

Now restart awesome to see the changes. You can also add some nice widget icons to further enhance the status bar. You can choose among many different icons sets on the Nice Icons page. To display icons, we first have to set them in our theme file. Open your theme file (theme.lua) and add the following:

theme.widget_net = "/path/to/icons/down.png" theme.widget_netup = "/patch/icons/icons/up.png"

Don't forget to change your path, usually it should be ~/.config/awesome/icons/.

Next, add the following to your rc.lua, right where you put the widget:

dnicon = widget({ type = "imagebox" }) upicon = widget({ type = "imagebox" }) dnicon.image = image(beautiful.widget_net) upicon.image = image(beautiful.widget_netup)

These lines goes after the theme definition.

Then add the icons to your Wibox, right before and after the "netwidget":

..   upicon, netwidget, dnicon, ..

Restart to see the final result.



The last thing we want to do, is add a separator between the netwidget and the clock. We will achieve this with a simple text widget. Add this to your rc.lua where your new widget is:

-- use widget({ type = "textbox" }) for awesome < 3.5 separator = wibox.widget.textbox -- use separator.text = " :: " for awesome < 3.5 separator:set_text(" :: ")

Add the separator to your wibox: ..   separator, upicon, netwidget, dnicon, ..

That's it. You now learned how to add widgets to your status bar. Read the Vicious wiki and the Readme file to learn how to add other widgets. You might also want to have a look at the Obvious widget package, which is also pretty straightforward to use.