Intro... Window managers have a few ways in which they are significantly different from other applications. This file, combined with the code overview in doc/code-overview.txt, should hopefully provide a series of relatively quick pointers (hopefully only a few minutes each) to some of the places one can look to orient themselves and get started. Some of this will be general to window managers on X, much will be specific to Metacity, and there's probably some information that's common to programs in general but is nonetheless useful. Overview Administrative issues Minimal Building/Testing Environment Relevant standards and X properties Debugging and testing Debugging logs Adding information to the log Valgrind Testing Utilities Technical gotchas to keep in mind Other important reading Extra reading Ideas for tasks to work on Administrative issues Don't commit substantive code in here without asking hp@redhat.com. Adding translations, no-brainer typo fixes, etc. is fine. The code could use cleanup in a lot of places, feel free to do so. See http://developer.gnome.org/dotplan/for_maintainers.html for information on how to make a release. The only difference from those instructions is that the minor version number of a Metacity release should always be a number from the Fibonacci sequence. Minimal Building/Testing Environment You do not need to _install_ a development version of Metacity to build, run and test it; you can run it from some temporary directory. Also, you do not need to build all of Gnome in order to build a development version of Metacity -- odds are, you may be able to build metacity from CVS without building any other modules. As long as you have gtk+ >= 2.10 and GConf with your distro (gtk+ >= 2.6 if you manually revert the change from bug 348633), you should be able to install your distro's development packages (e.g. gtk2-devel, GConf2-devel, startup-notification-devel on Fedora; also, remember to install the gnome-common package which is needed for building cvs versions of Gnome modules like Metacity) as well as the standard development tools (gcc, autoconf, automake, pkg-config, intltool, and libtool) and be ready to build and test Metacity. Steps to do so: $ svn checkout http://svn.gnome.org/svn/metacity/trunk metacity $ cd metacity $ ./autogen.sh --prefix /usr $ make $ ./src/metacity --replace Again, note that you do not need to run 'make install'. Relevant standards and X properties There are two documents that describe some basics about how window managers should behave: the ICCCM (Inter-Client Communication Conventions Manual) and EWMH (Extended Window Manager Hints). You can find these at the following locations: ICCCM - http://tronche.com/gui/x/icccm/ EWMH - :pserver:anoncvs@pdx.freedesktop.org:/cvs The ICCCM is usually available in RPM or DEB format as well. There is actually an online version of the EWMH, but it is almost always woefully out of date. Just get it from cvs with these commands (the backslash means include the stuff from the next line): cvs -d :pserver:anoncvs@cvs.freedesktop.org:/cvs/icccm-extensions login cvs -d :pserver:anoncvs@cvs.freedesktop.org:/cvs/icccm-extensions \ checkout wm-spec DO NOT GO AND READ THOSE THINGS. THEY ARE REALLY, REALLY BORING. If you do, you'll probably end up catching up on your sleep instead of hacking on Metacity. ;-) Instead, just look at the table of contents and glance at a page or two to get an idea of what's in there. Then only refer to it if you see something weird in the code and you don't know what it is but has some funny looking name like you see in one of those two documents. You can refer to the COMPLIANCE file for additional information on these specifications and Metacity's compliance therewith. One of the major things those documents cover that are useful to learn about immediately are X properties. The right way to learn about those, though, is through hand on experimentation with the xprop command (and then look up things you find from xprop in those two manuals if you're curious enough). First, try running xprop in a terminal and click on one of the windows on your screen. That gives you the x properties for that window. Look through them and get a basic idea of what's there for kicks. Note that you can get rid of some of the verboseness by grepping out the _NET_WM_ICON stuff, i.e. xprop | grep -v _NET_WM_ICON Next, try running xprop -root in a terminal. There's all the properties of the root window (which you can think of as the "main" Xserver window). You can also manually specify individual windows that you want the properties of with xprop -id if you know the id of the window in question. You can get the id of a given window by either running xwininfo, e.g. xwininfo | grep "Window id" | cut -f 4 -d ' ' or by looking at the _NET_CLIENT_STACKING property of the root window. Finally, it can also be useful to add "-spy" (without the quotes) to the xprop command to get it to continually monitor that window and report any changes to you. Debugging information Trying to run a window manager under a typical debugger, such as gdb, unfortunately just doesn't work very well. So, we have to resort to other methods. Debugging logs First, note that you can start a new version of metacity to replace the existing one by running metacity --replace (which also comes in handy in the form "./src/metacity --replace" when trying to quickly test a small change while hacking on metacity without doing a full "make install", though I'm going off topic...) This will allow you to see any warnings printed at the terminal. Sometimes it's useful to have these directed to a logfile instead, which you can do by running METACITY_USE_LOGFILE=1 metacity --replace The logfile it uses will be printed in the terminal. Sometimes, it's useful to get more information than just warnings. You can set METACITY_VERBOSE to do that, like so: METACITY_VERBOSE=1 METACITY_USE_LOGFILE=1 metacity --replace (note that METACITY_VERBOSE=1 can be problematic without METACITY_USE_LOGFILE=1; avoid it unless running in from something that won't be managed by the new Metacity--see bug 305091 for more details). There are also other flags, such as METACITY_DEBUG, most of which I haven't tried and don't know what they do. Go to the source code directory and run grep "METACITY_" * | grep getenv to find out what the other ones are. Adding information to the log Since we can't single step with a debugger, we often have to fall back to the primitive method of getting information we want to know: adding "print" statements. Metacity has a fairly structured way to do this, using the functions meta_warning, meta_topic, and meta_verbose. All three have the same basic format as printf, except that meta_topic also takes a leading enumeration parameter to specify the type of message being shown (makes it easier for grepping in a verbose log). You'll find tons of examples in the source code if you need them; just do a quick grep or look in most any file. Note that meta_topic and meta_verbose messages only appear if verbosity is turned on. I tend to frequently add temporary meta_warning statements (or switch meta_topic or meta_verbose ones to meta_warning ones) and then undo the changes once I've learned the info that I needed. There is also a meta_print_backtrace (which again is only active if verbosity is turned on) that can also be useful if you want to learn how a particular line of code gets called. And, of course, there's always g_assert if you want to make sure some section isn't executed (or isn't executed under certain conditions). Valgrind Valgrind is awesome for finding memory leaks or corruption and uninitialized variables. But I also tend to use it in a non-traditional way as a partial substitute for a normal debugger: it can provide me with a stack trace of where metacity is crashing if I made a change that caused it to do so, which is one of the major uses of debuggers. (And, what makes it cooler than a debugger is that there will also often be warnings pinpointing the cause of the crash from either some kind of simple memory corruption or an uninitialized variable). Sometimes, when I merely want to know what is calling a particular function I'll just throw in an "int i; printf("%d\n", i);" just because valgrind will give me a full stacktrace whenever it sees that uninitialized variable being used (yes, I could use meta_print_backtrace, but that means I have to turn verbosity on). To run metacity under valgrind, use options typical for any Gnome program, such as valgrind --log-file=metacity.log --tool=memcheck --num-callers=48 \ --leak-check=yes --leak-resolution=high --show-reachable=yes \ ./src/metacity --replace where, again, the backslashes mean to join all the stuff on the following line with the previous one. However, there is a downside. Things run a little bit slowly, and it appears that you'll need about 1.5GB of ram, which unfortunately prevents most people from trying this. Testing Utilities src/run-metacity.sh The script src/run-metacity.sh is useful to hack on the window manager. It runs metacity in an Xnest. e.g.: CLIENTS=3 ./run-metacity.sh or DEBUG=memprof ./run-metacity.sh or DEBUG_TEST=1 ./run-metacity-sh or whatever. metacity-message The tool metacity-message can be used as follows: metacity-message reload-theme metacity-message restart metacity-message enable-keybindings metacity-message disable-keybindings The first of these is useful for testing themes, the second is just another way (besides the --restart flag to metacity itself) of restarting metacity, and the third is useful for testing Metacity when running it under an Xnest (typically, the Metacity under the Xnest wouldn't get keybinding notifications--making keyboard navigation not work--but if you disable the keybindings for the global Metacity then the Metacity under the Xnest can then get those keybinding notifications). metacity-window-demo metacity-window-demo is good for trying behavior of various kinds of window without launching a full desktop. Technical gotchas to keep in mind Files that include gdk.h or gtk.h are not supposed to include display.h or window.h or other core files. Files in the core (display.[hc], window.[hc]) are not supposed to include gdk.h or gtk.h. Reasons: "Basically you don't want GDK most of the time. It adds abstractions that cause problems, because they aren't designed to be used in a WM where we do weird stuff (display grabs, and just being the WM). At best GDK adds inefficiency, at worst it breaks things in weird ways where you have to be a GDK guru to figure them out. Owen also told me that they didn't want to start adding a lot of hacks to GDK to let a WM use it; we both agreed back in the mists of time that metacity would only use it for the "UI" bits as it does. Having the split in the source code contains and makes very clear the interface between the WM and GDK/GTK. This keeps people from introducing extra GDK/GTK usage when it isn't needed or appropriate. Also, it speeds up the compilation a bit, though this was perhaps more relevant 5 years ago than it is now. There was also a very old worry that the GDK stuff might have to be in a separate process to work right; that turned out to be untrue. Though who knows what issues the CM will introduce." Remember that strings stored in X properties are not in UTF-8, and they have to end up in UTF-8 before we try putting them through Pango. If you make any X request involving a client window, you have to meta_error_trap_push() around the call; this is not necessary for X requests on the frame windows. Remember that not all windows have frames, and window->frame can be NULL. Other important reading & where to get started Extra reading There are some other important things to read to get oriented as well. These are: http://pobox.com/~hp/features.html rationales.txt doc/code-overview.txt It pays to read http://pobox.com/~hp/features.html in order to understand the philosophy of Metacity. The rationales.txt file has two things: (1) a list of design choices with links in the form of bugzilla bugs that discuss the issue, and (2) a list outstanding bug categories, each of which is tracked by a particular tracker bug in bugzilla from which you can find several closely related bug reports. doc/code-overview.txt provides a fairly good overview of the code, including coverage of the function of the various files, the main structures and their relationships, and places to start looking in the code tailored to general categories of tasks. Ideas for tasks to work on There are a variety of things you could work on in the code. You may have ideas of your own, but in case you don't, let me provide a list of ideas you could choose from: If you're ambitious, there's a list of things Havoc made that he'd really like to see tackled, which you can find at http://log.ometer.com/2004-05.html. Be sure to double check with someone to make sure the item is still relevant if you're interested in one of these. Another place to look for ideas, of course, is bugzilla. One can just do queries and look for things that look fixable. However, perhaps the best way of getting ideas of related tasks to work on, is to look at the second half of the rationales.txt file, which tries to group bugs by type.