mutter-performance-source/HACKING

Making a release
===

To make a release of metacity, do the following:

 - check out a fresh copy from CVS

 - increment the version number in configure.in, 
   see the comment above the version for the next fibonacci number

 - update the file NEWS based on the ChangeLog

 - add a ChangeLog entry containing the version number 
   you're releasing ("Released 2.5.4" or something)
   so people can see which changes were before and after
   a given release.

 - "make distcheck" (DO NOT just "make dist" - pass the check!)

 - if make distcheck fails, fix it.

 - once distcheck succeeds, "cvs commit"

 - if someone else made changes and the commit fails, 
   you have to "cvs up" and run "make distcheck" again

 - once the commit succeeds, WITHOUT cvs updating, "cvs tag
   METACITY_X_Y_Z" where
   X_Y_Z map to version X.Y.Z

 - scp the tarball to master.gnome.org

 - run install-module on master.gnome.org to install the tarball 
   on the ftp site

Misc stuff
===

Don't commit substantive code in here without asking me,
hp@redhat.com.  Adding translations, no-brainer typo fixes, etc.  is
fine.

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.

The tool metacity-message can be used as follows:
 metacity-message reload-theme
 metacity-message restart
 metacity-message enable-keybindings
 metacity-message disable-keybindings

metacity-window-demo is good for trying behavior of various kinds of window
without launching a full desktop.

src/window.c is where all the guts of the window manager live. This is
basically the only remotely scary file.

src/frames.c is the GtkWidget that handles drawing window frames.

src/core.h defines the interface used by the GTK portion of the window
manager to talk to the other portions. There's some cruft in here
that's unused, since nearly all window operations have moved out of
this file so frameless apps can have window operations.

src/ui.h defines the interface the plain Xlib portion of the window
manager uses to talk to the GTK portion.

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.

src/theme.c and src/theme-parser.c have the theme system; this is
well-modularized from the rest of the code, since the theme viewer app
links to these files in addition to the WM itself.

When hacking, remember that you can have multiple screens. The code is
also written to support multiple displays, but this is useless, since
you can just run two copies of the WM. Also, an XKillClient() or
shutdown on any display causes Xlib to exit the app, so it would be
broken. So the multi-display thing is mostly just for code
cleanliness.  Multi-screen on the other hand is important for some
people.

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.

The code could use cleanup in a lot of places, feel free to do so.

Metacity is ideally a fully ICCCM and EWMH-compliant window manager.
Reading these specifications is a useful first step to understanding
the role of a window manager on an X11 desktop and the standards and
conventions on which X11 desktops are based.  Please refer to the
COMPLIANCE file for additional information on these specifications and
metacity's compliance therewith.