1Intro... 2 3Window managers have a few ways in which they are significantly different 4from other applications. This file, combined with the code overview in 5doc/code-overview.txt, should hopefully provide a series of relatively 6quick pointers (hopefully only a few minutes each) to some of the places 7one can look to orient themselves and get started. Some of this will be 8general to window managers on X, much will be specific to Metacity, and 9there's probably some information that's common to programs in general but 10is nonetheless useful. 11 12Overview 13 Administrative issues 14 Minimal Building/Testing Environment 15 Relevant standards and X properties 16 Debugging and testing 17 Debugging logs 18 Adding information to the log 19 Valgrind 20 Testing Utilities 21 Technical gotchas to keep in mind 22 Other important reading 23 Extra reading 24 Ideas for tasks to work on 25 26 27Administrative issues 28 Don't commit substantive code in here without asking hp@redhat.com. 29 Adding translations, no-brainer typo fixes, etc. is fine. 30 31 The code could use cleanup in a lot of places, feel free to do so. 32 33 See http://developer.gnome.org/dotplan/for_maintainers.html for 34 information on how to make a release. The only difference from those 35 instructions is that the minor version number of a Metacity release 36 should always be a number from the Fibonacci sequence. 37 38Minimal Building/Testing Environment 39 You do not need to _install_ a development version of Metacity to 40 build, run and test it; you can run it from some temporary 41 directory. Also, you do not need to build all of Gnome in order to 42 build a development version of Metacity -- odds are, you may be able 43 to build metacity from CVS without building any other modules. 44 45 As long as you have gtk+ >= 2.10 and GIO >= 2.25.10 with your distro 46 (gtk+ >= 2.6 if you manually revert the change from bug 348633), you 47 should be able to install your distro's development packages 48 (e.g. gtk2-devel, glib-devel, startup-notification-devel on 49 Fedora; also, remember to install the gnome-common package which is 50 needed for building cvs versions of Gnome modules like Metacity) as 51 well as the standard development tools (gcc, autoconf, automake, 52 pkg-config, intltool, and libtool) and be ready to build and test 53 Metacity. Steps to do so: 54 55 $ svn checkout http://svn.gnome.org/svn/metacity/trunk metacity 56 $ cd metacity 57 $ ./autogen.sh --prefix /usr 58 $ make 59 $ ./src/metacity --replace 60 61 Again, note that you do not need to run 'make install'. 62 63Relevant standards and X properties 64 There are two documents that describe some basics about how window 65 managers should behave: the ICCCM (Inter-Client Communication Conventions 66 Manual) and EWMH (Extended Window Manager Hints). You can find these at 67 the following locations: 68 ICCCM - http://tronche.com/gui/x/icccm/ 69 EWMH - :pserver:anoncvs@pdx.freedesktop.org:/cvs 70 The ICCCM is usually available in RPM or DEB format as well. There is 71 actually an online version of the EWMH, but it is almost always woefully 72 out of date. Just get it from cvs with these commands (the backslash 73 means include the stuff from the next line): 74 cvs -d :pserver:anoncvs@cvs.freedesktop.org:/cvs/icccm-extensions login 75 cvs -d :pserver:anoncvs@cvs.freedesktop.org:/cvs/icccm-extensions \ 76 checkout wm-spec 77 78 DO NOT GO AND READ THOSE THINGS. THEY ARE REALLY, REALLY BORING. 79 80 If you do, you'll probably end up catching up on your sleep instead of 81 hacking on Metacity. ;-) Instead, just look at the table of contents and 82 glance at a page or two to get an idea of what's in there. Then only 83 refer to it if you see something weird in the code and you don't know 84 what it is but has some funny looking name like you see in one of those 85 two documents. 86 87 You can refer to the COMPLIANCE file for additional information on these 88 specifications and Metacity's compliance therewith. 89 90 One of the major things those documents cover that are useful to learn 91 about immediately are X properties. The right way to learn about those, 92 though, is through hand on experimentation with the xprop command (and 93 then look up things you find from xprop in those two manuals if you're 94 curious enough). First, try running 95 xprop 96 in a terminal and click on one of the windows on your screen. That gives 97 you the x properties for that window. Look through them and get a basic 98 idea of what's there for kicks. Note that you can get rid of some of the 99 verboseness by grepping out the _NET_WM_ICON stuff, i.e. 100 xprop | grep -v _NET_WM_ICON 101 Next, try running 102 xprop -root 103 in a terminal. There's all the properties of the root window (which you 104 can think of as the "main" Xserver window). You can also manually 105 specify individual windows that you want the properties of with 106 xprop -id <id> 107 if you know the id of the window in question. You can get the id of a 108 given window by either running xwininfo, e.g. 109 xwininfo | grep "Window id" | cut -f 4 -d ' ' 110 or by looking at the _NET_CLIENT_STACKING property of the root 111 window. Finally, it can also be useful to add "-spy" (without the 112 quotes) to the xprop command to get it to continually monitor that 113 window and report any changes to you. 114 115Debugging information 116 Trying to run a window manager under a typical debugger, such as gdb, 117 unfortunately just doesn't work very well. So, we have to resort to 118 other methods. 119 120 Debugging logs 121 122 First, note that you can start a new version of metacity to replace the 123 existing one by running 124 metacity --replace 125 (which also comes in handy in the form "./src/metacity --replace" when 126 trying to quickly test a small change while hacking on metacity without 127 doing a full "make install", though I'm going off topic...) This will 128 allow you to see any warnings printed at the terminal. Sometimes it's 129 useful to have these directed to a logfile instead, which you can do by 130 running 131 METACITY_USE_LOGFILE=1 metacity --replace 132 The logfile it uses will be printed in the terminal. Sometimes, it's 133 useful to get more information than just warnings. You can set 134 METACITY_VERBOSE to do that, like so: 135 METACITY_VERBOSE=1 METACITY_USE_LOGFILE=1 metacity --replace 136 (note that METACITY_VERBOSE=1 can be problematic without 137 METACITY_USE_LOGFILE=1; avoid it unless running in from something that 138 won't be managed by the new Metacity--see bug 305091 for more details). 139 There are also other flags, such as METACITY_DEBUG, most of which I 140 haven't tried and don't know what they do. Go to the source code 141 directory and run 142 grep "METACITY_" * | grep getenv 143 to find out what the other ones are. 144 145 Adding information to the log 146 147 Since we can't single step with a debugger, we often have to fall back to 148 the primitive method of getting information we want to know: adding 149 "print" statements. Metacity has a fairly structured way to do this, 150 using the functions meta_warning, meta_topic, and meta_verbose. All 151 three have the same basic format as printf, except that meta_topic also 152 takes a leading enumeration parameter to specify the type of message 153 being shown (makes it easier for grepping in a verbose log). You'll find 154 tons of examples in the source code if you need them; just do a quick 155 grep or look in most any file. Note that meta_topic and meta_verbose 156 messages only appear if verbosity is turned on. I tend to frequently add 157 temporary meta_warning statements (or switch meta_topic or meta_verbose 158 ones to meta_warning ones) and then undo the changes once I've learned 159 the info that I needed. 160 161 There is also a meta_print_backtrace (which again is only active if 162 verbosity is turned on) that can also be useful if you want to learn how 163 a particular line of code gets called. And, of course, there's always 164 g_assert if you want to make sure some section isn't executed (or isn't 165 executed under certain conditions). 166 167 Valgrind 168 169 Valgrind is awesome for finding memory leaks or corruption and 170 uninitialized variables. But I also tend to use it in a non-traditional 171 way as a partial substitute for a normal debugger: it can provide me with 172 a stack trace of where metacity is crashing if I made a change that 173 caused it to do so, which is one of the major uses of debuggers. (And, 174 what makes it cooler than a debugger is that there will also often be 175 warnings pinpointing the cause of the crash from either some kind of 176 simple memory corruption or an uninitialized variable). Sometimes, when 177 I merely want to know what is calling a particular function I'll just 178 throw in an "int i; printf("%d\n", i);" just because valgrind will give 179 me a full stacktrace whenever it sees that uninitialized variable being 180 used (yes, I could use meta_print_backtrace, but that means I have to 181 turn verbosity on). 182 183 To run metacity under valgrind, use options typical for any Gnome 184 program, such as 185 valgrind --log-file=metacity.log --tool=memcheck --num-callers=48 \ 186 --leak-check=yes --leak-resolution=high --show-reachable=yes \ 187 ./src/metacity --replace 188 where, again, the backslashes mean to join all the stuff on the following 189 line with the previous one. 190 191 However, there is a downside. Things run a little bit slowly, and it 192 appears that you'll need about 1.5GB of ram, which unfortunately prevents 193 most people from trying this. 194 195 Testing Utilities 196 197 metacity-message 198 The tool metacity-message can be used as follows: 199 metacity-message reload-theme 200 metacity-message restart 201 metacity-message enable-keybindings 202 metacity-message disable-keybindings 203 The first of these is useful for testing themes, the second is just 204 another way (besides the --restart flag to metacity itself) of 205 restarting metacity, and the third is useful for testing Metacity when 206 running it under an Xnest (typically, the Metacity under the Xnest 207 wouldn't get keybinding notifications--making keyboard navigation not 208 work--but if you disable the keybindings for the global Metacity then 209 the Metacity under the Xnest can then get those keybinding notifications). 210 211Technical gotchas to keep in mind 212 Files that include gdk.h or gtk.h are not supposed to include 213 display.h or window.h or other core files. Files in the core 214 (display.[hc], window.[hc]) are not supposed to include gdk.h or 215 gtk.h. Reasons: 216 217 "Basically you don't want GDK most of the time. It adds 218 abstractions that cause problems, because they aren't designed to 219 be used in a WM where we do weird stuff (display grabs, and just 220 being the WM). At best GDK adds inefficiency, at worst it breaks 221 things in weird ways where you have to be a GDK guru to figure 222 them out. Owen also told me that they didn't want to start adding 223 a lot of hacks to GDK to let a WM use it; we both agreed back in 224 the mists of time that metacity would only use it for the "UI" 225 bits as it does. 226 227 Having the split in the source code contains and makes very clear 228 the interface between the WM and GDK/GTK. This keeps people from 229 introducing extra GDK/GTK usage when it isn't needed or 230 appropriate. Also, it speeds up the compilation a bit, though this 231 was perhaps more relevant 5 years ago than it is now. 232 233 There was also a very old worry that the GDK stuff might have to 234 be in a separate process to work right; that turned out to be 235 untrue. Though who knows what issues the CM will introduce." 236 237 Remember that strings stored in X properties are not in UTF-8, and they 238 have to end up in UTF-8 before we try putting them through Pango. 239 240 If you make any X request involving a client window, you have to 241 meta_error_trap_push() around the call; this is not necessary for X 242 requests on the frame windows. 243 244 Remember that not all windows have frames, and window->frame can be NULL. 245 246Other important reading & where to get started 247 Extra reading 248 249 There are some other important things to read to get oriented as well. 250 These are: 251 http://pobox.com/~hp/features.html 252 rationales.txt 253 doc/code-overview.txt 254 255 It pays to read http://pobox.com/~hp/features.html in order 256 to understand the philosophy of Metacity. 257 258 The rationales.txt file has two things: (1) a list of design choices with 259 links in the form of bugzilla bugs that discuss the issue, and (2) a list 260 outstanding bug categories, each of which is tracked by a particular 261 tracker bug in bugzilla from which you can find several closely related 262 bug reports. 263 264 doc/code-overview.txt provides a fairly good overview of the code, 265 including coverage of the function of the various files, the main 266 structures and their relationships, and places to start looking in the 267 code tailored to general categories of tasks. 268 269 Ideas for tasks to work on 270 271 There are a variety of things you could work on in the code. You may 272 have ideas of your own, but in case you don't, let me provide a list of 273 ideas you could choose from: 274 275 If you're ambitious, there's a list of things Havoc made that he'd really 276 like to see tackled, which you can find at 277 http://log.ometer.com/2004-05.html. Be sure to double check with someone 278 to make sure the item is still relevant if you're interested in one of 279 these. Another place to look for ideas, of course, is bugzilla. One can 280 just do queries and look for things that look fixable. 281 282 However, perhaps the best way of getting ideas of related tasks to work 283 on, is to look at the second half of the rationales.txt file, which tries 284 to group bugs by type. 285