1 The FOX GUI Library Installation 2 ================================ 3 4 5 6Systems Which are Supported or Known to work: 7============================================= 8 9 o Linux (gcc, INTEL C++), x86, IA64 (Itanium), x86-64 (Opteron). 10 o Windows XP, 2K, NT, Windows 9x, (VC++, Cygwin, MinGW, 11 Borland C++, Digital Mars C++, OpenWatcom C++, ... ) 12 o Digital Unix/COMPAQ Tru64 OSF1 3.2, 4.0x, 5.0x (gcc and DEC cxx). 13 o SGI IRIX 5.3, 6.1, 6.2, 6.4, 6.5 (gcc and MIPS Pro C++) 14 o SUN Solaris, SunOS (gcc, SUN WorkShop Compiler, SUN Forte C++) 15 o HP-UX PA-RISC 9.x, 10.x and B.11.00, (gcc and aCC). 16 o HP-UX B.11.22 Intel Itanium (IA64) using aCC. 17 o AIX 4.2, 4.3 18 o FreeBSD 19 o Sequent DYNIX/ptx 4.4.7 20 o IBM VisualAge C++ 3.5 (Windows) 21 o Apple MAC OS-X. You will need an X-Server, either Apple's or XFree. 22 23 24 25Building Documentation. 26======================= 27 28You will need the "doxygen" documentation extraction tool. You can get it 29from: 30 31 http://www.stack.nl/~dimitri/doxygen/index.html 32 33Many current linux distributions already include this tool as an optional 34package. 35 36To generate documentation, unpack the FOX tarball and go to directory "doc." 37Then issue the command: 38 39 make docs 40 41If doxygen is installed properly, it will churn for a while and then generate 42hyperlinked documentation from the header files' document comments. You will 43find this reference documentation in the "doc/ref" directory. 44 45 46 47 48For most UNIX systems. 49====================== 50 51For most unix systems you can configure simply as: 52 53 54 ./configure 55 56 57You can disable OpenGL support by configuring as: 58 59 60 ./configure --with-opengl=no 61 62 63After configure runs its course, simply type ``make'' to build the library, 64and ``make install'' to install it. 65 66FOX should compile on most UNIX platforms; we have tested the following: 67SGI, IBM, HP, SUN, DEC, LINUX, all with gcc; however, FOX uses a fairly 68conservative subset of C++, and should be no problem to port to other, more 69primitive, C++ compilers. 70 71On some machines, the X11 header files are still K&R C, instead of ANSI-C. 72You might try define add "-fpermissive" to the CXXFLAGS environment variable 73prior to running configure (this is the flag for GCC; other compilers may 74have similar option for old K&R C). 75 76When programming against FOX, you should only have to include "fx.h", and 77for 3D programs, "fx3d.h". To use keyboard symbols, include "fxkeys.h" also. 78Specifically, to remain portable application programs should NOT include any X 79window header files. 80 81You may of course need other system headers ("stdio.h", "gl.h", etc). 82 83 84 85Enabling XFT Support. 86===================== 87 88On Linux systems, you can turn on XFT anti-aliased font support. 89 90 91 ./configure --with-xft=yes 92 93 94For portability reasons, the default of this settings is off. 95 96 97 98XCursor Support. 99================ 100 101FOX supports Xcursor support where available. This is normally turned on, 102allowing full alpha-blended cursor support. However, you can disable if 103desired: 104 105 106 ./configure --with-xcursor=no 107 108This will cause to revert to vanilla black/white cursor support only; note 109that your color cursors will still work: they will be thresholded to black 110and white depending on brightness. 111 112 113 114Building for Debug or Release. 115============================== 116 117Normal builds [w/o any special arguments to configure] will include assert and 118trace statements into the library, but no debug symbols. This mode compiles 119the fastest and allows for tracing of the FOX library. This mode is the 120recommended way to develop FOX applications, as it allows for resource tracing 121and internal consistency checks. 122 123Building for debug will add debug symbols as needed by your debugger. It also 124includes assert and tracing into the library. This setting is recommended if 125you need to debug the FOX library itself. Full debug executables are build by 126configuring with: 127 128 129 ./configure --enable-debug 130 131 132 133Release builds strip all debug information, asserts, and tracing, and generates 134optimized code. The resulting library is the smallest/fastest, and this is the 135recommended setting for production code. To build for release, use: 136 137 138 ./configure --enable-release 139 140 141 142 143Building Shared or Non-Shared Libraries. 144======================================== 145 146You can build FOX either as shared library, static library, or both. The 147default is both. To build static library only [this may be necessary on 148certain systems where shared library support is lacking]: 149 150 ./configure --disable-shared 151 152to build shared library only: 153 154 ./configure --disable-static 155 156 157 158Thread-safe support. 159==================== 160 161It is highly recommended to build FOX with thread-safe API's wherever 162possible; this is accomplished using: 163 164 165 ./configure --enable-threadsafe 166 167Enabling thread-safe will cause FOX to use the thread-safe equivalent 168API's for some common C library functions like getpwuid(), readdir() 169and so on. 170 171 172 173 174Image File Format Support. 175========================== 176 177FOX needs external libraries for JPEG, TIFF, and PNG image format. On 178some systems, such as Linux, *BSD, these are likely already installed 179on your system. On Windows or older UNIX systems, they need to be 180compiled and installed first. See below on how to override default 181locations on UNIX systems. 182 183The JPEG support is provided by jpegsrc.v6b.tar.gz, the PNG support 184by libpng-1.2.5.tar.gz (or a newer version). The TIFF support is 185in tiff-v3.5.7.tar.gz (or later). All these files are available on 186ftp.fox-toolkit.org. 187 188After these libraries have been compiled and installed, compile FOX 189with HAVE_TIFF_H=1, HAVE_PNG_H=1, HAVE_JPEG_H=1. 190 191The TIFF library may also need the JPEG library (JPEG is one of the 192tags supported in the TIFF format), so compile the JPEG library first. 193TIFF also needs the GNU compression library zlib (available as 194zlib-1.1.4.tar.gz (or later) on ftp.fox-toolkit.org). 195 196 197Compression Library Support. 198============================ 199 200Compressed FXStream support is enabled by installing zlib-1.1.4.tar.gz 201and bzip2-1.0.2.tar.gz (or later), then compiling FOX with HAVE_ZLIB_H=1 202and HAVE_BZ2LIB_H=1, respectively. You do not need to install them on 203Linux, *BSD, but you probably do on Windows and older UNIX systems. 204 205 206 207 208Overriding Libraries. 209===================== 210 211The default libraries determined by configurations are not always the ones you 212want to use; therefore, there is a mechanism to override the default choices 213of the configuration system. 214 215The override is done simply by setting environment variables prior to running 216configure; make sure config.cache is removed if you've ran configure before. 217 218Configure allows for the following overrides: 219 220 221 Environment Variable Default value if not set 222 ==================== ======================== 223 224 LIBJPEG -ljpeg 225 LIBPNG -lpng 226 LIBTIFF -ltiff 227 LIBZ -lz 228 LIBBZ2 -lbz2 229 LIBGL -lopengl32 (win32) 230 LIBGLU -lglu32 (win32) 231 LIBGL -lGL (unix) 232 LIBGLU -lGLU (unix) 233 234 235 236On SGI IRIX 6.x 237=============== 238 239 240On SGI Systems where MIPS Pro C++ compiler is used instead of GCC, you will 241need to set the environment variable CXX to: 242 243 CC -n32 244 245and then run: 246 247 ./configure --x-libraries=/usr/lib32 248 249 250or, you can also build FOX for the 64 bit model, and set CXX to: 251 252 253 CC -64 254 255 256and run configure with: 257 258 ./configure --x-libraries=/usr/lib64 259 260 261The first argument is only needed if you also have MESA on your system. 262FOX searches for the png library [for Portable Network Graphics, the successor 263of GIF], but the library it finds, even though it has the same name, is not 264the right one. You will need to disable this feature, or download the PNG 265library from http://www.graphicswiz.com/png/ and compile it, and pass the 266appropriate flags for your compiler to find the new version. 267If compiling without PNG, pass the flag: --disable-png; likewise, you 268can disable JPEG with the flag: --disable-jpeg. 269 270 271SGI Altix 272========= 273 274Using Intel C++ compiler on IA64-based Altix system, drop optimization level 275to -O1: 276 277 setenv CXX "icpc -O1" 278 setenv CC "icc -O1" 279 280 281Full optimization with icc compiler appears to generate incorrect code. 282 283 284Using gcc 2.95.2 on IRIX 6.x (Thanks to Theo Venker) 285==================================================== 286 287You won`t believe the solution: rename FXApp.cpp to FXApp.C and everything 288is fine. The manual page of g++ says that it accepts C++ suffixes .C, .cc, 289.cxx, .cpp, and .c++, and it does, but for .cpp and .c++ it compiles with 290-D__LANGUAGE_C -D_LANGUAGE_C -DLANGUAGE_C whereas the others suffixes 291use -D__LANGUAGE_C_PLUS_PLUS -D_LANGUAGE_C_PLUS_PLUS. This is clearly a 292bug in g++. I decided to wait for the next g++ release, so I didn`t 293report this to the g++ maintainers. May be you will. 294 295The work-arround is: 296 297 export CC="g++ -D__LANGUAGE_C_PLUS_PLUS -D_LANGUAGE_C_PLUS_PLUS" 298 299and then run configure. 300 301 302 303 304Building 64-bit code on Linux for x86-64 (AMD Opteron, Athlon64) 305================================================================ 306 307Linux for AMD Opteron supports execution of both 32 and 64 bit code 308on the same system; consequenly, two sets of libraries are installed. 309To configure properly, you will need to let ld search the right set 310of directories. Here's how: 311 312 313 export LDFLAGS="-L/usr/lib64 -L/usr/X11R6/lib64 -L/lib64" 314 ./configure <other options> 315 316 317No other issues are known at this time. 318 319 320 321 322On Alpha Processor based Workstations (COMPAQ/DEC OSF1) 323======================================================= 324 325 326If you use DEC's "cxx" instead of GNU gcc, you will need to make sure the 327you add the flag option -D_XOPEN_SOURCE_EXTENDED to the compiler; this 328will allow usage of a wider set of POSIX functions; GCC seems to have 329this flag on by default, but the standard C++ compiler on OSF1 does not; 330thanks to thomas.goessler@avl.com for pointing this out. 331 332When compiling with gcc on Digital Unix, you may want to enable gradual 333underflow support for IEEE754 conformant floating point operations: 334 335 336 export CXX="gcc -mieee" 337 ./configure .... 338 339 340If this flag is NOT set, floating point operations which yield underflows 341will cause a floating point exception (SIGFPE). 342 343Many perfectly correct programs may generate underflows when working 344with small numbers (~1e-38 single precision, ~1e-308 double precision); 345working with these numbers may involve so-called denormalized floating 346point numbers, i.e. numbers where the mantissa can no longer be shifted 347to be within [0.5,1.0> range due to the exponent becoming 0. 348 349The ALPHA CPU does not include hardware do manipulate these numbers and 350will generate a trap when trying to manipulate these numbers; passing 351the "-mieee" flag will incorporate a software handler to ensure IEEE754 352conformant floating arithmetic. 353 354 355 356 357Compiling FOX on the SUN 358============================================ 359 360To use the SUN WorkShop Compiler compilers, simply configure 361FOX as follows: 362 363 > cd fox 364 > env CC=cc CXX=CC LD=CC ./configure 365 366 367 368Explanation: 369 370The SUN compilers require 'CC' to be used instead of 'ld' for creating the 371shared object library. This is to ensure that template instances will be 372included in the library. To build a static library 'CC -xar' should be 373used instead of 'ar' but there is no simple way to do this, due to 374limitations in 'libtool'. 375 376To get around this problem, the configure script invokes 'CC' with the 377argument '-instances=global', thus including template instances in the 378object file instead of using a template repository. This works fine and 379'ar' can be used to build a static object library. 380Thanks to: Daniel Gehriger <gehriger@epfl.ch> 381 382 383 384Compiling FOX using the HP/UX C++ Compiler 385========================================== 386 387You may want to use GNU make instead of HP's make (/usr/bin/make). The default 388version of make doesn't seem to process the dependencies for PathFinder 389correctly and thus doesn't generate the reswrapped icon header files. Since 390PathFinder is built after the library and all the test programs, this isn't 391a huge problem -- it just means that the build will stop at that point with 392an error message. 393 394Configure the build by typing: 395 396 env CC="cc +DA2.0W" CXX="aCC +DA2.0W +W740,749,863" ./configure 397 398The "+DA2.0W" flag tells it to compile as 64 bit. The "+W740,749,863" option 399suppresses a few warning messages that we believe are safe to ignore ;) 400 401 402 403Compiling FOX using the HP/UX Itanium^2 aCC C++ Compiler 404======================================================== 405 406Assuming the aCC is installed in the recommended place: 407 408 409 export CXX="aCC -fast -mt +DD64 -DHAVE_VSSCANF=1 -DHPOGL_SUPPRESS_FAST_API=1 410 -I/opt/aCC/include -I/opt/graphics/OpenGL/include -L/lib/hpux64 411 -L/usr/lib/hpux64 -L/opt/graphics/OpenGL/lib/hpux64" 412 413 414You may want to build the image support libraries also if you need them. 415 416 417 418Windows 95/98/ME/NT/XP Builds 419============================= 420 421We currently build FOX on a regular basis using Microsoft Visual C++ 6.0. 422There is also support for Mingw32, the latest net release of Cygwin (v1.1) 423and Borland C++. We have heard of mixed success with building under Symantec's 424C++ 7.5 compiler. 425 426A few things to keep in mind: 427 428 1. If you want to include OpenGL support be sure to define the HAVE_OPENGL 429 symbol on the compiler's command line, and to link your executables to 430 the opengl32.lib and glu32.lib libraries. 431 432 2. The native Windows version of FOX relies on an undocumented API called 433 _TrackMouseEvent() which is found in comctl32.dll. You should be sure 434 to link your FOX applications with the comctl32.lib import library. 435 Note that for this function is only available for comctl32.dll 436 versions 4.70 or later; the latest version of this DLL can be downloaded 437 from Microsoft's web site: 438 439 http://www.microsoft.com/msdownload/ieplatform/ie/comctrlx86.asp 440 441 If you are running Windows 98, Windows NT 4.0 SP3, or have installed 442 Internet Explorer 4.0 or later, you *probably* already have the latest 443 version of this DLL already. 444 445 3. The FOX registry mechanism uses the regular Windows registry under the 446 hood; those functions are found in advapi32.lib which is not always a 447 standard library. If you get some unresolved symbols at link time (esp. 448 with names beginning with "Reg") try adding advapi32.lib to the list 449 of libraries. 450 451 4. To build or use FOX as a DLL, the symbol FOXDLL must be defined; for 452 building the core FOX library, FOXDLL_EXPORTS must also be defined. 453 If FOXDLL_EXPORTS must NOT be not defined when you are just using FOX 454 as a DLL. 455 456 5. It is recommended that extension DLL's are compiled with FOXDLL but 457 that you define your own symbol to signify export; for example, the 458 CHART library is build with CHARTDLL_EXPORTS; since the CHART library 459 USES FOX, it must import the core FOX library, yet export its own 460 functions. 461 462 463 464Building with Microsoft Visual C++ 465================================== 466 467We now have a project workspace and project files set up for Win32 builds 468under Visual C++ 6.0. To use these, perform the following steps: 469 470 1. Download the latest fox.tar.gz from the web site; 471 472 2. Unzip & untar in your favorite place; 473 474 3. Start Visual C++ and open the fox/windows/vcpp/win32.dsw workspace; 475 476 4. Choose a project and build it. The project corresponding to the library 477 itself is named "fox", and all of the other projects list it as a 478 dependency. So if you choose, say, "glviewer" to build, it should first 479 build the library and then build the glviewer test program. 480 481 482Building with Borland C++ Compilers 483=================================== 484 485The Borland makefiles are now tested semi-regularly against the free 486command-line compiler tools (compiler version 5.5) distributed by 487Borland/Inprise. We believe that they should also be usable for any recent 488Borland C++ compilers (e.g. Borland C++ Builder 3 or later). 489 490To build the FOX library, utility programs and example programs, change to the 491fox-0.99.xxx\windows\borland subdirectory and type "make". It should compile 492without a hitch, with the possible exception of building the OpenGL test 493programs in the "tests" subdirectory: 494 495 + If you're using the free command-line compiler tools, you want to be sure 496 that the %BCCDIR%\Lib\PSDK directory appears in the linker configuration 497 file (%BCCDIR%\Bin\ilink32.cfg). If it isn't there, the linker won't know 498 where to find the opengl32.lib and glu32.lib import libraries. 499 500 + If you're using an older Borland compiler, you similarly want to be sure 501 to have the updated OpenGL SDK for Win32 (including the OpenGL 1.2 header 502 files and import libraries). 503 504If for some reason you don't have the correct header files and import libraries 505for OpenGL, and if OpenGL support isn't important for your project anyways, 506just modify the "Makefile.bc" in the fox-0.99.xxx\tests subdirectory so that 507it doesn't try to build the "glviewer.exe" or "gltest.exe" examples. 508 509 510Building FOX as a DLL 511===================== 512 513The FOX library can also be built as a DLL for Windows; this is done by 514selecting the "foxdll" project and building it. Building this project 515causes the import libraries and DLLs to be placed in fox/lib. 516The filenames are foxdll.lib and foxdll.dll for the Release build, or 517foxdlld.lib and foxdlld.dll for the Debug build. 518 519To compile your own FOX applications so that they use the FOX DLL instead of 520the static FOX library, be sure to define the FOXDLL symbol in your compiler 521flags. Also note that the DLL must be in your search path for the program to 522run! 523 524 525Building FOX using OpenWatcom C++ 526================================= 527 528The OpenWatcom C++ compiler can be downloaded free of charge from: 529 530 531 http://www.openwatcom.org. 532 533 534To use the OpenWatcom "patch" with a fresh copy of FOX vx.y.zz, please make 535sure you've installed OpenWatcom C++ v1.0 and executed the SETVARS.BAT file 536found in the OpenWatcom installation directory. 537The Makefile.wc files rely on a Watcom environment variable, %WATCOM%, to 538determine the location of the COMCTL32.LIB file. Use the Makefile provided 539in windows/watcom/Makefile. 540Thanks to mikael@lyngvig.org for this port. 541 542 543 544Building FOX using MinGW 545======================== 546 547Please see the standard FOX documentation file, "Developing Win32 GUI 548Applications Using FOX", available in this distribution as the file 549"doc/win32.html". 550 551 552 553Building FOX using Cygwin 1.1 554============================= 555 556FOX can also be built against the latest net release of Cygwin, available 557for download from here: 558 559 http://sourceware.cygnus.com/cygwin/mirrors 560 561It absolutely will not compile with previous releases of Cygwin (i.e. 562Cygwin B20.1 or earlier), at least not without a lot of headaches. The 563win32api header files distributed with earlier versions of Cygwin were not 564up-to-date enough for FOX. 565 566It should compile out-of-the-box by typing: 567 568 ./configure --disable-shared 569 make 570 571 572 573Building FOX on QNX 574=================== 575 576 577For those interested in using FOX with QNX, before running configure for 578FOX on QNX it might be a good idea to run: 579 580 automake --add-missing 581 libtoolize -f 582 583Doing so will ensure that the configuration files needed to detect QNX 584are present. � 585 586Also, for now it is probably best to disable shared libraries when 587building FOX on QNX. �Programs linked with the FOX shared library will 588not run, but instead will segfault. �I plan on looking into a fix for 589this eventually. � 590 591Dustin Graves <dgraves@computer.org> 592 593 594 595Building on MAC OS-X 596==================== 597 598 599When building on Mac OS-X, the following might help: 600 601 602 CXX="c++ -I/sw/include -L/sw/lib 603 ./configure <otheroptions> 604 605 606This might help; no guarantees, I can not test this myself.... 607For more information, see: 608 609 http://freeride.rubyforge.org/wiki/wiki.pl?MacOSXInstall 610 611 612 613 614Image Formats in File Browser 615============================= 616 617By default, all available image formats are supported in the File and 618Directory Browsers. Some of these image formats require external 619library support and consequently the size of your application executables 620may be reduced by limiting the supported formats to those supported in 621the core library; the image formats supported in the core library do 622not require external libraries and therefore supporting them does not 623incur any additional "code bloat". 624 625To support only the core image formats, pass the compiler flag: 626 627 628 -DCORE_IMAGE_FORMATS=1 629 630 631Another flag is the default icon search path, i.e. where the file browser will 632normally look to find and load icons bound to file extensions. 633The path below will cause the system to look in three different directories: 634 635 636 -DDEFAULICONPATH="~/.foxicons:/usr/local/share/icons:/usr/share/icons" 637 638 639This would be a common setting for LINUX. Note that this is only the default; 640the actual search path can by set at any time by means of the FOX registry setting: 641 642 643 [SETTINGS] 644 iconpath="/home/extraicondir:/usr/share/icons" 645 646