X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/2243eed57327ce844cfaf61f25b11cf372f96309..f24badde9a0efe4e2a18057045e044542f582158:/docs/motif/install.txt diff --git a/docs/motif/install.txt b/docs/motif/install.txt index 9d6bd53a91..4fbdde99a4 100644 --- a/docs/motif/install.txt +++ b/docs/motif/install.txt @@ -1,70 +1,524 @@ -wxWindows 2.0 for Motif installation +wxWindows 2.5 for Motif installation ------------------------------------ -- Prerequisites: Motif 1.2 or above, or - Lesstif (not yet tested). +IMPORTANT NOTE: -- Download the files wx200gen.zip and wx200mot.zip, and - documentation in a preferred format, such as wx200htm.zip - or wx200pdf.zip. + If you experience problems installing, please re-read these + instructions and other related files (todo.txt, bugs.txt and + osname.txt for your platform if it exists) carefully before + mailing wxwin-users or the author. Preferably, try to fix the + problem first and then send a patch to the author. + + When sending bug reports tell us what version of wxWindows you are + using (including the beta) and what compiler on what system. One + example: wxMotif 2.5.0, gcc 2.95.4, Redhat 6.1 -- Make a directory such as ~/wx and unzip the files into this - directory. Use the -a option if available to convert the ASCII - files to Unix format. Don't worry about files being - overwritten: they should be identical anyway. +First steps +----------- -- Edit src/make.env to change options according to your local - environment. In particular, change WXDIR to where wxWindows is - found on your system. - Later, there will be a better makefile system - and/or alternate make.env files as per wxWindows 1.68. - Please feel free to contribute settings files for your environment. +- Prerequisites: Motif 1.2 or above, or Lesstif. Motif 2.0 and + above may also be suitable. -- Change directory to src/motif and type: +- Download wxX11-x.y.z.tgz, where x.y.z is the version number. + (wxMotif is included in the wxX11 distribution). + Download documentation in a preferred format, such as + wxWindows-HTML.zip or wxWindows-PDF.zip. - make -f makefile.unx motif - - This should make the library libwx_motif.a in the lib +- Make a directory such as ~/wx and unarchive the files into this directory. -- Make a sample, such as the minimal sample: +- It is recommended that you install bison and flex; using yacc + and lex may require tweaking of the makefiles. You also need + libXpm (see comments in the Notes section below) if you want to have + XPM support in wxWindows (recommended). + +- You can now use configure to build wxWindows and the samples. + + Using configure is the recommended way to build the library. If it doesn't + work for you for whatever reason, please report it (together with detailed + information about your platform and the (relevant part of) contents of + config.log file) to wx-dev@lists.wxwindows.org. + + +COMPILING USING CONFIGURE +========================= + +* The simplest case +------------------- + +If you compile wxWindows on Linux for the first time and don't like to read +install instructions just do (in the base dir): + +> ./configure --with-motif +> make +> su +> make install +> ldconfig +> exit + +Afterwards you can continue with + +> make +> su +> make install +> ldconfig +> exit + +If you want to remove wxWindows on Unix you can do this: + +> su +> make uninstall +> ldconfig +> exit + +* The expert case +----------------- + +If you want to do some more serious cross-platform programming with wxWindows, +such as for GTK and Motif, you can now build two complete libraries and use +them concurrently. For this end, you have to create a directory for each build +of wxWindows - you may also want to create different versions of wxWindows +and test them concurrently. Most typically, this would be a version configured +with --enable-debug_flag and one without. Note, that only one build can +currently be installed, so you'd have to use local version of the library for +that purpose. For building three versions (one GTK, one Motif and a debug +version of the GTK source) you'd do this: + +md buildmotif +cd buildmotif +../configure --with-motif +make +cd .. + +md buildgtk +cd buildgtk +../configure --with-gtk +make +cd .. + +md buildgtkd +cd buildgtkd +../configure --with-gtk --enable-debug_flag +make +cd .. + +* The simplest errors +--------------------- + +You get errors during compilation: The reason is that you probably have a +broken compiler. GCC 2.8 and earlier versions and egcs are likely to cause +problems due to incomplete support for C++ and optimisation bugs. Best to use +GCC 2.95 or later. + +You get immediate segfault when starting any sample or application: This is +either due to having compiled the library with different flags or options than +your program - typically you might have the __WXDEBUG__ option set for the +library but not for your program - or due to using a compiler with optimisation +bugs. + +* The simplest program +---------------------- + +Now create your super-application myfoo.app and compile anywhere with + +g++ myfoo.cpp `wx-config --libs --cxxflags` -o myfoo + +* General +--------- + +The Unix variants of wxWindows use GNU configure. If you have problems with +your make use GNU make instead. + +If you have general problems with installation, see the wxWindows website at + + http://www.wxwindows.org/ + +for newest information. If you still don't have any success, please send a bug +report to one of our mailing lists (see my homepage) INCLUDING A DESCRIPTION OF +YOUR SYSTEM AND YOUR PROBLEM, SUCH AS YOUR VERSION OF MOTIF, WXMOTIF, WHAT +DISTRIBUTION YOU USE AND WHAT ERROR WAS REPORTED. I know this has no effect, +but I tried... + +* GUI libraries +--------------- + +wxWindows/Motif requires the Motif library to be installed on your system. As +an alternative, you may also use the free library "lesstif" which implements +most of the Motif API without the licence restrictions of Motif. + +You can get the newest version of the Lesstif from the lesstif homepage at: + + http://www.lesstif.org + +* Additional libraries +---------------------- + +wxWindows/Motif requires a thread library and X libraries known to work with +threads. This is the case on all commercial Unix-Variants and all +Linux-Versions that are based on glibc 2 except RedHat 5.0 which is broken in +many aspects. As of writing this, these Linux distributions have correct glibc +2 support: + + - RedHat 5.1 + - Debian 2.0 and 3.0 + - Stampede + - DLD 6.0 + - SuSE 6.0 + +You can disable thread support by running + +./configure --disable-threads +make +su +make install +ldconfig +exit + +* Building wxMotif on OS/2 +-------------------------- + +Please send comments and question about the OS/2 installation +to Andrea Venturoli and patches to +the wxWindows mailing list. + +You'll need OS/2 Warp (4.00FP#6), X-Free86/2 (3.3.3 or newer), +Lesstif (0.89.1 or newer), emx (0.9d fix 1), flex (2.5.4), +yacc (1.8), unix like shell, e.g. korn shell (5.2.13), +Autoconf (2.13), GNU file utilities (3.6), +GNU text utilities (1.3), GNU shell utilites (1.12), m4 (1.4), +sed (2.05), grep (2.0), Awk (3.0.3), GNU Make (3.76.1). + +Open an OS/2 prompt and switch to the directory above. +First set some global environment variables we need: + +SET CXXFLAGS=-Zmtd -D__ST_MT_ERRNO__ +SET CFLAGS=-Zmtd -D__ST_MT_ERRNO__ +SET OSTYPE=OS2X +SET COMSPEC=sh + +Notice you can choose whatever you want, if you don't like OS2X. + +Now, run autoconf in the main directory and in the samples, demos +and utils subdirectory. This will generate the OS/2 specific +versions of the configure scripts. Now run + configure --with-motif +as described above. + +To verify Lesstif installation, configure will try to compile a +sample program that requires X headers/libraries to be either +available via C_INCLUDE_PATH and LIBRARY_PATH or you need to +explicitly set CFLAGS prior to running configure. + +If you have pthreads library installed, it will be autodetected +and the library will be compiled with thread-support. + +Note that configure assumes your flex will generate files named +"lexyy.c", not "lex.yy.c". If you have a version which does +generate "lex.yy.c", you need to manually change the generated +makefile. + +* Building wxMotif on SGI +------------------------- + +Using the SGI native compilers, it is recommended that you +also set CFLAGS and CXXFLAGS before running configure. These +should be set to : + +CFLAGS="-mips3 -n32" +CXXFLAGS="-mips3 -n32" + +This is essential if you want to use the resultant binaries +on any other machine than the one it was compiled on. If you +have a 64bit machine (Octane) you should also do this to ensure +you don't accidently build the libraries as 64bit (which is +untested). + +The SGI native compiler support has only been tested on Irix 6.5. + +* Create your configuration +--------------------------- + +Usage: + ./configure [options] + +If you want to use system's C and C++ compiler, +set environment variables CXX and CC as + + % setenv CC cc + % setenv CXX CC + % ./configure options + +to see all the options please use: + + ./configure --help + +The basic philosophy is that if you want to use different +configurations, like a debug and a release version, +or use the same source tree on different systems, +you have only to change the environment variable OSTYPE. +(Sadly this variable is not set by default on some systems +in some shells - on SGI's for example). So you will have to +set it there. This variable HAS to be set before starting +configure, so that it knows which system it tries to +configure for. + +Configure will complain if the system variable OSTYPE has +not been defined. And Make in some circumstances as well... + + +* General options +------------------- + +Given below are the commands to change the default behaviour, +i.e. if it says "--disable-threads" it means that threads +are enabled by default. + +Many of the configure options have been thoroughly tested +in wxWindows snapshot 6, but not yet all (ODBC not). + +You have to add --with-motif on platforms, where Motif is +not the default (on Linux, configure will default to GTK). + + --with-motif Use either Motif or Lesstif + Configure will look for both. + +The following options handle the kind of library you want to build. + + --disable-threads Compile without thread support. Threads + support is also required for the + socket code to work. + + --disable-shared Do not create shared libraries. + + --disable-optimise Do not optimise the code. Can + sometimes be useful for debugging + and is required on some architectures + such as Sun with gcc 2.8.X which + would otherwise produce segvs. + + --enable-profile Add profiling info to the object + files. Currently broken, I think. + + --enable-no_rtti Enable compilation without creation of + C++ RTTI information in object files. + This will speed-up compilation and reduce + binary size. + + --enable-no_exceptions Enable compilation without creation of + C++ exception information in object files. + This will speed-up compilation and reduce + binary size. Also fewer crashes during the + actual compilation... + + --enable-no_deps Enable compilation without creation of + dependency information. + + --enable-permissive Enable compilation without checking for strict + ANSI conformance. Useful to prevent the build + dying with errors as soon as you compile with + Solaris' ANSI-defying headers. + + --enable-mem_tracing Add built-in memory tracing. + + --enable-dmalloc Use the dmalloc memory debugger. + Read more at www.letters.com/dmalloc/ + + --enable-debug_info Add debug info to object files and + executables for use with debuggers + such as gdb (or its many frontends). + + --enable-debug_flag Define __DEBUG__ and __WXDEBUG__ when + compiling. This enable wxWindows' very + useful internal debugging tricks (such + as automatically reporting illegal calls) + to work. Note that program and library + must be compiled with the same debug + options. + +* Feature Options +----------------- + +Many of the configure options have been thoroughly tested +in wxWindows snapshot 6, but not yet all (ODBC not). + +When producing an executable that is linked statically with wxGTK +you'll be surprised at its immense size. This can sometimes be +drastically reduced by removing features from wxWindows that +are not used in your program. The most relevant such features +are + + --without-libpng Disables PNG image format code. + + --without-libjpeg Disables JPEG image format code. + +{ --without-odbc Disables ODBC code. Not yet. } + + --disable-resources Disables the use of *.wxr type + resources. + + --disable-threads Disables threads. Will also + disable sockets. + + --disable-sockets Disables sockets. + + --disable-dnd Disables Drag'n'Drop. + + --disable-clipboard Disables Clipboard. + + --disable-serial Disables object instance serialisation. + + --disable-streams Disables the wxStream classes. + + --disable-file Disables the wxFile class. + + --disable-textfile Disables the wxTextFile class. + + --disable-intl Disables the internationalisation. + + --disable-validators Disables validators. + + --disable-accel Disables accel. + +Apart from disabling certain features you can very often "strip" +the program of its debugging information resulting in a significant +reduction in size. + +* Compiling +----------- + +The following must be done in the base directory (e.g. ~/wxMotif +or ~/wxWin or whatever) + +Now the makefiles are created (by configure) and you can compile +the library by typing: + + make + +make yourself some coffee, as it will take some time. On an old +386SX possibly two weeks. During compilation, you'll get a few +warning messages depending in your compiler. + +If you want to be more selective, you can change into a specific +directory and type "make" there. + +Then you may install the library and its header files under +/usr/local/include/wx and /usr/local/lib respectively. You +have to log in as root (i.e. run "su" and enter the root +password) and type + + make install + +You can remove any traces of wxWindows by typing + + make uninstall + +If you want to save disk space by removing unnecessary +object-files: + + make clean + +in the various directories will do the work for you. + +* Creating a new Project +------------------------ + +1) The first way uses the installed libraries and header files +automatically using wx-config + +g++ myfoo.cpp `wx-config --libs` `wx-config --cxxflags` -o myfoo + +Using this way, a make file for the minimal sample would look +like this + +CXX = g++ + +minimal: minimal.o + $(CXX) -o minimal minimal.o `wx-config --libs` + +minimal.o: minimal.cpp mondrian.xpm + $(CXX) `wx-config --cxxflags` -c minimal.cpp -o minimal.o + +clean: + rm -f *.o minimal + +This is certain to become the standard way unless we decide +to stick to tmake. + +2) The other way creates a project within the source code +directories of wxWindows. For this endeavour, you'll need +GNU autoconf version 2.14 and add an entry to your Makefile.in +to the bottom of the configure.in script and run autoconf +and configure before you can type make. + +* Further notes by Julian Smart +--------------------------------- + +- You may find the following script useful for compiling wxMotif, + especially if installing from zips (which don't preserve file + permissions). Make this script executable with the command + chmod a+x makewxmotif. + + -------:x-----Cut here-----:x----- + # makewxmotif + # Sets permissions (in case we extracted wxMotif from zip files) + # and makes wxMotif. + # Call from top-level wxWindows directory. + # Note that this uses standard (but commonly-used) configure options; + # if you're feeling brave, you may wish to compile with threads: + # if they're not supported by the target platform, they will be disabled + # anyhow + # -- Julian Smart + chmod a+x configure config.sub config.guess + ./configure --with-shared --with-motif --without-gtk --with-debug_flag --with-debug_info --enable-debug --without-threads --without-sockets --without-odbc + make + -------:x-----Cut here-----:x----- + + This script will build wxMotif using shared libraries. If you want to build + a static wxWindows library, use --disable-shared. - cd samples/minimal - make -f makefile.unx motif +Troubleshooting +--------------- - and run the resulting minimal_motif binary. +- Solaris compilation with gcc: if the compiler has problems with the variable + argument functions, try putting the gcc fixinclude file paths early in the + include path. -Notes: ------- +- If you operator-related compile errors or strange memory problems + (for example in deletion of string arrays), set wxUSE_GLOBAL_MEMORY_OPERATORS + and wxUSE_MEMORY_TRACING to 0 in setup.h, and recompile. -- Better installation and makefile systems are - required. I didn't use the wxGTK system because I couldn't - understand it or make it work with wxMotif. Also I think - we should use something that can be made to work easily - with applications outside the wxWindows hierarchy. +- If you get an internal compiler error in gcc, turn off optimisations. -- Debugging mode is switched on by default. To compile in non-debug - mode, remove the -D__WXDEBUG__ switch in make.env. +- Problems with XtDestroyWidget crashing in ~wxWindow have been + reported on SGI IRIX 6.4. This has not yet been resolved, so + any advice here would be very welcome. See bugs.txt for a + possible temporary workaround (comment out the final + XtDestroyWidget from ~wxWindow in window.cpp). -- Some classes can be switched off in include/wx/motif/setup.h, - if you are having trouble with a particular file. However, - I'd prefer you to fix the problem and send the fix to me :-) or at - least let me know about it. +- Some compilers, such as Sun C++, may give a lot of warnings about + virtual functions being hidden. Please ignore these, it's correct C++ syntax. + If you find any incorrect instances, though, such as a + missing 'const' in an overridden function, please let us know. -- If you run into problems with a missing X11/Xpm.h header, you - need to install the XPM package. It can be obtained from: +Other Notes +----------- - ftp://ftp.x.org/contrib/libraries/xpm-3.4k.tar.gz +- Debugging mode is switched on by default in the makefiles, but using + configure will create a release build of the library by default: it's + recommended to use --with-debug_info and --with-debug_flag configure + switches while developing your application. To compile in non-debug + mode, remove the -D__WXDEBUG__ switch in make.env (or if using the + configure system, change --with-debug_flag to --without_debug_flag + and --with-debug_info to --without-debug_info in the makewxmotif + script). - Alternatively, edit include/motif/setup.h, set wxUSE_XPM - to 0, and recompile. You will not be able to load any XPMs, - though (currently the only supported colour bitmap format). +Bug reports +----------- -- Please send bug reports with a description of your environment, - compiler and the error message(s) to the wxwin-users mailing list at: +Please send bug reports with a description of your environment, +compiler and the error message(s) to the wxwin-developers mailing list at: - wxwin-users@wx.dent.med.uni-muenchen.de + wx-dev@lists.wxwindows.org +Julian Smart, Robert Roebling and Vadim Zeitlin, November 1999. -Julian Smart, November 1998. -julian.smart@ukonline.co.uk