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                     dwm-tools xclip dstat
  53
  54     If you chose to work on plugins, you can install all lua packages
  55     like this:
  56
  57        apt-cache search lua5.1 | awk '/liblua5.1/ { print $1 }' \
  58        | xargs sudo apt-get install -y
  59
  60  2) build libixp and wmii from source:
  61
  62     hg clone http://suckless.org/hg.rc/libixp
  63     cd libixp
  64     make
  65     sudo make install
  66     cd ..
  67
  68     hg clone http://suckless.org/hg.rc/wmii
  69     cd wmii
  70     make
  71     sudo make install
  72     cd ..
  73
  74
  75 Installation
  76 ------------
  77 Now that you have the prerequisites installed, you can choose one of the
  78 following options.
  79
  80  A. Make a Debian package
  81
  82     A.1. build the actual DEB
  83
  84         # get the sources, switch to debian branch
  85         git clone git://repo.or.cz/wmiirc-lua.git/
  86         cd wmiirc-lua
  87         git checkout debian
  88
  89         make deb
  90
  91     A.2. install deb
  92
  93         sudo debi
  94
  95     A.3. Setting up $HOME for wmiirc-lua
  96
  97         # as the user run
  98         install-wmiirc-lua
  99
 100  B. Install system wide, and in $HOME
 101
 102     B.1. get the sources
 103
 104         # (optional) get the sources
 105         git clone git://repo.or.cz/wmiirc-lua.git/
 106         cd wmiirc-lua
 107
 108         # (optional) configure where things go
 109         vim config.mk
 110
 111     B.2. Installing software in shared directories
 112
 113         # build as anyone
 114         make
 115
 116         # install system-wide as root
 117         make install
 118
 119     B.3. Setting up $HOME for wmiirc-lua
 120
 121         # as the user run
 122         install-wmiirc-lua
 123
 124  C. Install in $HOME only
 125
 126     # (optional) get the sources
 127     git clone git://repo.or.cz/wmiirc-lua.git/
 128     cd wmiirc-lua
 129
 130     make install-user
 131
 132
 133 Running wmii
 134 ------------
 135 wmiirc-lua is now ready to run, but you still have to make wmii your
 136 window manager.  You can do this by running the wmii executable from
 137 .initrc or .xsession... your choice.
 138
 139     cat ~/.xinitrc
 140     wmii
 141
 142 or
 143
 144     cat ~/.xsession
 145     exec wmii
 146
 147 Note: the base configuration uses Mod4 -- the windows key on PC
 148 keyboards -- for some of the binding.  If your keyboard, like my
 149 Thinkpad's, does not have a windows key you can "make one" with
 150 xmodmaprc.  See: contrib/remap-caps-ctrl-mod4
 151
 152 Configuration
 153 -------------
 154 All configuration of wmiirc-lua is done by editing the
 155 ~/.wmii-3.5/wmiirc file.  See doc/configuration for more help on configuring
 156 wmiirc-lua.
 157
 158 wmiirc-lua supports all the keyboard shortcuts of wmii's shell wmiirc,
 159 some of the features of wmii+ruby, as well as some additional ones.  See
 160 the doc/key-bindings for information on how to control wmii with the
 161 extended key bindings wmiirc-lua provides.
 162
 163 More advanced users may also write plugins for wmiirc-lua using the
 164 plugin API.  Plugins live in ~/.wmii-3.5/plugins/ directory, and several
 165 come with this package.  See the wmii.3lua man page, and doc/plugin-api
 166 for more information about how to write code for wmiirc-lua.
 167
 168     make man
 169     man ./wmii.3lua
 170
 171
 172 Credits
 173 -------
 174 The following people have contributed especially to wmiirc-lua in
 175 various ways.  They are copyright holders of their respective
 176 contributions.
 177
 178 - Bart Trojanowski <bart@jukie.net>
 179 - Dave O'Neill <dmo@dmo.ca>
 180 - Jean Richard <jean@geemoo.ca>
 181
 182
 183 Credits
 184 -------
 185 wmiirc-lua is licensed under GPLv2.
 186
 187 References
 188 ----------
 189 [1] http://www.suckless.org/
 190 [2] http://www.cs.bell-labs.com/sys/man/5/INDEX.html
 191 [3] http://www.jukie.net/~bart/blog/wmiirc-in-lua
 192 [4] http://www.linuxpowertop.org