The RRU Gimp Tutorial

Starting the GIMP

[Standard Options] [Debug Options] [Output]

Last updated: 31 August 1998

To date, the GIMP runs only on a variety of UNIX and UNIX-like systems. So the GIMP is always started via a command line (although this can be hidden by a window manager or desktop).

Simply typing 

    gimp
should start the GIMP. However, several options are available.

Standard options
-h or --help Output help.
-v or --version Output version info.
-b or --batch <commands> Run in batch mode.
-n or --no-interface Run without a user interface.
--no-data Do not load patterns, gradients, palettes, brushes.
--verbose Show the startup messages.
--no-splash Do not show the startup window.
--no-splash-image Do not add an image to the startup window.
--no-shm Do not use shared memory between GIMP and its plugins.
--no-xshm Do not use the X Shared Memory extension.
--console-messages Display warnings to console instead of a dialog box.
--display <display> Use the designated X display.
Debugging options
--sync Send X commands synchronously.
--show-events Show GDK events.
--no-show-events Don't show GDK events.
--debug-level <level> Provide debug output at designated level.
--debug-handlers Enable debugging signal handlers.

Standard Options

Help

The -h and --help options cause the GIMP to briefly explain how to properly invoke it, and the options available. My version currently looks like this: 
Usage: gimp [option ...] [files ...]
Valid options are:
  -h --help              Output this help.
  -v --version           Output version info.
  -b --batch <commands>  Run in batch mode.
  -n --no-interface      Run without a user interface.
  --no-data              Do not load patterns, gradients, palettes, brushes
  --no-shm               Do not use shared memory between GIMP and its plugins.
  --no-xshm              Do not use the X Shared Memory extension
  --display <display>    Use the designated X display.

Valid debugging options are:
  --sync                 Send X commands synchronously.
  --show-events          Show GDK events.
  --no-show-events       Don't show GDK events.
  --debug-level <level>  Provide debug output at designated level.

Version

The -v and --version options cause the GIMP to tell you its current version. 
    GIMP version 0.99.10
To get the latest version of the GIMP, check http://www.gimp.org/ .

Batch mode

The -b and --batch commands allow you to execute a series of GIMP/scheme commands directly from the command line, the standard input stream, or a file. The GIMP looks at the parameter following the batch for these commands.

If this parameter is '-' (a minus sign), the commands will be taken from the standard input stream (stdin). If the parameter starts with a parenthesis, it is assumed to be the actual commands. Otherwise, the GIMP tries to open a file using the parameter as a filename. If this fails, the GIMP will complain: 

    unable to open batch file: <commands>
When the parameter is the actual command[s] to run, you may need to enclose the command[s] in quotes (single or double) to pass escape various characters that would otherwise be interpreted by your shell (such as quotes and parentheses). You will need to escape any quotes that appear within the command by prepending them with a backslash (\), as in the example below. 
    gimp -b '((gimp-palette-set-background \'(255 0 0)) ... (gimp-displays-flush))'
NOTE

With the C shell and its variants (csh, tcsh, etc.) you cannot use a single quote inside single quotes. In this case, you need to end the quote, add an escaped quote, and resume the quoted string, as shown below. 

    gimp -b '((gimp-...ound '\''(255 0 0)) ... ))'

This must be the last option on the command line, because everything after it is interpreted as a batch command.

Unless you have something generating commands on the fly, or are testing something simple, you probably don't want to use this option.

No interface

The no interface option, invoked by -n and --no-interface, is primarily useful when the GIMP is invoked in batch mode. As its name implies, it causes the GIMP to not display any sort of user interface.

No data

The --no-data option speeds up the GIMP's startup time quite a bit by not trying to load the brushes, patterns, palettes and gradients. Many times you will not need these, or may only need one of them. At the present time, brushes and patterns may be loaded on demand by selecting 
    File
    -> Dialogs
       -> Brushes...
          (or Patterns...)
and clicking on the [Refresh] button. There is currently no equivalent method to load palettes and gradients after starting. Presumably this will change.

No shared memory

The --no-shm disables the OS-level shared memory mechanism. Shared memory allows the GIMP and its plug-ins to communicate faster. Turn this off only if the GIMP compains at startup about shared memory, or for debugging purposes. Otherwise, the GIMP will be much slower.

No X Shared Memory Extension

The --no-xshm option disables the X Shared Memory Extension, which is normally used to allow the GIMP to communicate faster with your display. However, this only works if your display is on the same system as the GIMP is running. If you are displaying on a remote workstation, X station, PC running X, or other remote device, you must tell the GIMP not to use this extension.

There may still be a couple of UNIX vendors whose X servers do not support this extension. In some cases, you have to explicitly tell your X server to use the extension. Check the X(1) and Xserver(1) man pages for more information if you suspect this is the case.

Display

Normally the GIMP tries to display its user interface on the X display server defined in your DISPLAY environment variable. If this is not set, the GIMP (like all C programs) will attempt to use the local workstation display, if any. To tell the GIMP to use a different display, you can either set your DISPLAY environment variable or use the -display command line option. 
    gimp -display volcano.tb.org:0
If you need further information, check the X(1) man pages.

Debug Options

For those of you who aren't developers, if a developer asks you to send debug output (whether it just appears or you have to set some of the options below), you do this by redirecting the GIMP's standard output (stdout) and standard error (stderr).

How you do this depends on the shell you are using. In any of the Bourne-derived shells (sh, bsh, rsh, ksh, or bash): 

   gimp > error_file 2>&1
In any of the csh-derived shells (csh, tcsh): 
    gimp >& error_file

X Synchronous Mode

The --sync option turns on X synchronous mode. The easiest way to explain this is to quote directly from the X(1) man page: 
    This  option  indicates  that  requests  to  the X
    server should be sent  synchronously,  instead  of
    asynchronously.    Since   Xlib  normally  buffers
    requests to the server, errors do not  necessarily
    get  reported  immediately after they occur.  This
    option turns off the buffering so that the  appli-
    cation  can  be debugged.  It should never be used
    with a working program.

Show GDK events

The --show-events option tells the GDK (GIMP Display Kit) to show events. This is primarily of use for developers, or to generate output to send developers when you are having a GDK problem. If you aren't a developer, you don't care about this unless someone helping you with a problem asks for its output.

Don't show GDK events

The --no-show-events tells the GDK (GIMP Display Kit) not to show its events (see above). Since this is off by default, this is primarily useful for commenting out the --show-events in a script, unless you have built a special debugging version where it is turned on by default.

Debug Level

This is also primarily a GDK debugging tool. Invoking the GIMP with the --debug option sets the debugging to the appropriate level. Again, if you don't know about this, you won't care unless a developer asks you to turn it on.

Output

The GIMP should normally produce very little in the way of messages. The current, pre-1.0 releases do give a few informational messages on startup: 
    parsing "/home/meo/.gimp/gtkrc"
    parsing "/usr/local/share/gimp/0.99.10/gimprc"
    parsing "/home/meo/.gimp/pluginrc"
    Starting extensions: extension_script_fu
I'm not sure whether these will still occur in 1.0 . If the GIMP is started from a window manager or desktop manager menu, you will probably never see these.

The only other messages at this time are debugging messages. The most common have to do with tile reference counts, which you may safely ignore (unless you are debugging, of course!) and complaints from scheme when a Script-Fu script fails. See the FAQs for the most common of these.

Now you should learn the basics of using the GIMP.

Last updated: 31 August 1998

Copyright 1997, 1998 Miles O'Neal, Austin, TX. All rights reserved.

Miles O'Neal, <meo@rru.com>
11501 Johnson Rd / Leander, TX / 78641-5823