mirror of
https://github.com/brl/mutter.git
synced 2024-09-12 10:35:54 -04:00
![Florian Müllner](/assets/img/avatar_default.png)
Move preferences to GSettings, using mainly shared schemas from gsettings-desktop-schemas. Unlike GConf, GSettings support is not optional, as Gio is already a hard dependency of GTK+. https://bugzilla.gnome.org/show_bug.cgi?id=635378
299 lines
14 KiB
Plaintext
299 lines
14 KiB
Plaintext
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+ >= 3.0 and GIO >= 2.25.10 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, glib-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 <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.
|