doc/INSTALL

   1
   2 BUILDING VTWM 5.4
   3 =================
   4
   5   - Unpack the distribution. You've likely done that already, no?
   6
   7   - Determine if you have the XPM library installed:
   8       - The library is usually found in /usr/X11R6/lib, /usr/local/lib,
   9         or some such directory. It's usually called "libxpm.a".
  10       - The header file is usually found in /usr/X11R6/include,
  11         /usr/local/include, or some such directory. It's "xpm.h".
  12
  13   - Determine if you have regular expressions ("RE"s) support:
  14       - On many systems, the routines are built into the standard
  15         C library. If not, the library might be in /usr/local/lib,
  16         /usr/lib, or some such directory, and would be called
  17         something like "libregex.a".
  18       - The header file is usually found in /usr/local/include,
  19         /usr/include, or some such directory. It's "regex.h".
  20       - Note that the routines must conform to the POSIX 1003.2
  21         specification. Older systems may have regex support that
  22         predates this POSIX spec, and will not suffice.
  23
  24   - Determine if you have the rplay library installed:
  25       - The library is usually found in /usr/local/lib, /usr/lib,
  26         or some such directory. It's usually called "librplay.a".
  27       - The header file is usually found in /usr/local/include,
  28         /usr/include, or some such directory. It's "rplay.h".
  29
  30   - Determine if your system supports internationalization (I18N):
  31       - On many systems, header files "locale.h" and "Xlocale.h"
  32         are found in /usr/include and /usr/X11R6/include/X11,
  33         respectively.
  34
  35   - Determine if you have the m4 macro processor installed:
  36       - Issuing 'whence m4' or 'which m4' ought to do it.
  37
  38   - Look over Imakefile, and edit to taste. If you use a VNC client, or
  39     Cygwin under MS-Windows, you may want to make changes as described
  40     further down in this file. Or particular interest to some people
  41     will be the installation path which can be changed by editing
  42     VTWMBINDIR. See also VTWMLIBDIR and VTWMMANDIR. This will allow
  43     installation to other than the system X11 directories where you don't
  44     have root access.
  45
  46   - Issue 'xmkmf'. If that doesn't work (you'll know it), you'll have
  47     to copy Makefile.QNX to Makefile, and edit the latter to taste.
  48
  49   - Issue 'make'. This shouldn't take very long at all; VTWM is small.
  50     Should the build break, check further down in this file. If it still
  51     breaks, ask a friend. If it _still_ breaks, you can write me.
  52
  53   - The sysrc_add_apps.sh script in contrib/support/ may be of help in
  54     customizing the default system resource file. It automagically adds
  55     selected applications found on your system to system.vtwmrc. Issue
  56     'sh contrib/support/sysrc_add_apps.sh -h' for a brief help message.
  57
  58
  59 INSTALLING VTWM 5.4
  60 ===================
  61
  62 1) Installation.
  63     If you haven't modified VTWMBINDIR, et al, to point to a non-system
  64     area in which you have write access, you will need to perform the
  65     following install steps as root.
  66   - If you trust whoever set up your build environment:
  67       - issue 'make install'.
  68     If you don't:
  69       - Issue 'make -n install' to see what it'll do, without actually
  70         doing it.
  71   - If you want (or have) to set it up manually:
  72       - Copy vtwm to /usr/X11R6/bin, or to wherever other X
  73         window managers and binaries are.
  74       - Copy system.vtwmrc to wherever it's spec'd in the
  75         Makefile (this path is built into the VTWM binary).
  76       - Copy vtwm.man to wherever other X window manager
  77         man pages are (usually /usr/X11R6/man/mann).
  78
  79 2) Configuration.
  80   - Set up user resource files:
  81       - Copy system.vtwmrc to your home directory as .vtwmrc, and edit
  82         it to suit your immediate needs (you'll be editing it a lot more,
  83         I'm sure).
  84       - If VTWM supports m4, you can copy the contrib/vtwmrc/ directory
  85         into your home directory as vtwm/ or some such. Then, create a
  86         symlink $(HOME)/.vtwmrc to one of the vtwmrc-*ish files in that
  87         subdirectory, or specify one of those files on VTWM's invocation
  88         (either will give you much more to work with).
  89       - The sysrc_add_apps.sh script in contrib/support/ may also be
  90         useful in customizing user resource files by playing with its
  91         command-line switches.
  92
  93   - Edit the script that starts your current X window manager to start
  94     VTWM instead (mine is 'vtwm -d :0.0 -f vtwm/vtwmrc-MWMish -s -m -p'
  95     in $(HOME)/.xinitrc).
  96
  97   - Exit X, and restart it.
  98
  99
 100 BUILD HINTS
 101 ===========
 102
 103   - If, during the build, you get complaints of an undefined "yylineno",
 104     uncomment the "NEED_YYLINENO_V" definition in Imakefile (or the
 105     Makefile) and try the build again. If it is still undefined, also
 106     remove the "extern" keyword from its declaration in gram.y. Likewise,
 107     if "yywrap" turns up as undefined, add a line "yywrap() {return(1)};"
 108     to lex.l. Finally, if "yylex" turns up undefined, it can be fixed by
 109     adding a line "#define YY_DECL int yylex YY_PROTO((void))" to lex.l.
 110     These are all expected to be in the lexer's skeleton file, but there
 111     are some without.
 112
 113   - If, during the build, you get complaints of undefined data types and
 114     functions "FontSet" and "Xmb" whatall, it's because you've built VTWM
 115     with internationalization (I18N) support, and your system doesn't
 116     support it. Read the comments in Imakefile and/or Makefile.QNX.
 117
 118   - If, during the build, you get complaints of undefined data types and
 119     functions "Xpm" whatall, it's because you've built VTWM with XPM image
 120     support, and either you don't have the XPM library available, or it's
 121     not a recent enough version (3.4h is the earliest I know of). Read the
 122     comments in Imakefile and/or Makefile.QNX.
 123
 124   - If, during the build, you get complaints of an undefined data type
 125     "regex_t" or functions "reg" whatall, it's because you've built VTWM
 126     with regular expressions ("RE"s) support, and either you don't have
 127     regex support, or it's not POSIX 1003.2 compliant. Read the comments
 128     in Imakefile and/or Makefile.QNX.
 129
 130   - If, during the build, you get complaints of an undefined data type
 131     "RPLAY" or functions "rplay" whatall, it's because you've built VTWM
 132     with sound support and you don't have the rplay library available.
 133     Read the comments in Imakefile and/or Makefile.QNX.
 134
 135   - If, during the build, you get complaints of an unknown data type
 136     "Pixel", add "EXTRA_DEFINES=-DNEED_PIXEL_T" to the make command.
 137
 138   - If you expected HTML or Postscript man pages on build completion,
 139     or VTWM doesn't fall back on system resource files on startup, read
 140     the comments in Imakefile and/or Makefile.QNX.
 141
 142   - VNC users: If you regularly use a remote X desktop, you may want to
 143     add "EXTRA_DEFINES=-DORIGINAL_DRAWIT" to the make command. It seems
 144     that VTWM's diagonal resize/move lines are more expensive than TWM's
 145     horizontal and vertical lines. YMMV.
 146
 147   - Windows users: VTWM is known to build and run under Cygwin with DLL
 148     version 1.3.2. The Makefile may need a line "vtwm: vtwm.exe" added
 149     beneath the "all:: vtwm" line for a successful build. The INSTALL
 150     file and the /usr/X11R6/lib/X11/twm directory may have to be "moved
 151     out of the way" for a successful installation.
 152
 153
 154 RUNTIME HINTS
 155 =============
 156
 157   - Prior to version 5.4.7, key and button bindings were dependent on
 158     various "shift states". Version 5.4.7 can ignore these; check out
 159     the IgnoreModifiers variable.
 160
 161   - As of version 5.4.7, all window moves and resizes initiated at the
 162     virtual desktop will end there (previous behavior was to leave the
 163     pointer at the window). Bind a function like
 164         Function "move-or-warp" { f.move f.deltastop f.warp }
 165     to a button and the desktop context with something like
 166         Button2 = : desktop : f.function "move-or-warp"
 167     to approximate previous behavior.
 168
 169   - As of version 5.4.7, the raise that normally accompanies moves and
 170     resizes occurs at operation end, to preserve window stacking order
 171     on cancellation. Set the RaiseOnStart variable for previous behavior.
 172
 173   - The SunkFocusHighlightWindow variable was depreciated in version
 174     5.4.7. Set the TitleHighlight argument of the Pixmaps variable to
 175     an appropriate built-in pixmap.
 176
 177   - If, on startup, things are coming up weird (if at all!), check the
 178     resource file for m4 macros, and if found, see that VTWM is version
 179     5.4.6 or later, that it was built with m4 support, that "-m" is in
 180     the line that starts VTWM, and that m4 is in $(PATH).
 181
 182   - The UseRealScreenBorder variable was depreciated in version 5.4.6.
 183     If the RealScreenBorderWidth variable is non-zero, why wouldn't you
 184     want to use it?
 185
 186   - As of version 5.4.6, random zooms during deiconification won't occur
 187     unless the ZoomZoom variable is set.
 188
 189   - If you use any of the 3D resources from versions before 5.4.5, you
 190     will find that they generate errors on startup. They no longer exist!
 191     See the man page or the CHANGELOG file for the new resources (look
 192     for the word "Bevel").
 193
 194   - If you use a SqueezeTitle list from versions before 5.4.4, you may
 195     want to check the man page to see if the new enterpretation of the
 196     resource's list parameters fouls your setup.
 197
 198   - See also the man page, and the SOUND and BUGS files in doc/.
 199