X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/acbd13a365fe2bd7ed6bafd19dc26775a256d499..6a1c4604fca992329679a63dfc4a9424a28740f5:/docs/motif/install.txt diff --git a/docs/motif/install.txt b/docs/motif/install.txt index d6b5d2a62f..2cbb7cb91d 100644 --- a/docs/motif/install.txt +++ b/docs/motif/install.txt @@ -1,147 +1,526 @@ -wxWindows 2.0 for Motif installation +wxWindows 2.3 for Motif installation ------------------------------------ +IMPORTANT NOTE: + + 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.3.0, egcs 1.1.1, Redhat 5.0 + +First steps +----------- + - Prerequisites: Motif 1.2 or above, or Lesstif (not yet tested). Motif 2.0 and above may also be suitable. -- Download the files wx200gen.zip and wx200mot.zip, and - documentation in a preferred format, such as wx200htm.zip - or wx200pdf.zip. +- Download wxMotif-x.y.z.tgz, where x.y.z is the version number. + Download documentation in a preferred format, such as + wxWindows-HTML.zip or wxWindows-PDF.zip. -- 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. +- Make a directory such as ~/wx and unarchive the files into this + directory. - It is recommended that you install bison and flex; using yacc and lex may require tweaking of the makefiles. You also need - Xpm (see comments in the Notes section below). + 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. -- You now have the option of using the configure-based system, - or the simple makefile system. Configure is more hard to debug - if things go wrong, but may be easier to use if they go OK :-) - Makefiles are easier to tweak. COMPILING USING CONFIGURE ========================= -- You can use the wxGTK configure system to make wxMotif, or - you can follow the following steps to use the simpler (but - less automatic) makefile system. If using configure, the - following script should make the library and samples, when - run from the top-level wxWindows directory (see also 'makewxmotif' - in this directory). 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. - # -- Julian Smart - chmod a+x configure config.sub config.guess setup/general/* setup/shared/* - ./configure --with-shared --with-motif --without-gtk --with-debug_flag --with-debug_info --without-threads - make makefiles - make - -------:x-----Cut here-----:x----- +* The most simple case +----------------------- - This script will build wxMotif using shared libraries. +If you compile wxWindows on Linux for the first time and don't like to read +install instructions just do (in the base dir): -- Change directory to a sample e.g. samples/minimal, and type make. - The binary will end up under the Linux (or other appropriate) subdirectory. +> ./configure --with-motif +> make +> su +> make install +> ldconfig +> exit -- To build an application outside the wxWindows hierarchy, you can - use `wx-config --cflags` when compiling source files and `wx-config --libs` - when linking, where wx-config is in the wxWindows root directory. - These invocations return the appropriate flags for the compiler. +Afterwards you can continue with -- When compiling certain utilities such as Dialog Editor, you may find - that the makefile refers to wx-config as above. Unless you have used - "make install" to install wxWindows, wx-config won't be found, so - either edit the makefile to hard-wire the flags, or place wx-config - where it will be found by the makefile. +> 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 concurretly. 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 most simple errors +------------------------ + +You get errors during compilation: The reason is that you probably have a broken +compiler, which includes almost everything that is called gcc. If you use gcc 2.8 +you have to disable optimsation as the compiler will give up with an internal +compiler error. + +If there is just any way for you to use egcs, use egcs. We cannot fix gcc. + +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 broken compiler (and its optimisation) such as GCC 2.8. + +* The most simple program +------------------------- + +Now create your super-application myfoo.app and compile anywhere with + +g++ myfoo.cpp `wx-config --libs --cflags` -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, read my homepage at + + http://wesley.informatik.uni-freiburg.de/~wxxt + +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 GTK, WXGTK, 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 + - Stampede + - DLD 6.0 + - SuSE 6.0 + +You can disable thread support by running + +./configure "--disable-threads" +make +su +make install +ldconfig +exit + +NB: DO NOT COMPILE WXGTK WITH GCC AND THREADS, SINCE ALL PROGRAMS WILL +CRASH UPON START-UP! Just always use egcs and be happy. + +* Building wxGTK on OS/2 +-------------------------- + +Please send comments and question about the OS/2 installation +to Andrea Venturoli and patches to +the wxWindows mailing list. -COMPILING USING MAKEFILES -========================= +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). -- Choose a .env file from src/makeenvs that matches your - environment, and copy it to src/make.env. These are the - settings read by wxWindows for Motif makefiles. +Open an OS/2 prompt and switch to the directory above. +First set some global environment variables we need: -- Edit src/make.env to change options according to your local - environment. In particular, change WXDIR to where wxWindows is - found on your system, or set the WXWIN environment variable - before compilation, e.g.: +SET CXXFLAGS=-Zmtd -D__ST_MT_ERRNO__ +SET CFLAGS=-Zmtd -D__ST_MT_ERRNO__ +SET OSTYPE=OS2X +SET COMSPEC=sh - export WXWIN=/home/jacs/wx2 +Notice you can choose whatever you want, if you don't like OS2X. - Please feel free to contribute settings files for your environment. +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. -- Change directory to src/motif and type: +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 confiugre 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 deafult to GTK). + + --without-gtk Don't use the GIMP ToolKit (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 creation of + giving erros 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 confiugre 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 serialiasation. + + --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. ~/wxGTK +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 +directiry and type "make" there. + +Then you may install the library and it's 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 --cflags` -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` - make -f makefile.unx motif +minimal.o: minimal.cpp mondrian.xpm + $(CXX) `wx-config --cflags` -c minimal.cpp -o minimal.o - This should make the library libwx_motif.a in the lib - directory. Note that this makefile system does not build shared - libraries, only static ones (that is, the wxWindows library will be - linked statically; to see remaining dependencies on shared libraries, - type e.g. ldd minimal_motif). +clean: + rm -f *.o minimal + +This is certain to become the standard way unless we decide +to sitch 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. -- Make a sample, such as the minimal sample: +* Further notes by Julian Smart +--------------------------------- - cd samples/minimal - make -f makefile.unx motif +- 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. - and run the resulting minimal_motif binary. + -------: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----- -Notes: ------- + This script will build wxMotif using shared libraries. If you want to build + a static wxWindows library, use --disable-shared. -- Better installation and makefile systems are - required. A revised configure system is in preparation. +Troubleshooting +--------------- -- Debugging mode is switched on by default. 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). +- 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. -- 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. +- 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. -- Thread support is switched off by default in setup.h (wxUSE_THREADS) - because standard Unices often do not have the necessary thread library - installed. Please see ../docs/gtk/install.txt for more details on this. - For Linux, the problem is expected to go away with future - distributions of the operating system. +- If you get an internal compiler error in gcc, turn off optimisations. -- If you have trouble compiling the file y_tab.c, or have strange - linking errors, check whether you're using a C or C++ compiler for this file. - You should specify a C compiler in the CCLEX variable in src/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). -- If you run into problems with a missing X11/Xpm.h header, you - need to install the XPM package. It can be obtained from: +- 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. - ftp://ftp.x.org/contrib/libraries/xpm-3.4k.tar.gz - http://sunfreeware.com +Other Notes +----------- - You may need to modify make.env to add -I and -L options pointing to where Xpm - is installed and possibly change bitmap.cpp to - include instead of +- 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, January 1999. -julian.smart@ukonline.co.uk