X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/f5ee2e5f8f9c3e2e25bb17123b602251cdd1963e..a2f2764dfb323c70488243f8aa791e2bf780cb0a:/docs/motif/install.txt diff --git a/docs/motif/install.txt b/docs/motif/install.txt index e59a709afb..efadc9ba07 100644 --- a/docs/motif/install.txt +++ b/docs/motif/install.txt @@ -1,132 +1,519 @@ -wxWindows 2.0 for Motif installation +wxWidgets 2.8.0 for Motif installation ------------------------------------ -IMPORTANT NOTE: If you experience problems installing, please -re-read this instructions and other related files (todo.txt, -bugs.txt etc.) carefully before mailing wxwin-users or -the author. Preferably, try to fix the problem first and -then send a patch to the author. +IMPORTANT NOTE: -- Prerequisites: Motif 1.2 or above, or Lesstif - (not yet tested). Motif 2.0 and above may also be suitable. + 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 wx-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 wxWidgets you are + using (including the beta) and what compiler on what system. One + example: wxMotif 2.8.0, gcc 2.95.4, Redhat 6.1 -- Download the files wx200gen.zip and wx200mot.zip, and - documentation in a preferred format, such as wx200htm.zip - or wx200pdf.zip. +First steps +----------- + +- Prerequisites: Motif 1.2 or above, or Lesstif. Motif 2.0 and + above may also be suitable. -- 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. +- 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 + wxWidgets-HTML.zip or wxWidgets-PDF.zip. - (See http://www.cdrom.com/pub/infozip/ if you don't have zip/unzip - already installed. Zip isn't the same as gzip!) +- 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 wxWidgets (recommended). + +- You can now use configure to build wxWidgets and the samples. + + Using configure is the only 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. +* The simplest case +------------------- - -------: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----- +If you compile wxWidgets on Linux for the first time and don't like to read +install instructions just do (in the base dir): - This script will build wxMotif using shared libraries. +> ./configure --with-motif +> make +> su +> make install +> ldconfig +> exit -- Change directory to a sample e.g. samples/minimal, and type make. - The binary will end up under the Linux (or other appropriate) subdirectory. +Afterwards you can continue with -- 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. +> make +> su +> make install +> ldconfig +> exit -- 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. +If you want to remove wxWidgets on Unix you can do this: -- If switching between wxMotif and wxGTK, you should remove the - config.cache file manually before running configure again. +> su +> make uninstall +> ldconfig +> exit -COMPILING USING MAKEFILES -========================= +* The expert case +----------------- -- 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. +If you want to do some more serious cross-platform programming with wxWidgets, +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 wxWidgets - you may also want to create different versions of wxWidgets +and test them concurrently. Most typically, this would be a version configured +with --enable-debug and one without. -- 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.: +For building three versions (one GTK, one Motif and a debug version of the GTK +source) you'd do this: - export WXWIN=/home/jacs/wx2 +mkdir buildmotif +cd buildmotif +../configure --with-motif +make +cd .. - Please feel free to contribute settings files for your environment. +mkdir buildgtk +cd buildgtk +../configure --with-gtk +make +cd .. -- Change directory to src/motif and type: +mkdir buildgtkd +cd buildgtkd +../configure --with-gtk --enable-debug +make +cd .. - make -f makefile.unx motif +Note that since wxWidgets-2.6.0 you can install all those libraries +concurrently, you just need to pass the appropriate flags when using them. - 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). +* The simplest errors +--------------------- -- Make a sample, such as the minimal sample: +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. - cd samples/minimal - make -f makefile.unx motif +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. - and run the resulting minimal_motif binary. +* The simplest program +---------------------- -Troubleshooting +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 wxWidgets use GNU configure. If you have problems with +your make use GNU make instead. + +If you have general problems with installation, see the wxWidgets website at + + http://www.wxwidgets.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 --------------- -- 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. - You could also try using bison and flex instead of yacc and - lex. +wxWidgets/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 +---------------------- + +wxWidgets/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, virtually all Linux distributions have +correct glibc 2 support. + +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 Stefan Neis and patches to +the wxWidgets mailing list. + +In the following list, the version numbers indicate the configuration that +was actually used by myself, newer version should cause no problems and +even older ones are expected to work most of the time. + +You'll need OS/2 Warp (4.51) or eCS(1.0), X-Free86/2 (3.3.6 or newer), +Lesstif (0.92.7 or newer), emx (0.9d fix 4), a Unix like shell (pdksh-5.2.14 +or ash), Autoconf (2.57), GNU file utilities (3.13), GNU text utilities (1.19), +GNU shell utilites (1.12), m4 (1.4), sed (2.05), grep (2.0), Awk (3.0.3), +GNU Make (3.75). + +Preferably, you should have Posix/2 installed and C(PLUS)_INCLUDE_PATH and +LIBRARY_PATH set up accordingly, however, wxGTK will even work without it. +Presence of Posix/2 will be auto-detected. + +Open an OS/2 prompt and switch to the directory above. +Set MAKESHELL or MAKE_SHELL (which one is needed depends on the version of +make) to a Unix like shell, e.g. +SET MAKESHELL=ash +If you have a really deficient version of GNU make, it might even be +necessary to set SHELL or even COMSPEC to a unix like shell as well. +Depending on your installation you might want to also set INSTALL, for me +it tends to try to use the system's tcpip\pcomos\install.exe which causes +problems, e.g. +SET INSTALL=/install-sh -c + +Notice that the delivered configure scripts are fully OS/2 aware, so you +can simply run + ash -c "configure --with-motif" +and make and possibly make install 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. + +* 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. + +* Building wxMotif on Cygwin +---------------------------- + +The normal build instructions should work fine on Cygwin. The one difference +with Cygwin is that when using the "--enable-shared" configure option (which +is the default) the API is exported explicitly using __declspec(dllexport) +rather than all global symbols being available. + +This shouldn't make a difference using the library and should be a little +more efficient. However if an export attribute has been missed somewhere you +will see linking errors. If this happens then you can work around the +problem by setting LDFLAGS=-Wl,--export-all-symbols. Please also let us know +about it on the wx-dev mailing list. + +* 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 wxWidgets 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. + + --enable-monolithic Build wxWidgets as single library instead + of as several smaller libraries (which is + the default since wxWidgets 2.5.0). + + --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 Equivalent to --enable-debug_info plus + --enable-debug-flag. + + --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 wxWidgets' 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 wxWidgets 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 wxWidgets 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. + + --without-libtiff Disables TIFF image format code. + + --without-expat Disable XML classes based on Expat parser. + + --disable-threads Disables threads. Will also + disable sockets. + + --disable-sockets Disables sockets. + + --disable-dnd Disables Drag'n'Drop. + + --disable-clipboard Disables Clipboard. + + --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. -- Solaris compilation with gcc: if the compiler has problems with the variable argument - functions, try putting the gcc fixinclude file paths early in the +Please see the output of "./configure --help" for comprehensive list +of all configurable options. + + +* 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 +Pentium 200 around 40 minutes. During compilation, you may 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 wxWidgets 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. + +If your application uses only some of wxWidgets libraries, you can +specify required libraries when running wx-config. For example, +`wx-config --libs=html,core` will only output link command to link +with libraries required by core GUI classes and wxHTML classes. See +the manual for more information on the libraries. + +2) The other way creates a project within the source code +directories of wxWidgets. 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 wxWidgets 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 --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 wxWidgets library, use --disable-shared. + +Troubleshooting +--------------- + +- 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. - 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. -- If you get an internal compiler error in gcc, turn off - optimisations. +- If you get an internal compiler error in gcc, turn off optimisations. - Problems with XtDestroyWidget crashing in ~wxWindow have been reported on SGI IRIX 6.4. This has not yet been resolved, so @@ -134,15 +521,6 @@ Troubleshooting possible temporary workaround (comment out the final XtDestroyWidget from ~wxWindow in window.cpp). -- If you use flex and bison instead of yacc and lex, you may need - to change the relevant part of src/motif/makefile.unx to read: - - ../common/y_tab.c: ../common/parser.y - $(YACC) ../common/parser.y - mv ../common/parser.tab.c ../common/y_tab.c - - (the 'mv' command needs to be changed) - - 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 @@ -151,47 +529,18 @@ Troubleshooting Other Notes ----------- -- Better installation and makefile systems are - required. A revised configure system is in preparation. - -- 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). - -- 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. - -- 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 run into problems with a missing X11/Xpm.h header, you - need to install the XPM package. It can be obtained from: - - ftp://ftp.x.org/contrib/libraries/xpm-3.4k.tar.gz - http://sunfreeware.com - - 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 - - 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). +- Using configure will create a release build of the library by + default: it's recommended to use --enable-debug configure switch + while developing your application. To compile in non-debug mode, use + --disable-debug configure switch. 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: +compiler and the error message(s) to the wxwin-developers mailing list at: + + wx-dev@lists.wxwindows.org - wxwin-users@wx.dent.med.uni-muenchen.de +Julian Smart, Robert Roebling and Vadim Zeitlin, November 1999. -Julian Smart, February 1999. -julian.smart@ukonline.co.uk