X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/c98f04213ed354d0116092e87a30db5dc69c5709..9d6a9fdd13ab25f0ac7c54a3ec8098f8b5c1d118:/docs/gtk/install.txt diff --git a/docs/gtk/install.txt b/docs/gtk/install.txt index 24286b8abf..93401c727d 100644 --- a/docs/gtk/install.txt +++ b/docs/gtk/install.txt @@ -1,420 +1,488 @@ -* The most simple case ------------------------ +wxWidgets 2.5 for GTK 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. -If you compile wxWindows on Unix for the first time and don't like -to read install instructions just do (in the base dir): + When sending bug reports tell us what version of wxWidgets you are + using (including the beta) and what compiler on what system. One + example: wxGTK 2.4.0, gcc 2.95.4, Redhat 6.2 -./configure --with-gtk --with-shared --without-threads +* The simplest case +------------------- + +If you compile wxWidgets on Linux for the first time and don't like to read +install instructions just do (in the base dir): + +> ./configure --with-gtk +> make +> su +> make install +> ldconfig +> exit + +Afterwards you can continue with + +> make +> su +> make install +> ldconfig +> exit + +If you want to remove wxWidgets on Unix you can do this: + +> su +> make uninstall +> ldconfig +> exit + +* The GTK+ 2 case +----------------- + +wxGTK has support for the new version 2.0.X of GTK+ since version 2.4.0. +This means that wxGTK apps can now make use Unicode as the underlying encoding +for all text operations. This is a very fundamental change and will need time +to stabilize, so be careful. Anyways, after installing a recent version of GTK+ +2.0, do this + +> ./configure --with-gtk --enable-gtk2 --enable-unicode +> make +> su +> make install +> ldconfig +> exit + +If you are adventurous, you can install the FcConfig 2.0 package +and the Pango library from CVS (or a very recent snapshot from +the upcoming 1.2 series) and set do "export GDK_USE_XFT=1" so +that the display as well as the printing code will use render +using the same FreeType code even for Far Eastern encodings. + +Expect problems. + +* The expert case +----------------- + +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. 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 +make +cd .. + +* The simplest errors +--------------------- + +For any configure errors: please look at config.log file which was generated +during configure run, it usually contains some useful information. -and drink 10 coffees. +configure reports, that you don't have GTK 1.2 installed although you are +very sure you have. Well, you have installed it, but you also have another +version of the GTK installed, which you may need to remove including other +versions of glib (and its headers). Or maybe you installed it in non default +location and configure can't find it there, so please check that your PATH +variable includes the path to the correct gtk-config. Also check that your +LD_LIBRARY_PATH or equivalent variable contains the path to GTK+ libraries if +they were installed in a non default location. +You get errors from make: please use GNU make instead of the native make +program. Currently wxWidgets can be built only with GNU make, BSD make and +Solaris make. Other versions might work or not (any which don't have VPATH +support definitely won't). + +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. + +Linker complains about missing PROIO_yy_flex_alloc and similar symbols: you +probably have an old version of flex, 2.5.4 is recommended. + +* The simplest program +---------------------- + +Now create your super-application myfoo.cpp 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. -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 -Read my homepage at + http://wesley.informatik.uni-freiburg.de/~wxxt/ - http://wesley.informatik.uni-freiburg.de/~wxxt - -for newest information. +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 requires a GUI toolkit to be installed. Does that make -sense? So far only the GTK is supported, but we hope to provide -the choice between GTK, Qt, Motif/Lesstif in the not so distant -future. +wxWidgets/GTK requires the GTK+ library to be installed on your system. It has +to be a stable version, preferably version 1.2.10 (at least 1.2.3 is required, +1.2.7 is strongly recommended). -You can get the newest version of the GTK from the GTK homepage -at - http://www.gtk.org - -The newest versin of Qt can be downloaded for free from the Trolltec's -site at - http://www.troll.no +You can get the newest version of the GTK+ from the GTK homepage at: -Lesstif can be downloaded from their site -at - http://www.lesstif.org + http://www.gtk.org -If you want to develop using Motif, you need to buy it, unless it comes -with your operating system such as all commercial Unices, as well as -RedHat's, SuSe's and probably other's Linux Motif editions. +We also mirror GTK+ at my ftp site. You'll find information about downloading +at my homepage. * Additional libraries +---------------------- + +wxWidgets/Gtk 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 wxGTK 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), +GTK+ (1.2.5 or newer), emx (0.9d fix 4), flex (2.5.4), yacc (1.8) or +bison (1.25), 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 (and depending on your installation also INSTALL, for me +it tends to try to use the system's tcpip\pcomos\install.exe which causes +problems...) to a Unix like shell, e.g. +SET MAKESHELL=ash + +Be warned that depending on the precise version of your make, the +variable that needs to be set might be MAKE_SHELL instead of MAKESHELL. +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. + +Notice that the delivered configure scripts are fully OS/2 aware, so you +can simply run + ash -c "configure --with-gtk" +and make and possibly make install as described above. + +* Building wxGTK on SGI ----------------------- -There will be a few more features of wxWindows, which will -require further libraries (on some platforms). These -features will be optional. I hope to teach configure -to check that out automatically. - -Thread support: - - Requires pthreads under Linux with glibc 2. pthreads are - always present on such systems, so just compile, unless - you have RedHat 5.0, which has a broken combination of - glibc 2 and X. In this case, you have to run configure - with "--without-threads". - - Requires PCthreads under Linux with libc 5. If you - haven't installed pcthreads, there will be no thread - support in wxWindows, but the library will compile. - - Requires Posix threads on commercial Unix system, - which are always present. Just compile. - - On SGI Irix we first look for sprocs, then pthreads and - use the last one found. - -Python scripting language support: - - Requires Python. Soon to come. - -* Other things to do ------------------------------ - -wxGTK and wxMotif/wxLesstif require the built-in -ImLib/GdkImlib to be configured. For that purpose -copy the two files from /misc/imlib to your -home directory and rename "imrc" -> ".imrc". -You may also edit imrc by hand as you like. -The palette file is required when using -wxWindows in 256-colour mode. - -If you want to use wxWindows's ODBC support, you'll have -to create a .odbc.ini file. The readme file in -~/src/iodbc tells you what to do. +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 + ./configure options If you want to use system's C and C++ compiler, set environment variables CC and CCC as - % setenv CC cc - % setenv CCC CC - % ./configure options + % setenv CC cc + % setenv CXX CC + % ./configure [options] -Using the SGI native compilers, it is recommended that you -also set CFLAGS and CXXFLAGS before running configure. These -should be set to : +to see all the options please use: -CFLAGS="-mips3 -n32" -CXXFLAGS="-mips3 -n32" + ./configure --help -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). +It is recommended to build wxWidgets in another directory (maybe a +subdirectory of your wxWidgets installation) as this allows you to +have multiple configurations (for example, debug and release or GTK +and Motif) simultaneously. -The SGI native compiler support has only been tested on Irix 6.5. -to see all the options please use: +* General options +----------------- - ./configure --help +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. -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. +Normally, you won't have to choose a toolkit, because when +you download wxGTK, it will default to --with-gtk etc. But +if you use all of our CVS repository you have to choose a +toolkit. You must do this by running configure with either of: -Configure will complain if the system variable OSTYPE has -not been defined. And Make in some circumstances as well... + --with-gtk Use the GIMP ToolKit (GTK). Default. + --with-motif Use either Motif or Lesstif + Configure will look for both. -* General options -------------------- +The following options handle the kind of library you want to build. -Obviously, you have to choose a toolkit. You must do this by -running configure with either of + --disable-threads Compile without thread support. - --with-gtk Use the GIMP ToolKit (GTK) - - --with-qt Use Qt from TrollTec - - --with-motif Use either Motif or Lesstif - Configure will look for both. + --disable-shared Do not create shared libraries, but + build static libraries instead. -The following options handle the kind of library you want to build. + --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. - --without-threads Compile without thread support. + --enable-mem_tracing Add built-in memory tracing. - --with-shared Create shared libraries. + --enable-dmalloc Use the dmalloc memory debugger. + Read more at www.letters.com/dmalloc/ - --without-optimise Do not optimise the code. + --enable-debug_info Add debug info to object files and + executables for use with debuggers + such as gdb (or its many frontends). - --with-profile Add profiling info to the object - files. Currently broken, I think. - - --with-mem_tracing Add built-in memory tracing. - This doesn't work well with gcc. - - --with-dmalloc Use the dmalloc memory debugger. - Read more at www.letters.com/dmalloc/ - - --with-debug_info Add debug info to object files and - executables. + --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. - --with-debug_flag Define __DEBUG__ and __WXDEBUG__ when - compiling. + --enable-debug Same as --enable-debug_info and + --enable-debug_flag together. Unless you have + some very specific needs, you should use this + option instead of --enable-debug_info/flag ones + separately. * Feature Options -------------------- +----------------- -When using the Windows version of wxWindows, it is possible -to edit the file /include/wx/msw/setup.h in order to enable -or disable some features of wxWindows so that the resulting -binaries get smaller. +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 -As I don't yet care for binary size and target mainly at -producing a shared library, wxWindows's configure system auto- -matically enables all features, as long as they are already -implemented. + --with-odbc Enables ODBC code. This is disabled + by default because iODBC is under the + L-GPL license which is less liberal than + wxWidgets license. -* Compiling -------------- + --without-libpng Disables PNG image format code. -The following must be done in the base directory (e.g. ~/wxGTK -or ~/wxWin) + --without-libjpeg Disables JPEG image format code. + + --without-libtiff Disables TIFF image format code. + + --without-expat Disable XML classes based on Expat parser. + + --disable-pnm Disables PNM image format code. + + --disable-gif Disables GIF image format code. + + --disable-pcx Disables PCX image format code. + + --disable-iff Disables IFF image format code. + + --disable-resources Disables the use of *.wxr type resources. -First you have to create all makefiles in all subdirectories: + --disable-threads Disables threads. Will also disable sockets. - make Makefiles + --disable-sockets Disables sockets. -Dependencies are generated automatically using + --disable-dnd Disables Drag'n'Drop. - make depend - -(For some reason, this doesn't seem to work completely.) + --disable-clipboard Disables Clipboard. -Now the makefiles are created you can compile everything is as simple -as typing: + --disable-serial Disables object instance serialisation. - make + --disable-streams Disables the wxStream classes. -make yourself some coffee, as it will try to compile -ALL the files in this distribution. + --disable-file Disables the wxFile class. -if you want to be more selective: + --disable-textfile Disables the wxTextFile class. - make src will build only the base libraries - make utils will build the utils - make samples will build the samples - make other will build the other samples - make user will build the files in the directory other + --disable-intl Disables the internationalisation. -Depending on the configuration of some files, the libraries -and binaries will be placed in different directories. -The "global" binaries and libraries will be placed in: + --disable-validators Disables validators. - bin/$(OSTYPE) and - lib/$(OSTYPE) respectively + --disable-accel Disables accelerators support. -"local" binaries and libraries will be placed in: +Apart from disabling certain features you can very often "strip" +the program of its debugging information resulting in a significant +reduction in size. - (basedir of that application)/$(OSTYPE). +Please see the output of "./configure --help" for comprehensive list +of all configurable options. -This is also the place where all the object-files will go. -If you want to conserve disk space by removing unnecessary +* 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 +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_obj +make clean -will do the work for you. +in the various directories will do the work for you. * Creating a new Project -------------------------- -I propose to put all contributed programs in the directory -"~/wxWin/user", with a directory of its own. +1) The first way uses the installed libraries and header files +automatically using wx-config + +g++ myfoo.cpp `wx-config --cxxflags --libs` -o myfoo + +Using this way, a make file for the minimal sample would look +like this + +CC = gcc -This directory then should include the following files: +minimal: minimal.o + $(CC) -o minimal minimal.o `wx-config --libs` -Makefile (You can copy this one from any application in samples - probably you will not need to edit this one. There is - only one case where you might be interested in changing - this file, but about that see later.) -Makefile.in (This is the base application-Makefile template, from - which the actual Makefile for each system is created. - More about this later) +minimal.o: minimal.cpp mondrian.xpm + $(CC) `wx-config --cxxflags` -c minimal.cpp -o minimal.o -put ALL your source code along with all the other stuff you need for -your application in this directory (subdirectories are welcome). - -** Something about Makefiles ------------------------------- - -On general principle it should only contain ONE line, which is as follows: - - include ../../setup/general/makeapp - -this will include all the necessary definitions for creating the applications - -the only case where you might want to add another line is the following: -this version of configure also supports creation of source archives of the -application for easy distribution and updates to newer version of wxWindows. - For this purpose all files in the application-directory will be put into -a gziped tar-file in the full notation user//* -if you want to include some other files that you want "more visible", like -a README. or a shell script for easy -compilation/installation/distribution, then you have to add a variable - - DISTRIBUTE_ADDITIONAL= - -to the Makefile. -So it would look like this: - - DISTRIBUTE_ADDITIONAL=README.TheApp - include ../../setup/general/makeapp - -As we have already talked about distribution the command to create a -distribution is: - - make distrib - -NOTE: If you are in the base directory of wxWindows it will create -distribution packages for wxWindows as well as for all packages in the -user directory. - So if you want to create only packages for the files in user, -then go to the directory other and type: - - make distrib - -or if you only want one application to be created then -enter the specific directory and type there: -make distrib - -All the distribution files will be put in the directory -distrib at the base of the wxWindows-tree (where also configure -and template.mak can be found). - -** Something about Makefile.in --------------------------------- - -As you have already seen with Makefile, configure makes a lot of use -if the include statement in make to keep the Makefiles as simple as -possible. - -So basically there are only variables to define and then a include command. -Exception to this rule is if you have special rules for some stuff... -These rules should go AFTER the include statement!!! - -so the general header looks like this: - - # wxWindows base directory - WXBASEDIR=@WXBASEDIR@ - # set the OS type for compilation - OS=@OS@ - # compile a library only - RULE=bin - -and the general footer will look like this: - - # include the definitions now - include ../../../template.mak - -the key variable is RULE, which defines what make should create -in this directory. - -here are some examples: - - RULE description - =========================================================================== - bin creates a local binary (for a global binary prefix bin with g) - additional variables needed: - BIN_TARGET this gives the name of your application - BIN_OBJ this gives the object files needed to - link the application - optional variables are: - BIN_SRC this gives the list of c/c++ files for - which dependencies will be checked. - (This can be achieved with: make depend) - BIN_LINK this gives commands for additional - libraries needed to link the application - --------------------------------------------------------------------------- - bin2 creates two local binaries (for global binaries prefix bin2 with g) - in addition to the variables specified above you MUST also - provide the same variables with BIN2_ instead of BIN_ - --------------------------------------------------------------------------- - lib creates a local library (for a global binary prefix bin with g) - additional variables needed: - LIB_TARGET this gives the name of your library - LIB_OBJ this gives the object files needed for - the library to be build. - optional variables are: - LIB_SRC this gives the list of c/c++ files for - which dependencies will be checked. - libbin and libgbin are also possible and will need in addition - the variables from bin - --------------------------------------------------------------------------- - gslib is similar to lib, but it creates a shared library if the system - supports it. - additional variables needed: - LIB_MAJOR major number of the shared library - LIB_MINOR minor number of the shared library - --------------------------------------------------------------------------- - other additional variables: - - ADD_COMPILE define additional includes/defines that - are needed to compile the object files - (if you need to reference some directory - utils - like wxGrid -, then please - reference them with the variables defined - in template.mak - e.g.: $(SRCDIR),$(UTILS), - $(SAMPLES),$(OTHERS)) - - NEEDED_DEFINES lists all the defines that HAVE to be set in - /include/wx/setup.h to compile correctly. - - SRC_DIR lists all directories that are needed to - compile. (i.e: lists all the directories, - where there are source-files.) But it is - also needed to clean an object and for - machines, for which make does not support - VPATH - -currently there are the following compiling rules provided: -object files are created for the following file extensions: -.c .cc .cpp - -Please have a closer look at the Makefiles in this distribution. - -* Platforms configure is working with ---------------------------------------- - -Please report build succes on any machine. Especially non- -Linux operating systems (which I don't have). - -Original author of the autoconf system for wxxt-1.66 and for this INSTALL -file: - - Martin Sperl sperl@dsn.ast.univie.ac.at - -Ported to wxGTK 0.1: - - Wolfram Gloger wmglo@dent.med.uni-muenchen.de - -Thanks alot to both of them. +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. + +---------------------- In the hope that it will be useful, - Robert Roebling roebling@sun2.ruf.uni-freiburg.de - - + Robert Roebling +