1[(Basic Usage) Next >](basic-usage.md)
2
3***
4
5An overview of pekwm
6====================
7
8pekwm is a fast, functional, and flexible window manager which aims to
9be usable, even without a mouse.
10
11**Table of Contents**
12
131. [An Introduction to pekwm](#an-introduction-to-pekwm)
141. [Getting pekwm](#getting-pekwm)
151. [Compiling pekwm](#compiling-pekwm)
16
17An Introduction to pekwm
18------------------------
19
20pekwm, a window manager written by Claes Nästén that was once based on
21the aewm++ window manager, but has since evolved enough that it no
22longer resembles aewm++ at all. It also has an expanded feature-set,
23including window grouping (similar to ion, pwm, or fluxbox), auto
24properties, Xinerama support and keygrabber that supports keychains,
25and much more.
26
27### Why pekwm?
28
29"Why make another window manager?", some ask. This may confuse some
30people, but the best answer is "Why not?". There are arguments out
31there that it's better to have a single standard desktop environment,
32so that our mothers can find their way around, but in all honestly, if
33most of us wanted the same environment as our mothers, we probably
34wouldn't be reading this anyway. The same can also be applied to Your
35sister, your roommate, your wife, even your cat.
36
37"Why should I use pekwm?", others ask. Nobody ever said you
38should. However, we use it. And you're welcome to as well. You should
39use the environment most suited to you. For a better answer to this
40question, Check out the [pekwm Features](#pekwm-features)
41section below.
42
43### pekwm Features
44
45Here's a short list of some of the features included in pekwm:
46
47- Possibility to group windows in a single frame
48- Configurable keygrabber that supports keychains
49- Configurable mouse actions
50- Configurable root- and window-menus and keybindings for all menus
51- Dynamic menus that regenerate on every view from a script output
52- Multi-screen support both via RandR and Xinerama
53- Configurable window placement
54- Theming support with images, shaping and configurable buttons.
55- Autoproperties (Automatic properties such as a window's sticky state, etc.)
56
57
58Getting pekwm
59-------------
60
61Now that you've decided to try it out, you need to get it. You're left
62with two options. The first is to download and compile the source, and
63the second is finding a pre-compiled package.
64
65### Getting the pekwm source
66
67The source code is available from Github at https://github.com/pekdon/pekwm.
68
69Release tabralls are named pekwm-0.2.0.tar.gz and
70pekwm-0.2.0.tar.bz2. Although it doesn't matter which you get, keep in
71mind that the .bz2 is smaller.
72
73Generally pekwm from GIT is stable enough for everyday use and should
74in most cases be a safe bet to get all the latest functionality.
75
76### Getting prebuilt pekwm packages
77
78pekwm is available as a package on many Linux and BSD distributions,
79see your distribution for details.
80
81Compiling pekwm
82---------------
83
84This chapter will help you get pekwm compiled.
85
86### Unpacking the Archive
87
88The first step to compiling pekwm is to unpack the archive. Unpacking
89it depends on which version you downloaded:
90
91```
92tar -zxvf pekwm-0.2.0.tar.gz
93tar -zjvf pekwm-0.2.0.tar.bz2
94```
95
96> The '-j' option works normally on most linux systems, and as of the
97> current GNU tar development version, is part of GNU tar. If your
98> system does not support the -j option, you can use two things:
99> **bzip2 -dc pekwm-0.2.0.tar.bz2 | tar -xvf -** or **bzip2 -d
100> pekwm-0.2.0.tar.bz2** followed by **tar -xvf pekwm-0.2.0.tar**. This
101> also works for the .tar.gz version using **gzip -dc** or **gzip
102> -d**.
103
104The 'v' options are optional, they show you the filenames as they're
105being extracted. at this point, you should have a pekwm-0.2.0
106directory. Use **cd pekwm-0.2.0** to get there.
107
108### Installing build dependencies
109
110Before building pekwm a C++ compiler with support for C++11 needs to
111be available on the system, the CMake build system and a set of X11
112and image libraries.
113
114The below sections details how to install the required packages for
115different OSes and Linux distributions.
116
117#### Alpine
118
119Development tools using the GCC C++ compiler:
120
121```
122# apk add cmake g++ make
123```
124
125Build dependencies:
126
127```
128# apk add fontconfig-dev jpeg-dev libxext-dev libpng-dev libxft-dev libxpm-dev libxrandr-dev libxinerama-dev
129```
130
131#### Debian
132
133Development tools using the GCC C++ compiler:
134
135```
136# apt install cmake g++ make
137```
138
139Build dependencies:
140
141```
142# apt install libfontconfig1-dev libjpeg-dev libxext-dev libpng-dev libxft-dev libxpm-dev libxrandr-dev libxinerama-dev
143```
144
145#### Void
146
147Development tools using the GCC C++ compiler:
148
149```
150# xbps-install cmake make gcc
151```
152
153Build dependencies:
154
155```
156# xbps-install fontconfig-devel libjpeg-turbo-devel libXext-devel libpng-devel libXft-devel libXpm-devel libXrandr-devel libXinerama-devel
157```
158
159#### OpenBSD
160
161OpenBSD comes with X11 and a compatible C++ compiler. To add the
162required packages run:
163
164```
165# pkg_add cmake jpeg png
166```
167
168#### OS X (homebrew)
169
170OS X does not come with a X11 installation by default so first
171[XQuartz](https://www.xquartz.org/) needs to be installed.
172
173The development tools are not installed by default but can be
174installed using the following command:
175
176```
177xcode-select --install
178```
179
180Assuming homebrew is installed, the only package required to build
181pekwm after install XQuartz and the development tools is CMake:
182
183```
184$ brew install cmake
185```
186
187### Setting up a build directory
188
189The first thing to do is to setup a build directory and configure
190pekwm using CMake:
191
192```
193mkdir build && cd build
194cmake ..
195```
196
197Pekwm support a few configuration options, each option is specified on
198the cmake command line as:
199
200```
201-DOPTION=ON
202```
203
204
205### Common options
206
207| Option               | Default    | Description                                                   |
208|----------------------|------------|---------------------------------------------------------------|
209| CMAKE_INSTALL_PREFIX      | /usr/local       | It may be useful to use a custom prefix to install the files. |
210| CMAKE_INSTALL_SYSCONFDIR | /usr/etc/pekwm | It may be useful to use a custom prefix to install the config files. |
211| CMAKE_BUILD_TYPE         |                | Set to Debug to enable debug outputs and code                 |
212| PEDANTIC                 | OFF              | Turn on extra compiler warnings                               |
213| TESTS                    | OFF              | Enable compilation of unit test programs                      |
214
215### Options to reduce the size
216
217| Option            | Default | Description                                                          |
218|-------------------|---------|----------------------------------------------------------------------|
219| ENABLE_SHAPE      | ON      | Enables the use of the Xshape extension for non-rectangular windows. |
220| ENABLE_XINERAMA   | ON      | Enables Xinerama multi screen support                                |
221| ENABLE_RANDR      | ON      | Enables RandR multi screen support                                   |
222| ENABLE_XFT        | ON      | Enables Xft font support in pekwm (themes).                          |
223| ENABLE_IMAGE_XPM  | ON      | XPM image support using libXpm.                                      |
224| ENABLE_IMAGE_JPEG | ON      | JPEG image support using libjpeg.                                    |
225| ENABLE_IMAGE_PNG  | ON      | PNG image support using libpng.                                      |
226
227### Building and installing
228
229After running cmake with any configuration options you need, run **make**.
230This should only take a few minutes. After that, become root (unless you
231used a prefix in your home directory, such as
232-DCMAKE_INSTALL_PREFIX=/home/you/pkg) and type **make install**
233
234Adding **exec pekwm** to ~/.xinitrc if you start X running **startx**
235or ~/.xsession if you use a display manager should usually be enough
236to get pekwm running.
237
238That's it! pekwm is installed on your computer now. Next you should
239read the [Getting Started](basic-usage.md#getting-started) chapter.
240
241***
242
243[(Basic Usage) Next >](basic-usage.md)
244