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     sed -i -e 's,^IXP_PREFIX.*,IXP_PREFIX = ${HOME}/usr,' config.mk
 103
 104     # build and install wmii-lua
 105     make install-user
 106
 107 B. Install system wide
 108
 109     # (optional) get the sources
 110     git clone git://github.com/bartman/wmii-lua.git
 111     cd wmii-lua
 112
 113     # (optional) configure where things go
 114     make config.mk
 115     vim config.mk
 116
 117     # (optional) build and install libixp and wmii
 118     make ext-update
 119     make ext
 120     sudo make ext-install
 121
 122     # Build wmii-lua as anyone
 123     make
 124
 125     # Installing software in system directories as root
 126     sudo make install
 127
 128     # Setting up $HOME for wmii-lua
 129     install-wmiirc-lua
 130
 131 C. Make a Debian package
 132
 133     # (optional) get the sources
 134     git clone git://github.com/bartman/wmii-lua.git
 135     cd wmii-lua
 136
 137     # Switch to the debian branch
 138     git checkout -b debian -t origin/debian
 139
 140     # Build the .deb
 141     make deb
 142
 143     # Install deb
 144     sudo debi
 145
 146     # Setting up $HOME for wmii-lua
 147     install-wmiirc-lua
 148
 149
 150 Running wmii
 151 ------------
 152 wmii-lua is now ready to run, but you still have to make wmii your
 153 window manager.  You can do this by running the wmii executable from
 154 .initrc or .xsession... your choice.
 155
 156     cat ~/.xinitrc
 157     wmii-lua
 158
 159 or
 160
 161     cat ~/.xsession
 162     exec wmii-lua
 163
 164 Note: the base configuration uses Mod4 -- the windows key on PC
 165 keyboards -- for some of the binding.  If your keyboard, like my
 166 Thinkpad's, does not have a windows key you can "make one" with
 167 xmodmaprc.  See: contrib/remap-caps-ctrl-mod4
 168
 169 Configuration
 170 -------------
 171 All configuration of wmii-lua is done by editing the ~/.wmii-lua/wmiirc
 172 file.  See doc/configuration for more help on configuring wmii-lua.
 173
 174 wmii-lua supports all the keyboard shortcuts of wmii's shell wmiirc,
 175 some of the features of wmii+ruby, as well as some additional ones.  See
 176 the doc/key-bindings for information on how to control wmii with the
 177 extended key bindings wmii-lua provides.
 178
 179 More advanced users may also write plugins for wmii-lua using the
 180 plugin API.  Plugins live in ~/.wmii-lua/plugins/ directory, and several
 181 come with this package.  See the wmii.3lua man page, and doc/plugin-api
 182 for more information about how to write code for wmii-lua.
 183
 184     make man
 185     man ./wmii.3lua
 186
 187
 188 Credits
 189 -------
 190 The following people have contributed especially to wmii-lua in
 191 various ways.  They are copyright holders of their respective
 192 contributions.
 193
 194 - Bart Trojanowski <bart@jukie.net>
 195 - Dave O'Neill
 196 - Jean Richard
 197 - David Leadbeater
 198 - Jan-David Quesel
 199 - Stefan Riegler
 200 - Sytse Wielinga
 201
 202
 203 Credits
 204 -------
 205 wmii-lua is licensed under GPLv2.
 206
 207 References
 208 ----------
 209 [1] http://www.suckless.org/
 210 [2] http://www.cs.bell-labs.com/sys/man/5/INDEX.html
 211 [3] http://www.jukie.net/~bart/blog/wmiirc-in-lua
 212 [4] http://www.linuxpowertop.org
 213 # vim:set ft=mkd: