X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/397f14ce524d02bef903c3f186f1554e630467c2..44c5573d2e1f1239b7215551c8861f26fe666f2c:/docs/latex/book/chap_install.tex diff --git a/docs/latex/book/chap_install.tex b/docs/latex/book/chap_install.tex index dd73adc788..4c1a0071e6 100644 --- a/docs/latex/book/chap_install.tex +++ b/docs/latex/book/chap_install.tex @@ -3,5 +3,465 @@ \setheader{{\it CHAPTER \thechapter: INSTALLING wxWINDOWS}}{}{}{}{}{{\it CHAPTER \thechapter: INSTALLING wxWINDOWS}}% \setfooter{\thepage}{}{}{}{}{\thepage}% -Installing wxWindows (and what tools to use). +CONTENTS: Installing wxWindows (and what tools to use). + +Installing wxWindows isn't too hard. Each platform has a different method, so we'll look +at each major platform in turn. + +\section{Unix: GTK+ and Motif}\label{installunix} + +\subsection{The simplest case} + +If you are compile wxWindows on Linux for the first time and don't like to read +install instructions, just do this in the base directory: + +\begin{verbatim} + ./configure --with-gtk + make + su + make install + ldconfig + exit +\end{verbatim} + +This is using the GTK+ port. If using the Motif port, type --with-motif instead of --with-gtk. + +Afterwards you can continue with: + +\begin{verbatim} + make + su + make install + ldconfig + exit +\end{verbatim} + +If you want to remove wxWindows on Unix you can do this: + +\begin{verbatim} + su + make uninstall + ldconfig + exit +\end{verbatim} + +\subsection{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 a local version of the library for that purpose. +For building three versions (one for GTK+, one for Motif and a debug GTK+ version) you'd do this: + +\begin{verbatim} + 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 .. +\end{verbatim} + +\subsection{The simplest errors} + +\begin{itemize}\itemsep=0pt +\item 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). Also, look for the PATH variable and check +if it includes the path to the correct gtk-config! The check your LDPATH if it +points to the correct library. There is no way to compile wxGTK if configure +doesn't pass this test as all this test does is compile and link a GTK program. +\item 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. +\item 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. +\end{itemize} + +\subsection{The simplest program} + +Now create your super-application myfoo.app and compile anywhere with: + +\begin{verbatim} + g++ myfoo.cpp `wx-config --libs --cxxflags` -o myfoo +\end{verbatim} + +\wxheading{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, visit Robert Roebling's homepage at + +\begin{verbatim} + http://wesley.informatik.uni-freiburg.de/~wxxt +\end{verbatim} + +for the latest information. If you still don't have any success, please send a bug +report to one of the mailing lists. + +\wxheading{Libraries needed} + +wxWindows/GTK requires the GTK+ library to be installed on your system. It has to +be a stable version, preferably version 1.2.3. + +You can get the newest version of the GTK+ from the GTK homepage at: + +\begin{verbatim} + http://www.gtk.org +\end{verbatim} + +wxWindows/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, these Linux distributions have correct glibc 2 support: + +\begin{itemize}\itemsep=0pt +\item RedHat 5.1 +\item Debian 2.0 and 3.0 +\item Stampede +\item DLD 6.0 +\item SuSE 6.0 +\end{itemize} + +You can disable thread support by running + +\begin{verbatim} +./configure --disable-threads +make +su +make install +ldconfig +exit +\end{verbatim} + +\subsection{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. + +You'll need OS/2 Warp (4.00FP#6), X-Free86/2 (3.3.3 or newer), +GTK+ (1.2.5 or newer), emx (0.9d fix 1), flex (2.5.4), yacc (1.8), +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: + +\begin{verbatim} + SET CXXFLAGS=-Zmtd -D__ST_MT_ERRNO__ + SET CFLAGS=-Zmtd -D__ST_MT_ERRNO__ + SET OSTYPE=OS2X + SET COMSPEC=sh + \end{verbatim} + +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 + +\begin{verbatim} + configure --with-gtk +\end{verbatim} + +as described above. + +If you have pthreads library installed, but have a gtk version +which does not yet support threading, you need to explicitly +disable threading by using the option --disable-threads. + +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. + +\subsection{Building wxGTK 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: + +\begin{verbatim} + CFLAGS="-mips3 -n32" + CXXFLAGS="-mips3 -n32" +\end{verbatim} + +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 64-bit 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. + +\subsection{Create your configuration} + +Usage: + +\begin{verbatim} + ./configure options +\end{verbatim} + +If you want to use system's C and C++ compiler, +set environment variables CC and CCC as + +\begin{verbatim} + setenv CC cc + setenv CCC CC + ./configure options +\end{verbatim} + +to see all the options please use: + +\begin{verbatim} + ./configure --help +\end{verbatim} + +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 (and sometimes make) will complain if the system variable OSTYPE has +not been defined. + +\subsubsection{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. + +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: + +\begin{verbatim} + --without-gtk Don't use the GIMP ToolKit (GTK) + + --with-motif Use either Motif or Lesstif + Configure will look for both. +\end{verbatim} + +The following options handle the kind of library you want to build. + +\begin{verbatim} + --disable-threads Compile without thread support. + + --disable-shared Do not create shared libraries. + + --enable-static Create static 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 + and 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. +\end{verbatim} + +\subsubsection{Feature Options} + +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 + +\begin{verbatim} + --with-odbc Enables ODBC code. This is disabled + by default because iODBC is under the + L-GPL license. + + --without-libpng Disables PNG image format code. + + --without-libjpeg Disables JPEG image format code. + + --without-libtiff Disables TIFF image format code. + + --disable-pnm Disables PNM image format code. + + --disable-gif Disables GIF image format code. + + --disable-pcx Disables PCX image format code. + + --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. +\end{verbatim} + +Apart from disabling certain features you can very often "strip" +the program of its debugging information resulting in a significant +reduction in size. + +\subsubsection{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: + +\begin{verbatim} + make +\end{verbatim} + +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 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 + +\begin{verbatim} + make install +\end{verbatim} + +You can remove any traces of wxWindows by typing + +\begin{verbatim} + make uninstall +\end{verbatim} + +If you want to save disk space by removing unnecessary +object-files: + +\begin{verbatim} + make clean +\end{verbatim} + +in the various directories will do the work for you. + +\subsubsection{Creating a new Project} + +1\ket The first way uses the installed libraries and header files +automatically using wx-config + +\begin{verbatim} +g++ myfoo.cpp `wx-config --cxxflags --libs` -o myfoo +\end{verbatim} + +Using this way, a make file for the minimal sample would look +like this + +\begin{verbatim} +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 +\end{verbatim} + +This is certain to become the standard way unless we decide +to stick to tmake. + +2\ket 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. + +\section{Windows}\label{installwindows} + + +\section{Mac}\label{installmac} + +We don't have information about Mac installation at this time.