README

   1 wmii-lua copyright (c) 2007 Bart Trojanowski <bart@jukie.net>
   2
   3                    website - http://www.jukie.net/~bart/blog/tag/wmiirc-lua
   4                        irc - #wmiirc-lua on oftc.net
   5                      email - http://groups.google.ca/group/wmii-lua
   6                     source - http://github.com/bartman/wmii-lua
   7
   8 Abstract
   9 --------
  10 wmii [1], window manager improved-improved, is a dynamic window manager
  11 for X11.  It supports classic and tiled window management with extended
  12 keyboard, mouse, and 9P-based [2] remote control.
  13
  14 wmii-lua [3] implements an "event loop" script for the wmii window
  15 manager.  The goals of the project are to
  16
  17  - be fast, small, feature rich, and extensible through plugins,
  18  - avoid threading and polling at all costs, and
  19  - replicate the functionality of wmii+ruby.
  20
  21 As the name suggests the script is written in Lua.  Before writing it I
  22 was a happy user of wmii+ruby.  Happy, until powertop [4] was written.
  23 Powertop told me that ruby was the number 1 reason my battery life
  24 sucked.  I chose lua because it helps me achieve the first and second
  25 goals.
  26
  27
  28 Requirements for wmii-lua
  29 -------------------------
  30 The following are required to build wmii-lua project:
  31
  32  - lua5.1
  33  - liblua5.1
  34  - liblua5.1-posix0
  35  - patience (no, it's not a package)
  36
  37 Naturally, wmii-lua depends on wmii.  It also depends on libixp, which
  38 is used to communicate with wmii.  Both of these projects come from
  39 suskless.org and are tracked upstream using mercurial.  You are free
  40 chose how you wish to get libixp and wmii:
  41
  42  - from your distribution
  43  - from wmii-lua's extra packages
  44  - from suckless.org's mercurial repositories
  45
  46 Your distribution may have upto date libixp and wmii.  Great.
  47
  48 The easiest way to build libixp and wmii from source is to use the git
  49 submodules of this repository.  But that assumes that you have received
  50 this project in a form of a git repository from the above URL.  More on
  51 this under "building" below.
  52
  53
  54 Installing prerequisites
  55 ------------------------
  56 If you are running Debian (or derivative) these steps may help you:
  57
  58     apt-get install git-core                                \
  59                     build-essential debhelper               \
  60                     libx11-dev libxext-dev libxt-dev        \
  61                     libxrandr-dev libxinerama-dev           \
  62                     lua5.1 liblua5.1-0-dev                  \
  63                     liblua5.1-posix1-dev                    \
  64                     dwm-tools xclip dstat pkg-config
  65
  66 Note that liblua5.1-posix1 may actually be liblua5.1-posix0 or someother
  67 suffix.  Please check what's available on your platform.
  68
  69     apt-get build-dep libixp wmii
  70
  71 Note that you will need *deb-src* lines in your `/etc/apt/source` config
  72 file.  Without the build-dep will not work.
  73
  74 If you chose to work on plugins, you can install all lua packages
  75 like this:
  76
  77     apt-cache search lua5.1 | awk '/liblua5.1/ { print $1 }' \
  78     | xargs sudo apt-get install -y
  79
  80
  81 Building & Installation
  82 -----------------------
  83 Now that you have the prerequisites installed, you can choose one of the
  84 following three options.
  85
  86 A. Install in $HOME only
  87
  88   This method installs wmii-lua in ~/usr and ~/.wmii-lua only.  Ther is
  89   no need for super user privileges.
  90
  91     # (optional) get the sources
  92     git clone git://github.com/bartman/wmii-lua.git
  93     cd wmii-lua
  94
  95     # (optional) configure where things go
  96     make config.mk
  97     vim config.mk
  98
  99     # (optional) build and install libixp and wmii
 100     make ext-update
 101     make ext-install-user
 102
 103     # build and install wmii-lua
 104     make install-user
 105
 106 B. Install system wide
 107
 108     # (optional) get the sources
 109     git clone git://github.com/bartman/wmii-lua.git
 110     cd wmii-lua
 111
 112     # (optional) configure where things go
 113     make config.mk
 114     vim config.mk
 115
 116     # (optional) build and install libixp and wmii
 117     make ext-update
 118     make ext
 119     sudo make ext-install
 120
 121     # Build wmii-lua as anyone
 122     make
 123
 124     # Installing software in system directories as root
 125     sudo make install
 126
 127     # Setting up $HOME for wmii-lua
 128     install-wmiirc-lua
 129
 130 C. Make a Debian package
 131
 132     # (optional) get the sources
 133     git clone git://github.com/bartman/wmii-lua.git
 134     cd wmii-lua
 135
 136     # Switch to the debian branch
 137     git checkout -b debian -t origin/debian
 138
 139     # Build the .deb
 140     make deb
 141
 142     # Install deb
 143     sudo debi
 144
 145     # Setting up $HOME for wmii-lua
 146     install-wmiirc-lua
 147
 148
 149 Running wmii
 150 ------------
 151 wmii-lua is now ready to run, but you still have to make wmii your
 152 window manager.  You can do this by running the wmii executable from
 153 .initrc or .xsession... your choice.
 154
 155     cat ~/.xinitrc
 156     wmii-lua
 157
 158 or
 159
 160     cat ~/.xsession
 161     exec wmii-lua
 162
 163 Note: the base configuration uses Mod4 -- the windows key on PC
 164 keyboards -- for some of the binding.  If your keyboard, like my
 165 Thinkpad's, does not have a windows key you can "make one" with
 166 xmodmaprc.  See: contrib/remap-caps-ctrl-mod4
 167
 168 Configuration
 169 -------------
 170 All configuration of wmii-lua is done by editing the ~/.wmii-lua/wmiirc
 171 file.  See doc/configuration for more help on configuring wmii-lua.
 172
 173 wmii-lua supports all the keyboard shortcuts of wmii's shell wmiirc,
 174 some of the features of wmii+ruby, as well as some additional ones.  See
 175 the doc/key-bindings for information on how to control wmii with the
 176 extended key bindings wmii-lua provides.
 177
 178 More advanced users may also write plugins for wmii-lua using the
 179 plugin API.  Plugins live in ~/.wmii-lua/plugins/ directory, and several
 180 come with this package.  See the wmii.3lua man page, and doc/plugin-api
 181 for more information about how to write code for wmii-lua.
 182
 183     make man
 184     man ./wmii.3lua
 185
 186
 187 Credits
 188 -------
 189 The following people have contributed especially to wmii-lua in
 190 various ways.  They are copyright holders of their respective
 191 contributions.
 192
 193 - Bart Trojanowski <bart@jukie.net>
 194 - Dave O'Neill
 195 - Jean Richard
 196 - David Leadbeater
 197 - Jan-David Quesel
 198 - Stefan Riegler
 199 - Sytse Wielinga
 200
 201
 202 Credits
 203 -------
 204 wmii-lua is licensed under GPLv2.
 205
 206 References
 207 ----------
 208 [1] http://www.suckless.org/
 209 [2] http://www.cs.bell-labs.com/sys/man/5/INDEX.html
 210 [3] http://www.jukie.net/~bart/blog/wmiirc-in-lua
 211 [4] http://www.linuxpowertop.org
 212 # vim:set ft=mkd: