0.51.1 pre snapshot. Be careful, it may be buggy. It fixes some bugs though.
[wmaker-crm.git] / INSTALL
blob91bc05e056929a0ece83e381375df373d8f4c304
2                 Installation Instructions for Window Maker
6 SUPPORTED PLATFORMS
7 ===================
8 (ie: I've heard someone has compiled it on...)
10 - Intel GNU/Linux Slackware 3.5 (primary platform)
11 - Intel GNU/Linux other distributions
12 - Sparc GNU/Linux RedHat 5.1
13 - PowerPC GNU/MkLinux
14 - Alpha GNU/Linux RedHat 5.1
15 - FreeBSD
16 - NetBSD
17 - OpenBSD
18 - Solaris 2.5.1, 2.5.2
19 - Solaris 2.6.0
20 - Solaris 2.7beta
21 - SCO Unix
22 - SGI Irix
23 - OSF/1
24 - HP-UX
25 - AIX 4.1.4 / IBM PowerPC
26 - AIX 4.3.1 / IBM CC compiler
27 - AIX 4.3.2 / IBM PowerPC
28 - AIX 5.3
29 - DEC Alpha/Digital UNIX 4.x
30 - XFree86 / OS/2
31 - Corel NetWinder
32 - SunOS 4.x
33 - PowerMac / Power MachTen 4.1.1 over MacOS
34 - Amiga 3000 running RedHat Linux 5.1 (Rawhide)
36 Patches to make it work on other platforms are welcome. 
38 If the latest version doesn't work for you, try 0.19.3, 
39 which is known to be pretty stable on many platforms.
42 REQUIREMENTS:
43 =============
45 The following software is required to use Window Maker:
47 - X11R6.x       
48         Window Maker can be compiled in older versions of X, like X11R5
49         (Solaris) or X11R4 (OpenWindows) but it will not work 100% correctly.
50         In such servers there will not be application icons and you'll have
51         trouble using the dock. Upgrading the client libraries (Xlib, Xt etc)
52         will help if you can't upgrade the server.
54 The following is required to build Window Maker:
56 - Basic obvious stuff
57         If you will build Window Maker, make sure you have gcc (or some
58         other ANSI C compiler) and the X header files installed. Specially
59         for newbie Linux users: you must install all X development packages
60         and the gcc suite. Otherwise you won't be able to build any X
61         program, including Window Maker.
63 - libPropList
64         This library can be found in ftp://ftp.windowmaker.org/pub/libs
65         or in ftp://ftp.gnome.org/pub/libPropList
66         Install it before building Window Maker.
68 - autoconf, automake and libtool
69         These tools are NOT needed, but IF you have one or
70         more of them installed, make sure you have ALL of the following 
71         with exactly these versions:
72                 autoconf 2.13
73                 automake 1.4
74                 libtool 1.2
75         If you have a different version, disable them by temporarily
76         renaming them to something else or uninstalling them from your
77         system. If you don't develop software you don't need them,
78         so you can safely uninstall. 
80 - lex (or flex) and yacc (or bison)
81         These are used by libPropList. lex is actually not needed since
82         it's output file is included, but either me or automake is stupid,
83         causing the configure script for libPropList to simply abort for no
84         convincent reason if lex is not found.
87 OPTIONAL:
88 =========
90 These libraries are not required to make Window Maker work, but they
91 are supported in case you want to use them. Version numbers are those
92 that I have (and therefore, guraranteed to work), but other versions
93 might work too. 
96 - libXPM 4.7 or newer
97         Older versions may not work!!! 
98         Available at ftp://sunsite.unc.edu/pub/Linux/libs/X/
100         There is builtin support for XPM files, but it will not
101         load images in some uncommon encodings.
103 - libpng 0.96 or newer and zlib     
104         For PNG image support.
106 - libtiff 3.4 or newer
107         For TIFF image support.
108         You can get it at ftp://ftp.sgi.com/graphics/tiff
110 - libjpeg 6.0.1 or newer
111         For JPEG image support
113 - libgif 2.2 or libungif
114         For GIF image support   
116 - GNU xgettext
117         If you want to use translated messages, you will need GNU gettext.
118         Other versions of gettext are not compatible and will not work.
119         Get the GNU version from ftp://ftp.gnu.org
121 Most of these can be get from ftp.uu.net/pub/graphics
124 CONFIGURE OPTIONS:
125 ==================
127 These options can be passed to the configure script to enable/disable
128 some Window Maker features. Example:
130 ./configure --enable-kanji
132 will configure Window Maker with kanji (and other multi-byte) characters
133 support compiled in.
136 To get a list of other options, run ./configure --help
138 --with-libs-from
139         specify additional paths for libraries to be searched.
140         The -L flag must precede each path, like:
141         --with-libs-from=-L/opt/libs -L/usr/local/lib
143 --with-incs-from
144         specify additional paths for header files to be searched.
145         The -I flag must precede each paths, like:
146         --with-incs-from=-I/opt/headers -I/usr/local/include
148 --enable-kanji
149         support to display Kanji characters, Korean, Chinese and other
150         languagues that require special characters.
152 --enable-single-icon
153         enables the collapsing of all appicons of the WM_CLASS+WM_INSTANCE
154         into a single one. This feature is not supported at all by the
155         developers. If you have some trouble with it, contact it's author:
156         Christopher Seawood <cls@seawood.org>
158 --disable-shm
159         disable use of the MIT shared memory extension. This will slow down
160         texture generation a little bit, but in some cases it seems to be
161         necessary due to a bug that manifests as messed icons and textures.
163 --disable-motif 
164         disable support for mwm window manager hints
166 --enable-openlook
167         enable support for OPEN LOOK(tm) window manager hints
169 --enable-gnome
170         enable support for GNOME window manager hints
172 --enable-kde
173         enable support for kde/kwm window manager hints
175 --enable-lite
176         remove things that are already supported in desktop environments,
177         like KDE and GNOME. Disabled things are: window list, root
178         applications menu, multiple window selection. Note that you will not
179         be able to exit Window Maker from itself anymore; you will have to
180         use kill with the SIGTERM signal or exit it from KDE. It is not
181         advisable to enable it.
183 --enable-modelock
184         XKB language status lock support. If you don't know what it is you
185         probably don't need it.
187 --enable-sound  
188         enable support of sound effects module
190 --disable-xpm   
191         disables use of the XPM library even if it is available on your
192         system.
194 --disable-png   
195         disables use of PNG library
197 --disable-tiff
198         disable use of TIFF library
200 --disable-gif
201         disable use of GIF library
203 --disable-jpeg
204         disable use of JPEG library
206 --disable-shape
207         disables shaped windows (for oclock, xeyes etc.)
209 --enable-debug
210         Do not use it unless you know what you're doing.
213 PLATFORM SPECIFIC NOTES:
214 ========================
216 - DEC/Alpha machines
217         You might need to pass the --disable-shm flag to configure, like
218         ./configure --disable-shm
220 - SCO Unix - run configure like
221         CFLAGS="-belf -DANSICPP" ./configure 
223 - SunOS, Solaris 
224         If you have gcc installed, run configure as:
225         CPP_PATH="gcc -E -x c" ./configure
226         Sun's cpp lacks some features needed by Window Maker and it can
227         cause problems when parsing the config files.
228         You also might need to use the --with-libs-from and --with-incs-from
229         to supply the directory where libtiff is located.
230         Someone mailed me that you also must make /usr/local/lib be the
231         first path in LD_LIBRARY_PATH to make it work.
233         If you have a Ultra Creator 3D or some other machine with high-end
234         graphics, be sure to start the X server with the default visual
235         set to 24bpp or you might experience problems with mangled colors.
236         This is a wmaker bug and will be fixed.
238 - GNU/Linux in general
239         Make sure you have /usr/local/lib in /etc/ld.so.conf and that you
240         run ldconfig after installing.
241         Uninstall any packaged version of Window Maker before installing a new
242         version. 
244 - RedHat GNU/Linux
245         RedHat systems have several annoying problems. If you use it, 
246         be sure to follow the steps below or Window Maker will not work:
248         * if you installed the Window Maker that comes with RedHat, uninstall
249         it before upgrading;
251         * make sure you don't have the LANG and LINGUAS environment variables
252         set to en_RN;
254         * make sure you have /usr/local/bin in your PATH environment
255         variable;
257         * make sure you have /usr/local/lib in /etc/ld.so.conf before running
258         ldconfig;
260         * if you have problems that mention an error message with --no-reexec
261         uninstall libtool-1.2b and install libtool-1.2 instead. libtool-1.2
262         can be found in ftp.gnu.org  Also read the TROUBLESHOOTING section;
264         * if you installed the Window Maker package from RedHat and are
265         installing a new version of it by hand (compiling yourself), uninstall
266         the package from RedHat before.
268         * make a symbolic link from /usr/X11 to /usr/X11R6
269         (type ln -s /usr/X11R6 /usr/X11 ) and make sure you have a symbolic
270         link from /usr/include/X11 to /usr/X11R6/include/X11 (if not,
271         type ln -s /usr/X11R6/include/X11 /usr/include/X11 )
273         * make sure you have /lib/cpp pointing to the cpp program
275         If you have any doubts in doing any of the stuff above, please
276         don't exitate to contact the RedHat user support. They will
277         kindly answer to all your questions regarding their system.
278         They also know much more about their own system than us 
279         (we don't use RedHat).
282 - PowerPC MkLinux
283         You will need to have the latest version of Xpmac. Older versions
284         seem to have bugs that cause the system to hang.
286 - Debian GNU/Linux
287         If you want JPEG and TIFF support, make sure you have libtiff-dev 
288         and libjpeg-dev installed.
290 - SuSE GNU/Linux
291         If you installed the Window Maker package from SuSE,
292         uninstall it before trying to compile wmaker or you
293         might have problems.
295 - MetroX (unknown version)
296         MetroX has a bug that corrupts pixmaps that are set as window
297         backgrounds. If you use MetroX and has weird problems with
298         textures, do not use textures in titlebars. Or use a different
299         X server.
301 INSTALLATION:
302 =============
304 Unpack WindowMaker-data.tar.gz and move the pixmaps directory in it
305 to /usr/local/share/pixmaps
307 You can get the file at ftp://ftp.windowmaker.org. This file is optional
308 and only have a few icons.
311 Build Window Maker
312 ------------------
313         For a quick start, type the following in your shell prompt:
315         ./configure
316         make
318 then, login as root and type:
320         make install
321         ldconfig
323 or if you want to strip the debugging symbols from the binaries and make them
324 smaller, you can instead type:
326         make install-strip
327         ldconfig
329 This will build and install Window Maker with default parameters.
331 If you want to customize some compile-time options, you can do the
332 following. 
334         1. (optional) Look at the CONFIGURE OPTIONS section above for the 
335         options available. Also run:
337         ./configure --help
339         to get a complete listing of other options that are available.
341         2. Run configure with the options you want. For example, if you
342         want to use the --enable-kanji option, type:
344         ./configure --enable-kanji
346         3. (optional) Edit src/wconfig.h with your favorite text editor 
347         and browse through it for some options you might want to change.
349         4. Compile. Just type:
351         make
353         5. Login as root (if you can't do that, read the "I don't have the 
354         root password :-(" section) and install Window Maker in your system:
355                 su root
356                 make install
359 User specific configuration
360 ---------------------------
362 These instructions do not need to be followed when upgrading Window Maker
363 from an older version, unless stated differently in the NEWS file.
365 Every user on your system that wishes to run Window Maker must do the
366 following:
368         1. Install Window Maker configuration files in your home directory.
369 Type:
370         wmaker.inst
372         wmaker.inst will install Window Maker configuration files and will
373 setup X to automatically launch Window Maker at startup.
375         That's it! 
376         
377         You can type "man wmaker" to get some general help for configuration
378 and other stuff.
380 Read the User Guide for a more in-depth explanation of Window Maker.
382 You might want to take a look at the FAQ too.
385 I don't have the root password :(
386 ---------------------------------
388 If you can't get superuser privileges (can't be root) you can install
389 wmaker in your own home directory. For that, supply the --prefix option
390 when running configure in step 2 of building Window Maker. You will
391 also need to supply the --with-appspath option, to specify the path for
392 WPrefs.app Example:
394 ./configure --prefix=/home/jshmoe --with-appspath=/home/jshmoe/GNUstep/Apps
397 Then make /home/jshmoe/bin be included in your search PATH, add
398 /home/jshmoe/lib to your LD_LIBRARY_PATH environment variable and run 
399 bin/wmaker.inst
401 Of course, /home/jshmoe is supposed to be replaced with your actual home
402 directory path.
406 UPGRADING
407 =========
409 If you are upgrading from an older version of Window Maker:
411         1. Configure and build Window Maker as always
412         2. Install Window Maker (but do not run wmaker.inst)
413         3. Read the NEWS file and update your configuration files, 
414            if necessary.
416 TROUBLESHOOTING
417 ===============
419 When you have some trouble during configuration (while running configure),
420 like not being able to use a graphic format library you think you have
421 installed, look at the config.log file for clues of the problem.
424 == Error when configuring
426 ltconfig: unrecognized option `--no-reexec'
427 Try `ltconfig --help' for more information.
428 configure: error: libtool configure failed
430 remove the --no-reexec option from aclocal.m4 and libPropList/aclocal.m4
431 and reconfigure
432 Also make sure the autoconf and automake versions you have installed are:
433 autoconf 2.13
434 automake 1.4
435 libtool 1.2
437 Note that it must not be libtool 1.2b, it must be libtool 1.2, 
438 from the GNU sites.
440 == Cant find proplist.h or libPropList.something
442 Download and install libPropList from the places pointed to
443 somewhere else in this file.
446 == configure doesn't detect libtiff, or other graphic libraries.
448 Delete config.cache, then rerun configure adding the following options to
449 configure (among the other options you use):
450 --with-libs-from="-L/usr/local/lib"
451 --with-incs-from="-I/usr/local/include -I/usr/local/include/tiff"
452 Put the paths where your graphic libs and their corresponding header files are
453 located. You can put multiple paths in any of these options, as the example
454 of --with-incs-from shows. Just put a space between them.
457 == configure doesn't detect libXpm. 
459 * Check if you have a symbolic link from libXpm.so.4.9 to libXpm.so
462 == Segmentation fault on startup
464 * Check if the version of libXPM you have is at least 4.7
466 * Check if you have an updated version of ~/GNUstep/Defaults/WindowMaker
468 If you're not sure, try renaming ~/GNUstep to ~/GNUtmp and then run wmaker.inst
470 == "...: your machine is misconfigured. gethostname() returned (none)"
472 * the hostname of your machine is set to something invalid, that starts
473         with a parenthesis. Do a man hostname for info about how to set it.
476 == The root menu contains only 2 entries. ("XTerm" and "Exit...")
478 * Window Maker is not finding cpp (the C preprocessor). If your cpp is
479 not located in /lib/cpp, edit src/config.h and correct the path in
480 CPP_PATH.
482 == checking lex output file root... configure: error: cannot find output from true; giving up
484 * Read the REQUIREMENTS section of this file.
487 LOCALES/INTERNATIONALIZATION
488 ============================
490 Window Maker has national language support. 
491 To enable national language support, you must compile
492 Window Maker with some additional parameters. 
494 0 - You must have the GNU gettext package installed. It can be
495 obtained at ftp://prep.ai.mit.edu/pub/gnu/gettext-nnn.tar.gz
497 Steps 1 to 3 can be skipped if you use the Install script.
499 1 - You have to select the languages you want to support. Set the
500 LINGUAS to the list of locales you want. English is always
501 suported. Example:
503 setenv LINGUAS "pt ja de"
504 in csh
508 export LINGUAS;LINGUAS="pt ja de"
509 in sh
511 The list of supported locales can be found in po/README.
512 English is the default language.
514 Read po/README if you wish to translate and maintain locale files 
515 for other languages.
517 2 - Additionally, if your language uses multi-byte characters, such
518 as Japanese or Korean, you must supply the --enable-kanji flag to configure.
520 3 - Configure, build and install Window Maker normally.
522 4 - To select a particular locale at runtime you must set the LANG
523 environment variable to the locale you want. For example, if you want to set
524 the portuguese locale, you must run
526 setenv LANG pt
528 in csh or
530 export LANG; LANG=pt
532 in Bourne sh and similars
534 Note: If you have the LC_CTYPE environment variable set, you must
535 unset it before running wmaker.
537 For menu definition files, Window Maker searches for them in the
538 following order (for brazilian portuguese, in this case):
540 menu.pt_BR
541 menu.pt
542 menu
545 5 - If you chose a language that uses multi-byte characters, you must
546 configure the fonts appropriately. Read the manual page for XCreateFontSet
547 to have more details about it. You must change the ~/G/D/WindowMaker file
548 for fonts used in titlebars, menus and other things. For fonts used in
549 dialog windows, change ~/G/D/WMGLOBAL. The %d in the font names must not be
550 removed. You can also use the supplied wsetfont script for the task.
551 Read the script itself for instructions.
553 For example, you can specify the following in ~/G/D/WindowMaker:
555 WindowTitleFont = "-*-helvetica-bold-r-normal-*-12-*,-*-*-medium-r-normal-*-14-*";
556 MenuTitleFont = "-*-helvetica-bold-r-normal-*-12-*,-*-*-medium-r-normal-*-14-*";
557 MenuTextFont = "-*-helvetica-medium-r-normal-*-12-*,-*-*-medium-r-normal-*-14-*";
558 IconTitleFont = "-*-helvetica-medium-r-normal-*-8-*,-*-*-medium-r-normal-*-12-*";
559 ClipTitleFont = "-*-helvetica-bold-r-normal-*-10-*,-*-*-medium-r-normal-*-12-*";
560 DisplayFont = "-*-helvetica-medium-r-normal-*-12-*,-*-*-medium-r-normal-*-12-*";
562 and in ~/G/D/WMGLOBAL:
564 SystemFont = "-*-*-medium-r-normal-*-%d-*-*-*-*-*-*-*";
565 BoldSystemFont = "-*-*-medium-r-normal-*-%d-*-*-*-*-*-*-*";
567 The above 2 fonts are only used by applications that use WINGs (WindowMaker
568 and WPrefs.app)