Howto: Install and configure Pekwm

[urukrama]

Contents

1. Introduction
2. Installing Pekwm
3. Creating a Session entry for Pekwm
4. Pekwm basics
5. Configuring Pekwm
6. Pekwm themes
7. Conclusion

1. Introduction

Pekwm is a fast, functional, and flexible window manager, originally based on aewm++. It supports tabbed windows (like Fluxbox), key chains, pixmap themes, xinerama support and much more. If you like Fluxbox or Openbox chances are you'll like Pekwm too, as it resembles both in looks and functionality. Pekwm is still actively developped.

Here is what Pekwm can look like:

(The first screenshot uses the Groove Pekwm and Gtk theme, second the Fearless Pekwm theme and a modified Royalty gtk theme)

Pekwm has excellent documentation, which you can find here. Everything you need to know to use Pekwm can be found there, and though it can be daunting at times I strongly recommend reading it. This guide is not meant to repeat or replace the official documentation, but rather to help Ubuntu users new to Pekwm getting started.


2. Installing Pekwm

Ubuntu Hardy (8.04) and Intrepid (8.10) have a Pekwm package in the repositories. Unfortunately, this is not the latest version. You can easily install that package through Synaptic or with the command sudo aptitude install pekwm, but the latest version of Pekwm contains a lot of bug fixes and some added features that make Pekwm so much easier and more pleasant to use. It is, in other words, more than worth it spending some time installing the latest version.

You can install the latest stable version of Pekwm (0.1.8 ) in two ways: if you run Hardy you can use the Debian package Daniel Moerner (InfinityCircuit) created, or you can build from source.

2.1 Installing the Debian package

First edit your sources list for Apt and Aptitude (sudo nano -B /etc/apt/sources.list), and add the following two lines to it:

deb http://ppa.launchpad.net/dmoerner/ubuntu hardy main
deb-src http://ppa.launchpad.net/dmoerner/ubuntu hardy main

Next update Aptitude so it can access these repositories, and install Pekwm:

sudo aptitude update
sudo aptitude install pekwm

That's it! If all went well, Pekwm should now be installed and ready to use.

2.2 Building Pekwm from source

If you don't use Hardy, or prefer to build from source, it is a little more work, but still a lot easier than it seems. Here is how to do it.

• Preparation

  Since you will have to build from source, you will need the basic building tools installed. If you have never build a package from source before, you'll have to install build-essential. I also recommend installing checkinstall, as it makes it much easier to remove the package you've installed later on. Checkinstall will first create a .deb package and install that. This means that it will show up in Synaptic and can be removed with Apt or Aptitude.
  
  You can install these with the following command:
  
  

  sudo aptitude install build-essential checkinstall

  Next install the needed dependencies for Pekwm:
  
  

  sudo apt-get build-dep pekwm

• Download the source code from the Pekwm site.

  Use your favourite web browser to surf to the Pekwm site and click on the download link for Pekwm 0.1.8 to download the latest stable version, or download it with the following command:
  
  

  wget http://pekwm.org/projects/3/files/pekwm-0.1.8.tar.bz2

• Unpack the archive

  Once the source code archive has been downloaded, it is time to unpack it. Use a file browser to navigate to the directory where you saved the file and unpack the archive to the directory of your choice. Alternatively, you can use the command line as follows:
  

  cd /path/to/the/directory/where/the/archive/is/saved
  tar xjvf pekwm-0.1.8.tar.bz2

• Configure the package to make it ready to compile

  Now you have to compile the package. Open a terminal and navigate with the cd ('change directory') command to the directory where the unpacked archive is:
  

  cd pekwm-0.1.8/

  Then run the configure script to prepare the source for installation with the following command:
  

  ./configure

  You can add several options to this. Using this command, the package will be installed in /usr/local/. If you'd like the package to be installed in another directory, for example /usr/, use the following command:
  

  ./configure --prefix='/usr'

  If you would like Xinerama support (if you have more than one screen), you'll have to specify that now as well by adding the --enable-xinerama option:
  

  ./configure --enable-xinerama

  There are more options (see here), but unless you really know what you are doing, you need not be concerned with them.
  
  The configure script will look for dependencies and basic system settings. Just let it all run. You don't need to worry about what it tells you, unless you encounter an error and the process is aborted: only the first error message is then of importance as it will help you figure out what went wrong. If all goes well, you should see something like this:
  

  * pekwm version 0.1.8 configured successfully.
  *
  * PREFIX: /usr/local
  * FEATURES:  XShape Xrandr Xft image-xpm image-png menus harbour
  * CXXFLAGS: -g -O2  -I/usr/include -I/usr/include/freetype2
  * LIBS:   -L/usr/X11R6/lib -lX11 -lXext -lXrandr -lXft -lX11 -lfreetype -lz -lfontconfig -lXrender -lX11 -lXpm -lpng

  If you changed the destination directory, as explained above, the 'PREFIX' line will give the directory you specified. If you have configured with the xinerama option, the 'FEATURES' line will include Xinerama. You can ignore the rest.

