Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Newer
Older
100644 299 lines (253 sloc) 14.03 kB
9382d58 @newren Provide more documentation to make it easier for people to contribute to
newren authored
1 Intro...
2
3 Window managers have a few ways in which they are significantly different
4 from other applications. This file, combined with the code overview in
5 doc/code-overview.txt, should hopefully provide a series of relatively
6 quick pointers (hopefully only a few minutes each) to some of the places
7 one can look to orient themselves and get started. Some of this will be
8 general to window managers on X, much will be specific to Metacity, and
9 there's probably some information that's common to programs in general but
10 is nonetheless useful.
11
12 Overview
13 Administrative issues
a03e782 Include instructions on setting up a minimal building/testing environ…
Elijah Newren authored
14 Minimal Building/Testing Environment
9382d58 @newren Provide more documentation to make it easier for people to contribute to
newren authored
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
27 Administrative 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
a03e782 Include instructions on setting up a minimal building/testing environ…
Elijah Newren authored
38 Minimal 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
b004ef4 update -- we depend on gtk+ >= 2.10 since Vincent's July patches for
Elijah Newren authored
42 build a development version of Metacity -- odds are, you may be able
43 to build metacity from CVS without building any other modules.
a03e782 Include instructions on setting up a minimal building/testing environ…
Elijah Newren authored
44
eb3c38e update; cvs->svn & mention GConf needed Make it match idiotic format
Elijah Newren authored
45 As long as you have gtk+ >= 2.10 and GConf with your distro (gtk+ >=
46 2.6 if you manually revert the change from bug 348633), you should
47 be able to install your distro's development packages
48 (e.g. gtk2-devel, GConf2-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:
a03e782 Include instructions on setting up a minimal building/testing environ…
Elijah Newren authored
54
eb3c38e update; cvs->svn & mention GConf needed Make it match idiotic format
Elijah Newren authored
55 $ svn checkout http://svn.gnome.org/svn/metacity/trunk metacity
a03e782 Include instructions on setting up a minimal building/testing environ…
Elijah Newren authored
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
9382d58 @newren Provide more documentation to make it easier for people to contribute to
newren authored
63 Relevant 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
86bbde3 @newren Add tips on how to more easily get the ids of windows, and how to sho…
newren authored
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
9382d58 @newren Provide more documentation to make it easier for people to contribute to
newren authored
102 xprop -root
103 in a terminal. There's all the properties of the root window (which you
86bbde3 @newren Add tips on how to more easily get the ids of windows, and how to sho…
newren authored
104 can think of as the "main" Xserver window). You can also manually
105 specify individual windows that you want the properties of with
9382d58 @newren Provide more documentation to make it easier for people to contribute to
newren authored
106 xprop -id <id>
86bbde3 @newren Add tips on how to more easily get the ids of windows, and how to sho…
newren authored
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.
9382d58 @newren Provide more documentation to make it easier for people to contribute to
newren authored
114
115 Debugging 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
7c70749 @newren Clarify why METACITY_VERBOSE=1 is bad without META_USE_LOGFILE=1; poi…
newren authored
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
9382d58 @newren Provide more documentation to make it easier for people to contribute to
newren authored
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
0a8bdcd Add an (unbound by default) keybinding for setting spew marks in verbose
Elijah Newren authored
185 valgrind --log-file=metacity.log --tool=memcheck --num-callers=48 \
9382d58 @newren Provide more documentation to make it easier for people to contribute to
newren authored
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 src/run-metacity.sh
198 The script src/run-metacity.sh is useful to hack on the window manager.
199 It runs metacity in an Xnest. e.g.:
200 CLIENTS=3 ./run-metacity.sh
201 or
202 DEBUG=memprof ./run-metacity.sh
203 or
204 DEBUG_TEST=1 ./run-metacity-sh
205 or whatever.
206
207 metacity-message
208 The tool metacity-message can be used as follows:
209 metacity-message reload-theme
210 metacity-message restart
211 metacity-message enable-keybindings
212 metacity-message disable-keybindings
ab0ba52 Clarify how/why metacity-message is used a little
Elijah Newren authored
213 The first of these is useful for testing themes, the second is just
214 another way (besides the --restart flag to metacity itself) of
215 restarting metacity, and the third is useful for testing Metacity when
216 running it under an Xnest (typically, the Metacity under the Xnest
217 wouldn't get keybinding notifications--making keyboard navigation not
218 work--but if you disable the keybindings for the global Metacity then
219 the Metacity under the Xnest can then get those keybinding notifications).
9382d58 @newren Provide more documentation to make it easier for people to contribute to
newren authored
220
221 metacity-window-demo
222 metacity-window-demo is good for trying behavior of various kinds
223 of window without launching a full desktop.
224
225 Technical gotchas to keep in mind
1dea155 Include reasons why gdk/gtk.h and core includes like display.h/window.h
Elijah Newren authored
226 Files that include gdk.h or gtk.h are not supposed to include
227 display.h or window.h or other core files. Files in the core
228 (display.[hc], window.[hc]) are not supposed to include gdk.h or
229 gtk.h. Reasons:
230
231 "Basically you don't want GDK most of the time. It adds
232 abstractions that cause problems, because they aren't designed to
233 be used in a WM where we do weird stuff (display grabs, and just
234 being the WM). At best GDK adds inefficiency, at worst it breaks
235 things in weird ways where you have to be a GDK guru to figure
236 them out. Owen also told me that they didn't want to start adding
237 a lot of hacks to GDK to let a WM use it; we both agreed back in
238 the mists of time that metacity would only use it for the "UI"
239 bits as it does.
240
241 Having the split in the source code contains and makes very clear
242 the interface between the WM and GDK/GTK. This keeps people from
243 introducing extra GDK/GTK usage when it isn't needed or
244 appropriate. Also, it speeds up the compilation a bit, though this
245 was perhaps more relevant 5 years ago than it is now.
246
247 There was also a very old worry that the GDK stuff might have to
248 be in a separate process to work right; that turned out to be
249 untrue. Though who knows what issues the CM will introduce."
9382d58 @newren Provide more documentation to make it easier for people to contribute to
newren authored
250
251 Remember that strings stored in X properties are not in UTF-8, and they
252 have to end up in UTF-8 before we try putting them through Pango.
253
254 If you make any X request involving a client window, you have to
255 meta_error_trap_push() around the call; this is not necessary for X
256 requests on the frame windows.
257
258 Remember that not all windows have frames, and window->frame can be NULL.
259
260 Other important reading & where to get started
261 Extra reading
262
263 There are some other important things to read to get oriented as well.
264 These are:
265 http://pobox.com/~hp/features.html
266 rationales.txt
267 doc/code-overview.txt
268
269 It pays to read http://pobox.com/~hp/features.html in order
270 to understand the philosophy of Metacity.
271
272 The rationales.txt file has two things: (1) a list of design choices with
273 links in the form of bugzilla bugs that discuss the issue, and (2) a list
274 outstanding bug categories, each of which is tracked by a particular
275 tracker bug in bugzilla from which you can find several closely related
276 bug reports.
277
278 doc/code-overview.txt provides a fairly good overview of the code,
279 including coverage of the function of the various files, the main
280 structures and their relationships, and places to start looking in the
281 code tailored to general categories of tasks.
282
283 Ideas for tasks to work on
284
285 There are a variety of things you could work on in the code. You may
286 have ideas of your own, but in case you don't, let me provide a list of
287 ideas you could choose from:
288
289 If you're ambitious, there's a list of things Havoc made that he'd really
290 like to see tackled, which you can find at
291 http://log.ometer.com/2004-05.html. Be sure to double check with someone
292 to make sure the item is still relevant if you're interested in one of
293 these. Another place to look for ideas, of course, is bugzilla. One can
294 just do queries and look for things that look fixable.
295
296 However, perhaps the best way of getting ideas of related tasks to work
297 on, is to look at the second half of the rationales.txt file, which tries
298 to group bugs by type.
Something went wrong with that request. Please try again.