.gitignore update

[wmiirc-lua.git] / README

wmii-lua copyright (c) 2007 Bart Trojanowski <bart@jukie.net>

                   website - http://www.jukie.net/~bart/blog/tag/wmiirc-lua
                       irc - #wmiirc-lua on oftc.net
                     email - http://groups.google.ca/group/wmii-lua
                    source - http://github.com/bartman/wmii-lua

Abstract
--------
wmii [1], window manager improved-improved, is a dynamic window manager
for X11.  It supports classic and tiled window management with extended
keyboard, mouse, and 9P-based [2] remote control.

wmii-lua [3] implements an "event loop" script for the wmii window
manager.  The goals of the project are to

 - be fast, small, feature rich, and extensible through plugins,
 - avoid threading and polling at all costs, and
 - replicate the functionality of wmii+ruby.

As the name suggests the script is written in Lua.  Before writing it I
was a happy user of wmii+ruby.  Happy, until powertop [4] was written.
Powertop told me that ruby was the number 1 reason my battery life
sucked.  I chose lua because it helps me achieve the first and second
goals.


Requirements for wmii-lua
-------------------------
The following are required to build wmii-lua project:

 - lua5.1
 - liblua5.1
 - liblua5.1-posix0
 - patience (no, it's not a package)

Naturally, wmii-lua depends on wmii.  It also depends on libixp, which
is used to communicate with wmii.  Both of these projects come from
suskless.org and are tracked upstream using mercurial.  You are free
chose how you wish to get libixp and wmii:

 - from your distribution
 - from wmii-lua's extra packages
 - from suckless.org's mercurial repositories

Your distribution may have upto date libixp and wmii.  Great.

The easiest way to build libixp and wmii from source is to use the git
submodules of this repository.  But that assumes that you have received
this project in a form of a git repository from the above URL.  More on
this under "building" below.


Installing prerequisites
------------------------
If you are running Debian (or derivative) these steps may help you:

    apt-get install git-core                                \
                    build-essential debhelper               \
                    libx11-dev libxext-dev libxt-dev        \
                    lua5.1 liblua5.1-0-dev liblua5.1-posix0 \
                    dwm-tools xclip dstat pkg-config

    apt-get build-dep libixp wmii

If you chose to work on plugins, you can install all lua packages
like this:

    apt-cache search lua5.1 | awk '/liblua5.1/ { print $1 }' \
    | xargs sudo apt-get install -y


Building & Installation
-----------------------
Now that you have the prerequisites installed, you can choose one of the
following three options.

A. Install in $HOME only

  This method installs wmii-lua in ~/usr and ~/.wmii-lua only.  Ther is
  no need for super user privileges.

    # (optional) get the sources
    git clone git://github.com/bartman/wmii-lua.git
    cd wmii-lua

    # (optional) configure where things go
    make config.mk
    vim config.mk

    # (optional) build and install libixp and wmii
    make ext-update
    make ext-install-user

    # build and install wmii-lua
    make install-user

B. Install system wide

    # (optional) get the sources
    git clone git://github.com/bartman/wmii-lua.git
    cd wmii-lua

    # (optional) configure where things go
    make config.mk
    vim config.mk

    # (optional) build and install libixp and wmii
    make ext-update
    make ext
    sudo make ext-install

    # Build wmii-lua as anyone
    make

    # Installing software in system directories as root
    sudo make install

    # Setting up $HOME for wmii-lua
    install-wmiirc-lua

C. Make a Debian package

    # (optional) get the sources
    git clone git://github.com/bartman/wmii-lua.git
    cd wmii-lua

    # Switch to the debian branch
    git checkout debian

    # Build the .deb
    make deb

    # Install deb
    sudo debi

    # Setting up $HOME for wmii-lua
    install-wmiirc-lua


Running wmii
------------
wmii-lua is now ready to run, but you still have to make wmii your
window manager.  You can do this by running the wmii executable from
.initrc or .xsession... your choice.

    cat ~/.xinitrc
    wmii-lua

or

    cat ~/.xsession
    exec wmii-lua

Note: the base configuration uses Mod4 -- the windows key on PC
keyboards -- for some of the binding.  If your keyboard, like my
Thinkpad's, does not have a windows key you can "make one" with
xmodmaprc.  See: contrib/remap-caps-ctrl-mod4

Configuration
-------------
All configuration of wmii-lua is done by editing the ~/.wmii-lua/wmiirc
file.  See doc/configuration for more help on configuring wmii-lua.

wmii-lua supports all the keyboard shortcuts of wmii's shell wmiirc,
some of the features of wmii+ruby, as well as some additional ones.  See
the doc/key-bindings for information on how to control wmii with the
extended key bindings wmii-lua provides.

More advanced users may also write plugins for wmii-lua using the
plugin API.  Plugins live in ~/.wmii-lua/plugins/ directory, and several
come with this package.  See the wmii.3lua man page, and doc/plugin-api
for more information about how to write code for wmii-lua.

    make man
    man ./wmii.3lua


Credits
-------
The following people have contributed especially to wmii-lua in
various ways.  They are copyright holders of their respective
contributions.

- Bart Trojanowski <bart@jukie.net>
- Dave O'Neill
- Jean Richard
- David Leadbeater
- Jan-David Quesel
- Stefan Riegler 
- Sytse Wielinga 


Credits
-------
wmii-lua is licensed under GPLv2.

References
----------
[1] http://www.suckless.org/
[2] http://www.cs.bell-labs.com/sys/man/5/INDEX.html 
[3] http://www.jukie.net/~bart/blog/wmiirc-in-lua
[4] http://www.linuxpowertop.org
# vim:set ft=mkd: