Adventures with Awesome-3.4.1-Part1-The Basics

              
#TODO: Add screenshots


        I promised a walk-through of how to setup an rc.lua with widgets and other personalizations in Awesome, and here I am to come through :)  First thing is first, installing Awesome.  I will assume that you are familiar with your linux distribution enough to be able to install a package.  For Sabayon users you can open up your favorite terminal and type:

equo update && equo install awesome

Once the package is complete, enter this command:

cp /etc/xdg/awesome/rc.lua /home/yourname/.config/awesome

If you get a complaint about the awesome directory not being there, create it (as user)

mkdir ~/.config/awesome  

and then follow the previous command to copy the stock rc.lua to your home directory.

To alleviate any issues of permissions, as root: chown yourname /home/yourname/.config/awesome/rc.lua

Remember! you will still have to be root to edit the rc.lua in /etc/xdg/awesome.

Now that all of that is out of the way, let's get to personalizing Awesome.  Open the run prompt (at the top of the screen) by typing mod4+r (mod4 = windows key on most US keymaps).  You will notice a small "run" dialog at the top of your screen on the statusbar.  Enter the run command for your text editor of choice (gedit, bluefish-unstable, emacs, etc), once your editor is up on your screen, open your rc.lua (from within your ~/.config/awesome directory) and take a look at what is going on.  Here is a look at the top of my rc.lua:

1.  -- Standard awesome library
2.  require("awful")
3.  require("awful.autofocus")
4.  require("awful.rules")
5.  -- Theme handling library
6.  require("beautiful")
7.  -- Notification library
8.  require("naughty")
9.  -- Vicious Widgets
10. require("vicious")

As you can see there is quite a bit going on here :)  Lines 1 - 10 are telling awesome what libraries to open, for now we won't worry about this, just know that what is contained in that block is what's required for awesome to open.

12.-- {{{ Variable definitions

13.-- Themes define colours, icons, and wallpapers
14.beautiful.init("/home/darthlukan/.config/awesome/themes/default/theme.lua")

Lines 12 - 14 are the first of what I think of as the "eye candy" configs.  Here is where we specify our themes to be used.  There are infinite possibilities to theming awesome since the themes are really just config files themselves where arguments for colors and images can be made (among other things).  Awesome by default comes with three themes, Default, Zenburn, and Sky.  More on themes in  later How To.  For now just keep in mind that there are several themes available to you and some user submitted ones can be found on the Awesome wiki.

16. -- This is used later as the default terminal and editor to run.
17. terminal = "lilyterm"
18. editor = os.getenv("EDITOR") or "vim"
19. editor_cmd = terminal .. " -e " .. editor

Now we move on to lines 16 - 19.  As you can see in the screen shot, I have selected lilyterm as my terminal of choice, your rc.lua (assuming no changes from stock) most-likely shows Terminal = "xterm".  To change this simply do as I did and within the quotes enter the run command for your terminal of choice ("Eterm", "rxvt", "aterm", etc).  You will also see the line (18) specifying the terminal editor of choice, I prefer vim, so I left it there, but you can change this to match your preference as well ("nano", "vim", "pico", etc).

20. -- Default modkey.
21. -- Usually, Mod4 is the key with a logo between Control and Alt.
22. -- If you do not like this or do not have such a key,
23. -- I suggest you to remap Mod4 to another key using xmodmap or 24. other tools.
25. -- However, you can use another modifier like Mod1, but it may 26. interact with others.
27. modkey = "Mod4"

I won't touch on the next few lines (21 - 26) only because I have not myself adjusted these settings (for lack of a reason to) and I don't want to give bad information.  However, the mod4 key in my case is the "winkey", it's just about the only useful things that I have found for windows (yes that's a stab at an inferior OS :P ).

For the sake of ensuring that we have our bearings straight, I've included the layout arguments in the screenshot.  But really we are going to skip this and get right into the tags.  Your rc.lua (if stock) does not look the same on these lines, instead you have numbers:

tags[s] = awful.tag({ 1, 2, 3, 4, 5, 6, 7, 8, 9 }, s)

Notice that there are no quotes ( ' ' or " " ), that is because you have numerical values.  To change the names of your tags (desktops) simply add either single (' ') or double (" ") quotes with your desired names within the quotes as you see in mine above.

Now we are going to take a break from this config file, I've thrown a lot at you and really by now you are looking at the default awesome background on your desktop and wonder, "when can I change this?".  So we are going to skip ahead a little and change that wallpaper :)

There are a couple of ways to do this, however, we are still at the basics level, so I'm going to show you the easiest way.  The following needs to be done as root using whichever text editor that you choose, here I'll use gedit:

# gedit /usr/share/awesome/themes/default/theme.lua

Once you have the file opened in your text editor, scroll down to line 77 (theme.wallpaper_cmd = )

and point the command to your desired background; in my case it is the same background as my SLiM theme.  You will have to restart awesome (or logout and log back in) for the change to take effect, but yes, it is truly as easy as that.  To restart awesome you can use key combinations (mod4+shift+r) or you can right-click on the desktop and in the awesome menu select "restart" or "quit".  If you select quit, awesome will close out completely and you will be sent back to your login manager, you will have to then log back in just as you would if you had turned on your computer.

With all of that done, you should now have Awesome setup for basic desktop use.  In the next part we will dive into changing themes, adding custom menus, and creating some simple widgets using Vicious!  If you are a more advanced user and feel that you have what it takes to dive right into customizing awesome, feel free to visit the Awesome wiki and have a look at all of the possibilities that have been posted there.  If you would rather play it safe, I'll have more up tomorrow.  For now, I'll leave you with a nice screenshot of some simple things that are possible with awesome :)  Enjoy:

-DarthLukan