X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/e3a43801df2f05c057892481df9d3cfe30fd8800..cc24bf919256e8e1d317dbb8e67df6d007d641ea:/docs/x11/install.txt diff --git a/docs/x11/install.txt b/docs/x11/install.txt new file mode 100644 index 0000000000..d9d78aabe3 --- /dev/null +++ b/docs/x11/install.txt @@ -0,0 +1,525 @@ +wxWidgets for X11 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 wxWidgets you are + using (including the beta) and what compiler on what system. One + example: wxX11 2.8.0, gcc 2.95.4, Redhat 6.2 + +First steps +----------- + +- Download wxX11-x.y.z.tgz, where x.y.z is the version number. + Download documentation in a preferred format, such as + wxWidgets-HTML.zip or wxWidgets-PDF.zip. + +- 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 + libXpm 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 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 wxWidgets on Linux for the first time and don't like to read +install instructions just do (in the base dir): + +> ./configure --with-x11 +> 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 expert case +----------------- + +If you want to do some more serious cross-platform programming with wxWidgets, +such as for GTK and X11, 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_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 X11 and a debug version of the GTK +source) you'd do this: + +md buildx11 +cd buildx11 +../configure --with-x11 +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.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. + +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 X, WHAT DISTRIBUTION +YOU USE AND WHAT ERROR WAS REPORTED. I know this has no effect, but I tried... + +* GUI libraries +--------------- + +wxWidgets/X11 requires the X11 library to be installed on your system. + +* Additional libraries +---------------------- + +wxWidgets/X11 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 wxX11 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), +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-x11" +and make and possibly make install as described above. + +To verify X11 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 wxX11 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 wxX11 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. + +You have to add --with-x11 on platforms, where X11 is +not the default (on Linux, configure will default to GTK). + + --with-x11 Use X11. + +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_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 wxX11 +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. Not yet. } + + --without-expat Disable XML classes based on Expat parser. + + --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. + +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. ~/wxX11 +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 + +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 wxX11, + especially if installing from zips (which don't preserve file + permissions). Make this script executable with the command + chmod a+x makewxx11. + + -------:x-----Cut here-----:x----- + # makewxx11 + # Sets permissions (in case we extracted wxX11 from zip files) + # and makes wxX11. + # 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-x11 --with-shared --with-debug_flag --with-debug_info --enable-debug --without-threads --without-sockets --without-odbc + make + -------:x-----Cut here-----:x----- + + This script will build wxX11 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. + +- 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. + +Other Notes +----------- + +- 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 makewxx11 + script). + +Bug reports +----------- + +Please send bug reports with a description of your environment, +compiler and the error message(s) to the wxwin-developers mailing list at: + + wx-dev@lists.wxwindows.org + +