Customization

This page will introduce you to the most common methods for Sawfish customization. You might want to look at the Customization Options to find out what you want to customize.

sawfish-config, easy customization

Many things can be tweaked by sawfish-config. By launching

$ sawfish-config

from your shell, you are presented a window with many customization groups. All options, you customize via sawfish-config are saved to ~/.sawfish/custom. You are not supposed to modify this file; however it's good to know what is actually happening. This file is loaded by Sawfish when it starts to restore the customizations you made in your last Sawfish session.

Temporary changes via the sawfish-client

sawfish-client is a small but very powerful swissknife for every Sawfish user and developer. By launching sawfish-client from your shell you get direct access to the running Lisp core of Sawfish. From there, you can make drastic changes to Sawfish's internals; In fact, you can reprogram the whole window manager without even restarting or recompiling it.

When a tutorial or how-to tells you to submit some commands to sawfish, you can use sawfish-client for that purpose. For instance, try

$ sawfish-client                           
sawfish 1.3, Copyright (C) 1999-2000 John Harper
sawfish comes with ABSOLUTELY NO WARRANTY; for details see the file COPYING

Enter `,help' to list commands.
user> (iconify-window (select-window))
()

You will get a crosshair to select a window. This window will be iconified. If you know the Lisp basics, you will immediately notice what's happening. The select-window function is called which will turn the mouse pointer into a crosshair for window selection. After clicking on a window, the resulting window object is passed to iconify-window. You may guess only once what this function will do to a window.

Whenever you played too much with sawfish-client and you made a change you don't like, then just type

(restart)

The sawfish process will quit and restart itself. This can be done more quickly, if you run

sawfish-client -f restart 

The -f switch will cause the appended function to be called. Notice that sawfish-client has a nice symbol completion facility.

Permanent changes

All commands you can type into your sawfish user prompt, you can also stuff into ~/.sawfish/rc. This file will be loaded when Sawfish starts. Don't worry, if you make any errors. Sawfish will handle errors in the rc file gracefully. But beware: if you make any mistakes at the beginning of the file, the rest of the file won't be loaded. If you are new to Sawfish and have no idea how to find out what's right or wrong, check out Failing RC Debugging.

Extensions uploaded by users

In the scripts page, you will find a lot of code that can customize Sawfish behavior. Select your favorite extension, download it and load it the Sawfish process.

For a module to load successfully, you must submit a require statement to your Lisp interpreter. require will search the load-path and when a module with the respective name has been found, it will load this module.

To view your load-path, use the sawfish-client. This is a sample session.

   user> load-path
   ("/home/clemens/.sawfish/lisp" "/usr/local/share/sawfish/1.3/lisp"
   "/usr/local/share/sawfish/site-lisp" "/usr/share/rep/0.17/lisp"    
   "/usr/share/rep/site-lisp" ".")

This is a standard load-path. You can either put your downloaded files in one of these directories our you can add a load path by submitting

   user> (setq load-path (append load-path '("/new/load/path")))

to sawfish-client.

In order to avoid horrible confusion with the plethora of sawfish scripts available on the net, a good idea is to use a consistent scheme for storing the various scripts avoiding namespace clashes (that is: avoid conflicts with scripts named in the same way).

A good idea is to create for each contributor in /usr/local/share/sawfish/site-lisp or ~/share/sawfish/site-lisp a directory with the initials or a unique identifier string for each contributor (e.g. "tk" or "merlin") where to place all the scripts contributed by that author.

In this way becomes trivial to distinguish bewteen contributed files with the same name, using for example:

    (require 'tk.corner)

rather than:

      (require 'fdf.corner)

Of course you need to put before "/usr/local/share/sawfish/site-lisp" and/or "~/share/sawfish/site-lisp" dirs in your sawfish load-path.

How require works

Among Lisp implementations it's common to load code via the require function. This is also true for librep. Submitting

(require 'foobar)

tells librep to search the load path for foobar.jl or foobar.jlc. To help modularization, librep substitutes every dot it finds in the required name by the directory delimiter of your system. Under Unix this is of course /, a slash. Hence, submitting

(require 'sawfish.wm.ext.window-grid)

will search all load-path for a subdir sawfish, if found, for a subdir wm, and so on. When librep finds sawfish/wm/ext/window-grid.jl (or jlc) relative to a load-path, this file will be loaded.