• Build the package

  Once all this is done, you have to build the package. At the command prompt type the following command:
  

  make

  A lot of information will appear. If no errors show up, none of it is really important and can safely be ignored. Note that this may take a while.

• Install Pekwm

  If all this went smoothly and no errors were encountered, you can finally install the package with the following command:
  

  sudo checkinstall

  (If you prefer not to use checkinstall, type 'sudo make install' instead.)
  
  Checkinstall will then build a .deb package and install that. If you'd rather build the .deb now, but install the package later using that deb, enter the following command instead to install:
  

  sudo checkinstall -D

  Checkinstall will ask for confirmations three times in the beginning of the process, so keep an eye on it. The defaults are fine, so you can just press enter when it asks for something.
  
  If all goes well, Pekwm is now installed. If you encounter any error messages in this process, post them in this thread, and perhaps someone can help.

3. Creating a Session entry for Pekwm

If you use a display and session manager, such as GDM, KDM or Slim, you will not have an entry for Pekwm in the Sessions menu of your login screen. But don't worry, this is easily created. Open a terminal and enter the following command (you can replace nano by any other text editor, such as mousepad, leafpad, vim or gedit):

sudo nano /usr/share/xsessions/Pekwm.desktop

An empty file will open. Add the following to this:

[Desktop Entry] 
Encoding=UTF-8 
Name=PekWM
Comment=Start PekWM
Exec=/usr/local/bin/pekwm
Icon= 
Type=Application

(If you have installed Pekwm to /usr/ (as mentioned above), change the Exec line to 'Exec=/usr/bin/pekwm')

Save and close the file and make the file executable with the following command:

sudo chmod +x /usr/share/xsessions/Pekwm.desktop

When you restart your computer, you will be able to choose Pekwm in the sessions menu (which is accessed with F10 > Sessions if you use GDM or KDM, the default login manager of (X)Ubuntu and Kubuntu respectively).

If you don't use a session manager, edit your ~/.xinitrc file (create one if you don't have one already), so that it looks something like this:

#!/bin/sh
xsetroot -solid black &

exec /usr/local/bin/pekwm

If you have installed Pekwm to /usr/ (as mentioned above), change the exec line to 'exec /usr/bin/pekwm'. When you start X with the command startx you will start a new Pekwm session.

4. Pekwm basics

When you first log into Pekwm, you won't see much apart from a blank screen. This is normal. Pekwm doesn't come with a panel, or a desktop manager. Pekwm is fairly straightforward. It is a window manager, and does not much more than managing windows. Here are a few basics of Pekwm:

Windows

• Pekwm supports tabbed windows. You can group windows together by middle-clicking the titlebar of one window and dragging it to another window title. To group the next launched window with the current one, press the windows key + T to tag the current window. Until untagged with the same command, all new windows will be opened as tabs within that window.
  
• Apart from maximizing, windows can also 'fill' in Pekwm: they will grow (either vertically, horizontally or both) until they reach another window border or an edge of the screen.
  
• Every window can be stripped of their titlebar or their borders or both.

Menus

• Pekwm comes with several menus. You have the root menu, which is editable and generally contains entries to launch your applications. There is a active window menu (the GoTo menu), which contains a list of all active windows on all workspaces. The GoToClient menu list all active windows with their tabs. The Icon menu lists the iconified windows.
  
• Right click on the desktop, and you'll have your root menu. Middle click and you have the active window menu. You can also click on the screen edges to call up these menus, which means you don't have to iconify all windows to use the menu.
  
• To see the Icon menu, press Windows key+Shift+I, to use the GoToClient menu, press Windows key+C

Other

• Pekwm does not come with any panels, pagers, system trays. It does have a 'harbour', where you can load dockapps, and which is similar to (though less developed than) the slit of Fluxbox or the dock of Openbox. The order in which the dockapps are loaded can be specified in the autoproperties file (see below).
  
• Pekwm has a command dialog, which can be launched by pressing the Windows key + D. It can be used to execute commands to launch applications, but also to performs Pekwm actions. For a list of actions, see here.

5. Configuring Pekwm

