README

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