Building and Testing HOWTO

Eventually, the goal is to have Minx integrate well with different package management systems. When that happens, getting Minx working should be a fairly automated procedure. However, in these early days of development, the process is a bit of a slog...

Prerequisites

You will need the following software to be able to grab Minx's source code, build its C++ component (viz., minxlib), and then run the window manager:

Software	Debian/Ubuntu Package	FreeBSD Package	Comments
Fossil	`fossil`	`devel/fossil`
CMake	`cmake`	`devel/cmake`
Boost	`libboost-all-dev`	`devel/boost-all` `devel/boost-python-libs`
Python	installed by above	installed by above (?)
Xephyr	`xserver-xephyr`	`x11-servers/xephyr`
Xdmx	`xdmx`	`x11-servers/xorg-dmx`	Optional (if you want to test multi-monitor setup)
Doxygen	`doxygen`	`devel/doxygen`	Optional (if you want to build API documentation)

In the above table, the package names are valid for a recent Debian-based system (e.g., Debian squeeze, Ubuntu 12.04). You should be able to simply apt-get install the above packages to pull in the necessary dependencies.

For a recent FreeBSD system, the package names are all relative to /usr/ports. You should be able to install the packages using one of the following:

pkg_add
make ; make install
portmaster
whatever other package management facilites exist on FreeBSD

Personally, I use portmaster.

Get the Code

Before you can check-out the source code, you will have to create a directory where the Minx Fossil repository can be stored and another for the working copy:

    cd
    mkdir fossil minx

Now, you can clone the Minx repository and check-out the sources:

    fossil clone http://chiselapp.com/user/minxdude/repository/minx \
                 fossil/minx.fossil
    cd minx
    fossil open ~/fossil/minx.fossil
    fossil update rel1.x

At this point, you should have the Minx sources in ~/minx. You should see at least these two subdirectories: minxlib and core. The former contains the C++ part of Minx, the latter has the Python code.

Build minxlib

The top-level directory has a script named mk for building minxlib and the API documentation. So, assuming you are in ~/minx, all you should need to do is:

    ./mk

And, if you want to build the API documentation:

    ./mk doc

But note that the rel1.x branch already has the API documentation checked in to the repository. So you really shouldn't need to build the documentation.

Configure Minx

Minx is actually a Python library that allows you to write your own tiling window manager. Thus, there is no command to start Minx. Rather, you write a small Python program that loads Minx and starts the window manager.

You can put the above-mentioned program wherever you like. Here, we will assume it goes to ~/.minx/init.py. So, fire up your favourite editor and add the following content to ~/.minx/init.py:

    #!/usr/bin/env python

    import os, sys
    sys.path.append(os.path.join(os.environ['HOME']))

    import minx
    minx.core.wm().start()

After saving the above file, make it executable:

    chmod +x ~/.minx/init.py

That's it, we're now ready to put Minx through its paces...

Test-drive Minx

Single Monitor

Currently, Minx is very far from being ready for prime-time. All it does is allow you to switch input focus from one top-level window to another. So don't edit your ~/.xinitrc and restart X just yet! Instead, run Xephyr:

    Xephyr :1 2> /dev/null &

You don't have to redirect stderr to /dev/null. I do it because I find Xephyr's chatter distracting and unnecessary.

Once Xephyr comes up, start Minx:

    DISPLAY=:1 ~/.minx/init.py &

Now, give Minx a few windows it can switch between. I usually start up a few terminals and message windows (you can use any X applications you like):

    DISPLAY=:1 xterm &
    DISPLAY=:1 xmessage foo &
    DISPLAY=:1 xmessage bar &

To cycle input focus between the above windows, switch to the Xephyr window and have it grab input focus by pressing CTRL + SHIFT. Then, press ALT + Tab and/or ALT + SHIFT + Tab repeatedly move the input focus forwards or backwards through the applications you started. When you're done testing, use CTRL + SHIFT again to have Xephyr release its grab on the keyboard and mouse so you can kill it and return to your normal X session.

NOTE: If ALT + Tab doesn't work, try customizing the key bindings for focus cycling as described in the Key Bindings HOWTO.

Ubuntu Peculiarities

Sometimes, on Ubuntu 12.04, typing into a terminal window generates junk characters when other windows are present. That is, if you start Xephyr, Minx, and then an xterm, you can use the terminal. However, if you start an xmessage and an xterm, typing into the terminal results in junk. Not sure why this happens.

Dual Monitor

To test Minx's ability to handle dual-head configurations, use Xephyr and Xdmx like so:

   Xephyr :2 2> /dev/null &
   Xephyr :3 2> /dev/null &
   Xdmx :1 -display :2 -display :3 2> /dev/null &

Now start the window manager and a couple of applications:

   DISPLAY=:1 ~/.minx/init.py &
   DISPLAY=:1.0 xterm &
   DISPLAY=:1.0 xmessage foo &
   DISPLAY=:1.1 xterm &
   DISPLAY=:1.1 xmessage bar &

You should be able to use ALT + Tab to switch between the above xterm and xmessage windows across both screens.

NOTE: Again, if ALT + Tab doesn't work, try customizing the key bindings (F1 and SHIFT + F1 are usually quite trustworthy).

Peculiarities

One issue to keep in mind with this dual-monitor test is that key press events only seem to work on the first Xephyr window. For some reason, when the second Xephyr window is focused, no keyboard events are generated. Not sure why this happens.