All of Pekwm's configuration happens in the ~/.pekwm directory. In there you will find 7 files: config, menu, keys, mouse, autoproperties, start, and vars.

There are no graphical tools to change the settings in these files (apart from a text editor ). Any changes you make to these files will not be applied until you reconfigure (in the root menu) or restart Pekwm.

In case you accidentally delete these files, the defaults can be found at /usr/local/etc/pekwm

Config
This is the general configuration file. Here you can control the basic behaviour of Pekwm. It controls the workspace settings, the menu and harbour behaviour, window edge resistance, and more. The settings are very well explained in the official Pekwm documentation.

Menu
As you could have guessed, this is the file that controls your menu. You can edit this file to add, edit or remove entries or submenus to your root menu and (towards the end of the file) your window menu (the menu that pops up when you right click a window header). Any custom menu you'd like to setup will have to be added to this file.

When you first run Pekwm you will already have a rather full default menu, with possibly plenty of applications you don't have installed. It might be a useful basis to create your own menu. You could also run Menumaker to set up menus of all your installed applications. Run it with the following command:

mmaker --no-desktop pekwm

(Note that this will not overwrite your existing menu file. If you want it to overwrite, add the -f flag to the above command.


The syntax for the menu file is fairly straightforward. A simple entry has the following structure:

Entry = "NAME" { Actions = "Exec COMMAND &" }

A submenu has the following syntax:

Submenu = "NAME" {
				Entry = "NAME" { Actions = "Exec COMMAND &" }
                                Entry = "NAME" { Actions = "Exec COMMAND &" }
			}

(Make sure these brackets are always closed, or you will have errors and your menu will not display)

To add a separator line to the menu, use the following:

Separator {}

Pekwm also supports dynamic menus. These are basically menu entries or submenus that display the output of a script that is run every time the entry or submenu is accessed.

You can find some dynamic menus online. Check the exact syntax the menu requires, as they can vary. There are not that many dynamic menu scripts around, unfortunately. You can find dynamic menus for Gmail and network connections here, and one to display the time and date here.

Keys
This file controls all the keyboard bindings and keychains used in Pekwm. You can add keyboard bindings to launch programs or to perform actions in Pekwm, such as show a menu, move a window, switch desktops, etc. For a full list of Pekwm's actions, see the documentation.

The syntax structure of this file resembles that of the menu file and should be fairly self-evident. Mod1 is the Alt key, Mod4 the Windows key.

You can have more than one action assigned to one key combination. To do so, just separate the actions by a semicolon. Here is an example:

KeyPress = "Ctrl Mod1 R" { Actions = "Exec osdctl -s 'Reconfiguring'; Reload" }

When you press Ctrl+Alt+R Pekwm will display on the screen the text 'Reconfiguring' (osdctl -s 'Reconfiguring') and reconfigure (Reload). (Note that this requires osdsh to be installed)

Mouse
This file controls all the mouse actions used in Pekwm. For a full list of Pekwm's actions, see the documentation.

Pekwm is set up by default to focus windows when the mouse moves over them (as opposed to the 'click to focus' style). If you'd like to change this, look for the following lines in the file and do what they say (there are quite a few of the first, but only one occurrence of the second):

# Remove the following line if you want to use click to focus.
# Uncomment the following line if windows should raise when clicked.

For some ideas of what you can do with the Mouse and Keys file, have a look here.

Autoproperties
If you'd like certain applications to open on certain workspaces, have a certain title, skip the (window) menus, or be automatically tabbed together, you can specify all that here. The syntax is a little confusing at first, but it is well documented in the documentation and the default autoproperties file contains plenty of examples.

Start
This file is used to start applications when Pekwm is started. If you'd like to display a wallpaper or launch a panel whenever Pekwm is started, you can add entries for these things here. Note, though, that these applications are run every time Pekwm is started -- including when you run 'Restart' in the root menu. The commands are executed only after Pekwm is started.

To add an application, use the following structure:

nameofapplication &

The & at the end is crucial, or anything after it won't be run. To give you an idea of what this file could look like, here is an example:

# Auto-mounting drives 
gnome-volume-manager & 
# To set the background image
hsetroot -tile "/home/urukrama/Images/Desktops/Abandoned.jpg" &
fbpanel &
conky &
# To have visual feedback when changing the volume
osdsh & 
(sleep 1 && osdctl -m 1) &

Before you can use this file, you will have to make it executable with the following command:

chmod +x ~/.pekwm/start

Vars
Finally, the vars file contains variables that are applied throughout Pekwm. The default entry should be clear enough:

$TERM="xterm -fn fixed +sb -bg white -fg black"

Whenever the variable $TERM is used in any of Pekwm's configuration files, the command xterm -fn fixed +sb -bg white -fg black will be run.


6. Themes

Unlike some other window managers, Pekwm themes govern all visual aspects: window headers and borders, menus, the harbour, fonts, as well as the position and functions of window buttons (like close, iconify, etc.).

Themes are installed in ~/.pekwm/themes or /usr/local/share/pewkm/themes (/usr/share/pekwm/themes if you have changed the default installation directory). To install a theme, unpack the theme archive, and copy the folder that contains the 'theme' file and possibly image files to the above mentioned folders. The name of the theme folder is the name that will appear in the menu. You can change the theme also manually by editing the Pekwm config file (in the first section 'Files').

You can download pekwm themes from the following places:

• Box-look
• FreshMeat

The theme settings have changed in more recent versions of Pekwm, so themes written for older versions are most likely unusable. You'll be able to tell straight away whether a theme is broken or not.


7. Conclusion

Since Pekwm is just a window manager, it doesn't control the desktop, provide ways of changing Gtk settings such as themes, icons or fonts, manage the (un)mounting of devices, etc. Solutions to these are the same in Pekwm as in Fluxbox, Openbox or Icewm. If you need help with these, have a look at my Openbox guide, which discusses these at length.

Like Fluxbox and Openbox, Pekwm is small and light, but highly configurable. Explore its many potentials and find a setup that works for you.

For additional support of Pekwm read the documentation, join the mailing list, enter #pekwm at irc.freenode.net, or leave a message here on these forums.

[AndreiMe]

this is great... thanks alot... will surely play with it

[thyultimate]

that was amazingly well written and explained....kudos!!!

just installed it, will toy around and report back

[Iandefor]

A well-written introduction to PekWM. Thanks for this!

[strankan]

Great work mate!

I have a question and I think it has to do with PekWM. I use skype alot to communicate with my family. The problem is when i minimize skype to tray (and I have tried all available trays...) I can't get it to show again. It just doesn't appear when I click the icon. The weird thing is that Gajim works, amsn works, xchat works. It's just skype that doesn't want to play. It works with the exact same setup if I try openbox or fluxbox though. Do you have any idea what could be causing this?

Love PekWM, but without a working skype it's a no go for me

[mindepinde]

If you did everything right and can't login to the PekWM environment, i.e. after login you get the message "No Exec line in the session file: Pekwm.", here's the tip (took me half a day to figure out) to get it working:

- in the Pekwm.desktop file comment (use '#') the line with 'Encoding=UTF-8'. For some reason this line prevented the gdm finding the Exec line for me. Don't know why it is so, but it worked for me.

[urukrama]

Originally Posted by strankan Great work mate! I have a question and I think it has to do with PekWM. I use skype alot to communicate with my family. The problem is when i minimize skype to tray (and I have tried all available trays...) I can't get it to show again. It just doesn't appear when I click the icon. The weird thing is that Gajim works, amsn works, xchat works. It's just skype that doesn't want to play. It works with the exact same setup if I try openbox or fluxbox though. Do you have any idea what could be causing this? Love PekWM, but without a working skype it's a no go for me

I have no idea what might be causing that. I don't use Skype and (like you) have had no problem with other apps that have a tray icon.

Do you get any error messages if you launch Skype from the terminal when you try to make Skype appear again? Or could you post the contents of your ~/.xsession-errors here (after you've tried to make Skype reappear)?

[mossgarden]

Configure the package to make it ready to compile Now you have to compile the package. Open a terminal and navigate with the cd ('change directory') command to the directory where the unpacked archive is: Code: cd pekwm-0.1.6/ Then run the configure script to prepare the source for installation with the following command: Code: ./configure

I got this far when I was stopped by the error:

checking for X... no checking for XOpenDisplay in -lX11... no configure: error: Could not find XOpenDisplay in -lX11.

I'm not sure what this means?
(I installed the 0.1.5 version just using the sudo aptitude install pekwm, but naturally I would prefer the newest version :/)

EDIT: never mind, I found a solution

[urukrama]

Originally Posted by mossgarden EDIT: never mind, I found a solution

It might help others who have the same problem if you posted your solution here.

[njakol]

I had the same problem with:

checking for X... no checking for XOpenDisplay in -lX11... no configure: error: Could not find XOpenDisplay in -lX11.

but I found the solution here:
http://ubuntuforums.org/showthread.php?t=28400

i used:

apt-get build-dep pekwm

but you can also use auto-apt.