From: Arjen M. <arj...@us...> - 2007-01-16 20:24:11
|
Update of /cvsroot/plplot/plplot In directory sc8-pr-cvs1.sourceforge.net:/tmp/cvs-serv21048 Modified Files: README INSTALL Log Message: Edited the README and INSTALL files - notably moved the info on CBS to the front Index: README =================================================================== RCS file: /cvsroot/plplot/plplot/README,v retrieving revision 1.29 retrieving revision 1.30 diff -u -d -r1.29 -r1.30 --- README 19 Nov 2006 18:52:07 -0000 1.29 +++ README 16 Jan 2007 20:24:03 -0000 1.30 @@ -53,10 +53,10 @@ SunOS (Sun) MS-DOS (DJGPP) - Windows (95?, 98, NT, 2000) + Windows (95?, 98, NT, 2000, XP) Many different output device drivers are available, including postscript, -tektronix, HP laserjet, HP pen plotters, XFig, xterm, X-windows, and a +PDF, tektronix, HP laserjet, HP pen plotters, XFig, xterm, X-windows, and a portable metafile format, among others. The Tk driver under Unix/X provides a full user interface based on the plframe plotting widget (see below). The metafile renderer (plrender) supports all of the standard operations as well Index: INSTALL =================================================================== RCS file: /cvsroot/plplot/plplot/INSTALL,v retrieving revision 1.42 retrieving revision 1.43 diff -u -d -r1.42 -r1.43 --- INSTALL 4 Dec 2006 21:18:44 -0000 1.42 +++ INSTALL 16 Jan 2007 20:24:03 -0000 1.43 @@ -3,6 +3,9 @@ PLplot can be built and installed using one of several methods: +- (For UNIX, Linux, MacOS X, Cygwin, MinGW, MinGW/MSYS, and bare windows, +i.e., all systems other than DJGPP.) Use our new CMake build system (CBS). + - (Deprecated.) On UNIX-like systems (UNIX, Linux, MacOS X, and Cygwin and MinGW/MSYS on Windows) via the automake buid system (ABS) @@ -11,11 +14,290 @@ - DJGPP on (Free)DOS. Follow the directions at sys/dos/djgpp/readme -- (For UNIX, Linux, MacOS X, Cygwin, MinGW, MinGW/MSYS, and bare windows, -i.e., all systems other that DJGPP.) Use our new CMake build system (CBS). +PLplot installation notes for our new CBS (CMake build system). +========================================================================= -(Deprecated.) PLplot installation notes for our traditional ABS +The definitive set of instructions is given at +http://www.miscdebris.net/plplot_wiki/. The material below is cut and pasted +from there as of 2006-12-02. + +Our CMake Build System (CBS) has been made available as part of our +development releases of PLplot starting with version 5.7.0 and is a +build-system paradigm shift compared to our traditional Autotools Build +System (ABS). Thus, it is important to consult the CMake documentation to +get the most out of our CBS. That documentation is quite thorough but tends +to be a bit scattered so we have collected what we think are the best +general CMake documentation links +(http://www.miscdebris.net/plplot_wiki/index.php?title=General_CMake_documentation_links) +for your convenience. + +After consulting that documentation, install +(http://cmake.org/HTML/Install.html) the appropriate package of +CMake for your system platform. Note, you must use at least version 2.4.5 of +CMake for your PLplot configuration. + + +------------------------------------------------------------------------------ +Some general remarks on CMake +------------------------------------------------------------------------------ + +The CMake build system (from http://www.cmake.org) is a portable system +to prepare makefiles and project files for software like PLplot that +needs to be built on many different platforms (hardware, operating +system, compilers). + +The approach we have found most useful in using CMake to build PLplot is +this: + +* Copy the sources in one directory +* Create a separate directory to build and install the software itself + (libraries and the executables for the examples) + +This way, you can simply remove all files in the build/install directory +and start all over, if you want to change a build option. Or build +PLplot in a third directory with the new build options. + +CMake has two interfaces: + +* The command-line interface "cmake" + +* The graphical user-interface ccmake (or CmakeSetup under Windows) + +The advantage of the command-line interface is that you can set the +various options (and environment variables) in a shell script or batch +file so that you can not forget to set them. + +The advantage of the GUI is of course that you have an overview of all +possible options. But you will need to be careful to set all +environment variables _before_ running CMake. + +Whichever of two you take, the steps are: + +* Set up the environment (if this is needed, for instance to find the + compilers and extra libraries) + +* Run CMake with the right options to create makefiles or project files + +* Run the native build system (nmake or the proper IDE) to actually + build the library. + +------------------------------------------------------------------------------ +Generic Unix instructions for our CBS +------------------------------------------------------------------------------ + + + (Optional) set environment variables to help cmake find system components + that are installed in non-standard locations. + + Here is one particular example (which must be executed before the cmake + invocation discussed below). + + export CMAKE_INCLUDE_PATH=/home/software/autotools/install/include:/home/software/cgmlib/cd1.3 + export CMAKE_LIBRARY_PATH=/home/software/autotools/install/lib:/home/software/cgmlib/cd1.3 + export PKG_CONFIG_PATH=/home/software/libLASi/install/lib/pkgconfig + + For this particular example, CMAKE_INCLUDE_PATH helps cmake to find the + headers for libltdl and libcd in non-standard install locations; + CMAKE_LIBRARY_PATH helps cmake to find the libltdl and libcd libraries in + non-standard install locations; and PKG_CONFIG_PATH helps cmake to use + the pkg-config command internally to find a libLASi pkg-config module + file that is installed in a non-standard location. + + In general, CMAKE_INCLUDE_PATH helps cmake find headers and other files + that are installed in non-standard locations; CMAKE_LIBRARY_PATH helps + cmake find libraries that are installed in non-standard locations; and + PKG_CONFIG_PATH helps pkg-config (either externally or internally from + cmake) find pkg-config modules installed in non-standard locations. + Finally, although not used in the specific example above, the + colon-separated environment variable PATH helps cmake find executables + that are installed in non-standard locations. + + + (Optional) set environment variables to specify the compilers and compiler + flags. + + Here is one particular example (which must be executed before the cmake + invocation discussed below). + + export CC="gcc -O2" + export CXX="g++ -O2" + export FC="g77 -O2" + + Note a better option is to set CMAKE_BUILD_TYPE to one of Debug, Release, + RelWithDebInfo, or MinSizeRel. If you don't set this variable and don't + set the environment variables above, then by default no compiler options + (i.e., no optimization and no debugging symbols) are used for gcc-related + compilers for our CBS which makes for fast builds, but slow execution. + + + cmake invocation. + + Here is one typical example. + + mkdir build_dir + cd build_dir + cmake -DCMAKE_INSTALL_PREFIX=/my/prefix \ + -DCMAKE_VERBOSE_MAKEFILE=ON ../plplot_cmake >& cmake.out + + Check the cmake.out file for any configuration issues, especially WARNING + messages which signal that a component of PLplot has been removed because + required system components for that component have not been found. + + Everything can be controlled with -D options to the cmake command. There + are a large number of CMake options for PLplot + (http://www.miscdebris.net/plplot_wiki/index.php?title=CMake_options_for_PLplot) + which can be set for cmake to personalize your build. Use the ccmake + front end to cmake to obtain documentation of all these options. In the + above case we have specified a particular install prefix "/my/prefix" and + verbose make results (essential if you want to see the exact commands + used for the build). + + Note in the above example an empty build directory called build_dir is + used to insure a clean start, and ../plplot_cmake is a freshly checked + out source tree (which remains clean because you never actually create + any files in that directory tree). To start fresh, simply execute "cd + build_dir; rm -rf *". Of course, this is an extremely dangerous command + (since it removes everything in the current directory and all + subdirectories), but you should be okay so long as you cd to the correct + directory before executing the "rm" command. + + + Post-cmake build, install, and build-tree and install-tree tests + + make >& make.out + make install >& make_install.out + + ctest + + cp -a /my/prefix/share/plplot5.6.1/examples /tmp + cd /tmp/examples + make >& make_examples.out + ./plplot-test.sh >& plplot_test.out + + Note, the build-tree tests done with ctest are limited to just the psc + (colour postscript) device and can only be performed if cmake is invoked + with the -DBUILD_TEST=ON option (which roughly doubles the build time + because all the examples must be built). + + Check all the *.out files for any errors. Check that the large number of + postscript files generated by plplot-test.sh look good with a postscript + viewer. Also, use the --help option to ./plplot-test.sh to see ways you + can test your PLplot install for devices other than the default psc + device. + + --------------------------------------------------------------------------- + Linux instructions for our CBS. + --------------------------------------------------------------------------- + + No changes from the generic Unix instructions. + + --------------------------------------------------------------------------- + MacOS X instructions for our CBS. + --------------------------------------------------------------------------- + + Few changes from the generic Unix instructions which need to be updated + from http://www.miscdebris.net/plplot_wiki/. + +------------------------------------------------------------------------------ +Windows instructions for our CBS (needs updating from +http://www.miscdebris.net/plplot_wiki/ +------------------------------------------------------------------------------ + +* Here is a typical way to use cmake on windows systems. +CMake comes with a graphical user-interface that allows you to set the +various build parameters interactively. It will try and find the +available compilers and other language tools that can be used for +PLplot and then generate a set of makefiles or project files depending +on what you chose. + +Alternatively you can use the command-line version. This is particularly +useful if you need to set one or more environment variables - you can +do that in a small batch file and then run CMake several times until +you have fine-tuned the build system. + +Once you have the makefiles or project files, you can use nmake or +Visual Studio to actually build the library and the examples. + +Typically the steps are: + + + Set any environment variables you need to set (if the + right compilers are not already in your path for instance) + - If you set them in a DOS-box, be sure to run CMake in + that same DOS-box! + + + + Run CMakeSetup (the GUI version of CMake) or cmake (the + command-line version) to set the build parameters and + generate the make/project files + + + Run nmake or Visual Studio to build the library and + the examples + +For instance (sources copied in c:\plplot\plplot): + + c:\plplot> mkdir build + c:\plplot> cd build + c:\plplot\build> vcvarss32 + c:\plplot\build> cmake -DBUILD_TEST=ON -G "NMake Makefiles" ..\plplot + c:\plplot\build> nmake + +CMake supports most flavours of Visual Studio project files (ranging +from VS 6.0 to VS.net 2005) and it can create makefiles suitable for +the nmake utility. + +Currently (january 2007) there are the following limitations: + + + Support for additional libraries is limited: + - freetype (antialiasing fonts, smooth text): see notes below + - BGD (output in the form of GIF, JPEG or PNG files): none yet + - Qhull (advanced spatial interpolation): none yet + + + An important issue is that on Windows there is no standard + location to install _libraries_ as opposed to programs. + We are working on that. + +On the other hand: + + + Bindings for C and C++ (MSVC compiler) are no problem + + You can build both static (.lib) and dynamic link libraries (.dll) + +Note on the examples +-------------------- +If you want to run the examples _before_ actually installing PLplot, +then you must copy some files into the directory holding the example +programs: + + + plstnd5.fnt and plxtnd5.fnt in the directory ...\data + +Dealing with freetype on Windows +-------------------------------- +N.B. We need a lot more information here. For now we only have Werner's +instructions for dealing with the freetype library on two different windows +systems. + +MinGW: +* download and unzip freetype 2.2.1 (ft221.zip) +* mingw32-make (compiler is detected) +* mingw32-make (to compile the library) +* copy objs\freetype.a objs\libfreetype.a +* set FREETYPEDIR=C:\DevZone\freetype-2.2.1 +* set PATH=%FREETYPEDIR%\objs;%PATH% +* set CMAKE_INCLUDE_PATH=%FREETYPEDIR%\include +* run cmake with your options + +Visual C++ 2005 +* download and unzip freetype 2.2.1 (ft221.zip) +* change line 69 of freetype-2.2.1\builds\compiler\visualc.mk to + CFLAGS ?= /nologo /c /Ox /W3 /WX /D_CRT_SECURE_NO_DEPRECATE + otherwise it stops the build because of warnings (/WX) since it + doesn't know the /G5 option (this may not be necessary for + Visual C++ 6.0 and/or 2003 +* path_to_gnu_make\mingw32-make setup visualc +* path_to_gnu_make\mingw32-make +* set FREETYPEDIR=C:\DevZone\freetype-2.2.1 +* set PATH=%FREETYPEDIR%\objs;%PATH% +* set CMAKE_INCLUDE_PATH=%FREETYPEDIR%\include +* run cmake with your options + + +(Deprecated.) PLplot installation notes for our traditional ABS (automake build system). ========================================================================= @@ -650,234 +932,3 @@ is not found in xlf. x17f.f uses the random number generator rand for which xlf expects a different number of arguments than g77. ------------------------------------------------------------------------------ - -PLplot installation notes for our new CBS (CMake build system). -========================================================================= - -The definitive set of instructions is given at -http://www.miscdebris.net/plplot_wiki/. The material below is cut and pasted -from there as of 2006-12-02. - -Our CMake Build System (CBS) has been made available as part of our -development releases of PLplot starting with version 5.7.0 and is a -build-system paradigm shift compared to our traditional Autotools Build -System (ABS). Thus, it is important to consult the CMake documentation to -get the most out of our CBS. That documentation is quite thorough but tends -to be a bit scattered so we have collected what we think are the best -general CMake documentation links -(http://www.miscdebris.net/plplot_wiki/index.php?title=General_CMake_documentation_links) -for your convenience. - -After consulting that documentation, install -(http://cmake.org/HTML/Install.html) the appropriate package of -CMake for your system platform. Note, you must use at least version 2.4.5 of -CMake for your PLplot configuration. - ------------------------------------------------------------------------------- -Generic Unix instructions for our CBS ------------------------------------------------------------------------------- - - + (Optional) set environment variables to help cmake find system components - that are installed in non-standard locations. - - Here is one particular example (which must be executed before the cmake - invocation discussed below). - - export CMAKE_INCLUDE_PATH=/home/software/autotools/install/include:/home/software/cgmlib/cd1.3 - export CMAKE_LIBRARY_PATH=/home/software/autotools/install/lib:/home/software/cgmlib/cd1.3 - export PKG_CONFIG_PATH=/home/software/libLASi/install/lib/pkgconfig - - For this particular example, CMAKE_INCLUDE_PATH helps cmake to find the - headers for libltdl and libcd in non-standard install locations; - CMAKE_LIBRARY_PATH helps cmake to find the libltdl and libcd libraries in - non-standard install locations; and PKG_CONFIG_PATH helps cmake to use - the pkg-config command internally to find a libLASi pkg-config module - file that is installed in a non-standard location. - - In general, CMAKE_INCLUDE_PATH helps cmake find headers and other files - that are installed in non-standard locations; CMAKE_LIBRARY_PATH helps - cmake find libraries that are installed in non-standard locations; and - PKG_CONFIG_PATH helps pkg-config (either externally or internally from - cmake) find pkg-config modules installed in non-standard locations. - Finally, although not used in the specific example above, the - colon-separated environment variable PATH helps cmake find executables - that are installed in non-standard locations. - - + (Optional) set environment variables to specify the compilers and compiler - flags. - - Here is one particular example (which must be executed before the cmake - invocation discussed below). - - export CC="gcc -O2" - export CXX="g++ -O2" - export FC="g77 -O2" - - Note a better option is to set CMAKE_BUILD_TYPE to one of Debug, Release, - RelWithDebInfo, or MinSizeRel. If you don't set this variable and don't - set the environment variables above, then by default no compiler options - (i.e., no optimization and no debugging symbols) are used for gcc-related - compilers for our CBS which makes for fast builds, but slow execution. - - + cmake invocation. - - Here is one typical example. - - mkdir build_dir - cd build_dir - cmake -DCMAKE_INSTALL_PREFIX=/my/prefix \ - -DCMAKE_VERBOSE_MAKEFILE=ON ../plplot_cmake >& cmake.out - - Check the cmake.out file for any configuration issues, especially WARNING - messages which signal that a component of PLplot has been removed because - required system components for that component have not been found. - - Everything can be controlled with -D options to the cmake command. There - are a large number of CMake options for PLplot - (http://www.miscdebris.net/plplot_wiki/index.php?title=CMake_options_for_PLplot) - which can be set for cmake to personalize your build. Use the ccmake - front end to cmake to obtain documentation of all these options. In the - above case we have specified a particular install prefix "/my/prefix" and - verbose make results (essential if you want to see the exact commands - used for the build). - - Note in the above example an empty build directory called build_dir is - used to insure a clean start, and ../plplot_cmake is a freshly checked - out source tree (which remains clean because you never actually create - any files in that directory tree). To start fresh, simply execute "cd - build_dir; rm -rf *". Of course, this is an extremely dangerous command - (since it removes everything in the current directory and all - subdirectories), but you should be okay so long as you cd to the correct - directory before executing the "rm" command. - - + Post-cmake build, install, and build-tree and install-tree tests - - make >& make.out - make install >& make_install.out - - ctest - - cp -a /my/prefix/share/plplot5.6.1/examples /tmp - cd /tmp/examples - make >& make_examples.out - ./plplot-test.sh >& plplot_test.out - - Note, the build-tree tests done with ctest are limited to just the psc - (colour postscript) device and can only be performed if cmake is invoked - with the -DBUILD_TEST=ON option (which roughly doubles the build time - because all the examples must be built). - - Check all the *.out files for any errors. Check that the large number of - postscript files generated by plplot-test.sh look good with a postscript - viewer. Also, use the --help option to ./plplot-test.sh to see ways you - can test your PLplot install for devices other than the default psc - device. - - --------------------------------------------------------------------------- - Linux instructions for our CBS. - --------------------------------------------------------------------------- - - No changes from the generic Unix instructions. - - --------------------------------------------------------------------------- - MacOS X instructions for our CBS. - --------------------------------------------------------------------------- - - Few changes from the generic Unix instructions which need to be updated - from http://www.miscdebris.net/plplot_wiki/. - ------------------------------------------------------------------------------- -Windows instructions for our CBS (needs updating from -http://www.miscdebris.net/plplot_wiki/ ------------------------------------------------------------------------------- - -* Here is a typical way to use cmake on windows systems. -CMake comes with a graphical user-interface that allows you to set the -various build parameters interactively. It will try and find the -available compilers and other language tools that can be used for -PLplot and then generate a set of makefiles or project files depending -on what you chose. - -Alternatively you can use the command-line version. This is particularly -useful if you need to set one or more environment variables - you can -do that in a small batch file and then run CMake several times until -you have fine-tuned the build system. - -Once you have the makefiles or project files, you can use nmake or -Visual Studio to actually build the library and the examples. - -Typically the steps are: - - + Set any environment variables you need to set (if the - right compilers are not already in your path for instance) - - If you set them in a DOS-box, be sure to run CMake in - that same DOS-box! - - + Run CMakeSetup (the GUI version of CMake) or cmake (the - command-line version) to set the build parameters and - generate the make/project files - - + Run nmake or Visual Studio to build the library and - the examples - -CMake supports most flavours of Visual Studio project files (ranging -from VS 6.0 to VS.net 2005) and it can create makefiles suitable for -the nmake utility. - -Currently (august 2006) there are the following limitations: - - + No support for Compaq Visual Fortran yet - + No support for Java, Perl, Python or Tcl/Tk yet - + Support for additional libraries is limited: - - freetype (antialiasing fonts, smooth text): see notes below - - BGD (output in the form of GIF, JPEG or PNG files): none yet - - Qhull (advanced spatial interpolation): none yet - - (An important issue is that on Windows there is no standard - location to install _libraries_ as opposed to programs.) - -On the other hand: - - + Bindings for C and C++ (MSVC compiler) are no problem - + You can build both static (.lib) and dynamic link libraries (.dll) - -Note on the examples --------------------- -If you want to run the examples _before_ actually installing PLplot, -then you must copy some files into the directory holding the example -programs: - - + plstnd5.fnt and plxtnd5.fnt in the directory ...\data - + plplotd.dll and csirocsa.dll in the directories ...\lib and - ...\lib\csa respectively. - -Dealing with freetype on Windows --------------------------------- -N.B. We need a lot more information here. For now we only have Werner's -instructions for dealing with the freetype library on two different windows -systems. - -MinGW: -* download and unzip freetype 2.2.1 (ft221.zip) -* mingw32-make (compiler is detected) -* mingw32-make (to compile the library) -* copy objs\freetype.a objs\libfreetype.a -* set FREETYPEDIR=C:\DevZone\freetype-2.2.1 -* set PATH=%FREETYPEDIR%\objs;%PATH% -* set CMAKE_INCLUDE_PATH=%FREETYPEDIR%\include -* run cmake with your options - -Visual C++ 2005 -* download and unzip freetype 2.2.1 (ft221.zip) -* change line 69 of freetype-2.2.1\builds\compiler\visualc.mk to - CFLAGS ?= /nologo /c /Ox /W3 /WX /D_CRT_SECURE_NO_DEPRECATE - otherwise it stops the build because of warnings (/WX) since it - doesn't know the /G5 option (this may not be necessary for - Visual C++ 6.0 and/or 2003 -* path_to_gnu_make\mingw32-make setup visualc -* path_to_gnu_make\mingw32-make -* set FREETYPEDIR=C:\DevZone\freetype-2.2.1 -* set PATH=%FREETYPEDIR%\objs;%PATH% -* set CMAKE_INCLUDE_PATH=%FREETYPEDIR%\include -* run cmake with your options - |