README

   1 wmiirc-lua copyright (c) 2007 Bart Trojanowski <bart@jukie.net>
   2
   3                    website - http://www.jukie.net/~bart/blog/wmiirc-in-lua
   4                        irc - #wmiirc-lua on oftc.net
   5
   6 Abstract
   7 --------
   8 wmii [1], window manager improved-improved, is a dynamic window manager
   9 for X11.  It supports classic and tiled window management with extended
  10 keyboard, mouse, and 9P-based [2] remote control.
  11
  12 wmiirc-lua [3] implements an "event loop" script for the wmii window
  13 manager.  The goals of the project are to
  14
  15  - be fast, small, feature rich, and extensible through plugins,
  16  - avoid threading and polling at all costs, and
  17  - replicate the functionality of wmii+ruby.
  18
  19 As the name suggests the script is written in Lua.  Before writing it I
  20 was a happy user of wmii+ruby.  Happy, until powertop [4] was written.
  21 Powertop told me that ruby was the number 1 reason my battery life
  22 sucked.  I chose lua because it helps me achieve the first and second
  23 goals.
  24
  25
  26 Requirements
  27 ------------
  28 The following are required to build wmiirc-lua project:
  29
  30  - wmii, 3.5+ or whatever is in hg at the moment
  31  - libixp, latest
  32  - lua5.1
  33  - liblua5.1
  34  - liblua5.1-posix0
  35  - patience (no, it's not a package)
  36
  37 Note that as of version 0.2 wmiirc-lua is tracking wmii project closely,
  38 and we don't officially support anything older then wmii from the hg
  39 (mercurial) repository.
  40
  41
  42 Building prerequisites
  43 ----------------------
  44 If you are running Debian (or derivative) these steps may help you:
  45
  46  1) install Debian packages that you need to build
  47
  48     apt-get install mercurial git-core                      \
  49                     build-essential debhelper               \
  50                     libx11-dev libxext-dev libxt-dev        \
  51                     lua5.1 liblua5.1-0-dev liblua5.1-posix0
  52
  53     If you chose to work on plugins, you can install all lua packages
  54     like this:
  55
  56        apt-cache search lua5.1 | awk '/liblua5.1/ { print $1 }' \
  57        | xargs sudo apt-get install -y
  58
  59  2) build libixp and wmii from source:
  60
  61     hg clone http://suckless.org/hg.rc/libixp
  62     cd libixp
  63     make
  64     sudo make install
  65     cd ..
  66
  67     hg clone http://suckless.org/hg.rc/wmii
  68     cd wmii
  69     make
  70     sudo make install
  71     cd ..
  72
  73
  74 Installation
  75 ------------
  76 Now that you have the prerequisites installed, you can choose one of the
  77 following options.
  78
  79  A. Make a Debian package
  80
  81     A.1. build the actual DEB
  82
  83         # get the sources, switch to debian branch
  84         git clone git://repo.or.cz/wmiirc-lua.git/
  85         cd wmiirc-lua
  86         git checkout debian
  87
  88         make deb
  89
  90     A.2. install deb
  91
  92         sudo debi
  93
  94     A.3. Setting up $HOME for wmiirc-lua
  95
  96         # as the user run
  97         install-wmiirc-lua
  98
  99  B. Install system wide, and in $HOME
 100
 101     B.1. get the sources
 102
 103         # (optional) get the sources
 104         git clone git://repo.or.cz/wmiirc-lua.git/
 105         cd wmiirc-lua
 106
 107         # (optional) configure where things go
 108         vim config.mk
 109
 110     B.2. Installing software in shared directories
 111
 112         # build as anyone
 113         make
 114
 115         # install system-wide as root
 116         make install
 117
 118     B.3. Setting up $HOME for wmiirc-lua
 119
 120         # as the user run
 121         install-wmiirc-lua
 122
 123  C. Install in $HOME only
 124
 125     # (optional) get the sources
 126     git clone git://repo.or.cz/wmiirc-lua.git/
 127     cd wmiirc-lua
 128
 129     make install-user
 130
 131
 132 Running wmii
 133 ------------
 134 wmiirc-lua is now ready to run, but you still have to make wmii your
 135 window manager.  You can do this by running the wmii executable from
 136 .initrc or .xsession... your choice.
 137
 138     cat ~/.xinitrc
 139     wmii
 140
 141 or
 142
 143     cat ~/.xsession
 144     exec wmii
 145
 146 Note: the base configuration uses Mod4 -- the windows key on PC
 147 keyboards -- for some of the binding.  If your keyboard, like my
 148 Thinkpad's, does not have a windows key you can "make one" with
 149 xmodmaprc.  See: contrib/remap-caps-ctrl-mod4
 150
 151 Configuration
 152 -------------
 153 All configuration of wmiirc-lua is done by editing the
 154 ~/.wmii-3.5/wmiirc file.  See doc/configuration for more help on configuring
 155 wmiirc-lua.
 156
 157 wmiirc-lua supports all the keyboard shortcuts of wmii's shell wmiirc,
 158 some of the features of wmii+ruby, as well as some additional ones.  See
 159 the doc/key-bindings for information on how to control wmii with the
 160 extended key bindings wmiirc-lua provides.
 161
 162 More advanced users may also write plugins for wmiirc-lua using the
 163 plugin API.  Plugins live in ~/.wmii-3.5/plugins/ directory, and several
 164 come with this package.  See the wmii.3lua man page, and doc/plugin-api
 165 for more information about how to write code for wmiirc-lua.
 166
 167     make man
 168     man ./wmii.3lua
 169
 170
 171 Credits
 172 -------
 173 The following people have contributed especially to wmiirc-lua in
 174 various ways.  They are copyright holders of their respective
 175 contributions.
 176
 177 - Bart Trojanowski <bart@jukie.net>
 178 - Dave O'Neill <dmo@dmo.ca>
 179 - Jean Richard <jean@geemoo.ca>
 180
 181
 182 Credits
 183 -------
 184 wmiirc-lua is licensed under GPLv2.
 185
 186 References
 187 ----------
 188 [1] http://www.suckless.org/
 189 [2] http://www.cs.bell-labs.com/sys/man/5/INDEX.html
 190 [3] http://www.jukie.net/~bart/blog/wmiirc-in-lua
 191 [4] http://www.linuxpowertop.org