Main Page

The goal of this wiki is to provide a community-made documentation and especially help new users with the configuration of awesome. We cover developer information too, including information about how-to build awesome (several related distributions), how-to debug, and so on.

Note: Due to spammers, you must create an account in order to edit pages. While having to create an account to edit is annoying, so is spam.

Feel free to register a user and contribute with our documentation effort.

Current awesome releases:

• Stable: awesome 3.3.
• Development: Development versions of awesome can be downloaded as tarballs using git snapshots.
• Screenshots: Screenshots

Configuration and control of awesome have changed between major versions and may as well continue to evolve in future ones. Some of the following documents may try to describe all the existing versions. Please fix them if a missing version needs special explanations. Other documents may be bound to only one version of awesome. Please fix them if version indication is missing.

[edit] Installation & Basics For Users

• FAQ - Check here first if you're having problems!
• Building awesome - Instructions for building / installing awesome.
• awesome 3 configuration - Get help understanding awesome 3 configuration and API basics.
• awesome 2.X to 3.X Awesome Configuration Converter
• awesome 3.0 to 3.1 config options that changed between the releases
• Quickly Setting up Awesome with Gnome - How to make awesome be used in your gnome session with a couple commands.
• KDE and awesome
• man pages
• awesome-menu basics

[edit] Development Basics

• Debugging

[edit] Translations

Parts of this documentation were translated into different languages. Translated documents can contain additional information related to the native language or countries.

If there are translations available, a bar is displayed on the top of a page. This example is taken from the FAQ page:

Languages:

English  • Deutsch  • Français  • Italiano  • 日本語  • Русский

[edit] Reviews & News

• awesome 3 review on penguinsightings

[edit] Statusbars and widgets

• Widgets in awesome - A brief guide on the implementation of widgets within awesome.
• Widgets with Wicked - How to add dynamic widgets with the wicked library.
• User Contributed Widgets
• Using Cairo within Awesome
• Titlebar and Statusbar height - Small how-to that helps you to customize statusbar and titlebar height.

[edit] Theming awesome

• Theming with Beautiful - How to theme your awesome-3 with the beautiful library.
• User Contributed Themes - Several awesome themes for use with beautiful.
• Customizing Fonts - How to add new fonts to your system.
• Nice Icons - Where to find nice icons to use in your widgets.

[edit] User configuration files

Examples of other user's configuration files can be found here.

[edit] Other tips

• irssi tips - See here for some awesome irssi tips.
• Autostart - Small function providing autostart functionality for awesome.
• Run or raise - Run a client, or pop to it if it is already running.
• Revelation - Implementing Mac OS X Exposé in awesome.
• Gradient - Visual feedback on numerical data (e.g. processor usage).
• Problems with Java - What to do if your java apps look grey.
• XRandR Screen Table - If you don't like using numbers for screens.
• Move Mouse - Move the mouse from the centre of the screen for mouseless working.
• Rotate Clients - Functions to rotate all visible clients to the next position and keep the focus in place.
• Dbus, naughty and logs - Display colorized notifications of your logs.
• Naughty log watcher - Native implementation (no shell scripts/dbus required).
• Using Xephyr - How to run nested X sessions - good for testing new builds of awesome or different config files.
• Using Multiple Screens - How to setup X with multiple screens/monitors for use with awesome.
• nm-applet - How to setup nm-applet to start automatically in awesome.
• Mcabber notifications - Cool notifications for mcabber via naughty
• Drop-down terminal - Toggle a video game-like console on the top of your screen like Yakuake/Tilda.
• WMII-like tag management - mimic WMII's way of tag managment
• Custom Prompts - User contributed run prompts
  • SSH: prompt - Statusbar ssh prompt similar to Run: prompt with hostname completion.
  • Improving the Lua prompt - Completion and a more useful eval for the Lua prompt.
  • Wikipedia Completion - Wikipedia prompt with article completion.
  • Geo Prompt - Prompt for calculating the distance between two locations.
  • Manual Pages Prompt - Prompt for reading manual pages in your favorite application.
  • Web Search Prompt - Prompt for searching the web, giving you acess to any search form.

Lua is a fast, light-weight, embeddable scripting language. Lua combines simple procedural syntax with powerful data description constructs based on associative arrays and extensible semantics. Lua is dynamically typed, runs by interpreting bytecode for a register-based virtual machine, and has automatic memory management with incremental garbage collection, making it ideal for configuration, scripting, and rapid prototyping.

Common uses of Lua are:

• A configuration language for applications.
• A standalone scripting language.
• An embedded language in applications to modify runtime behaviour.

To get introduced into Lua, please read this tutorial for the newcomers to the language. As a suggestion, please consider to get this Lua Short Reference. The Awesome framework is build with Lua as the extension language. Some of all extensions can be see below:

• awful - the standard awesome Lua library.
• awful.menu - a popup menu library.
• Beautiful - a theming library.
• Wicked - a dynamic widget library.
• Space Invaders - allows you to play Space Invaders with Awesome
• Naughty - a popup notification library
• Shifty - dynamic tagging library with advanced client matching and sane configuration
• Rodentbane - a library for rapid control of the mouse cursor using just the keyboard

Most people these days are used to having a more complete desktop. This section includes links to various apps that are lightweight and useful from within awesome to fill the gaps between just a window manager and a full-blown desktop environment like KDE or GNOME.

• Customizing GTK Apps - How to use themes without gnome-settings-daemon.
• Terminals - Replacements for desktop environment terminals.
• File Managers - Lightweight stand-alone File Managers.
• Automounting - A replacement for "gnome-volume-manager", "thunar-volman", etc.