Menu
▾
▴
[Plplot-cvs] SF.net SVN: plplot:[9290] trunk/INSTALL
|
From: <ai...@us...> - 2009-01-11 02:24:42
|
Revision: 9290
http://plplot.svn.sourceforge.net/plplot/?rev=9290&view=rev
Author: airwin
Date: 2009-01-11 02:24:37 +0000 (Sun, 11 Jan 2009)
Log Message:
-----------
Update configure, build, and install instructions following cut-and-paste
from (updated)
http://www.miscdebris.net/plplot_wiki/index.php?title=Building_PLplot
Modified Paths:
--------------
trunk/INSTALL
Modified: trunk/INSTALL
===================================================================
--- trunk/INSTALL 2009-01-09 05:56:04 UTC (rev 9289)
+++ trunk/INSTALL 2009-01-11 02:24:37 UTC (rev 9290)
@@ -1,338 +1,130 @@
-PLplot installation
-===================
+PLplot Configuration, Build, and Installation
+=============================================
-- (For UNIX, Linux, MacOS X, Cygwin, MinGW, MinGW/MSYS, and bare windows,
-i.e., all systems other than DJGPP.) Use our CMake-based build system.
+The definitive set of instructions is given at
+http://www.miscdebris.net/plplot_wiki/index.php?title=Building_PLplot. The
+material below is cut and pasted from there as of 2009-01-10.
-- DJGPP on (Free)DOS. Follow the directions at sys/dos/djgpp/readme
+With the exception of DJGPP on (Free)DOS (where you should follow the
+directions at sys/dos/djgpp/readme) all PLplot builds are done with our
+CMake-based build system which gives good results on Unix, Linux, and Mac OS
+X and Cygwin, MinGW, MinGW/MSYS, and bare windows.
+Building PLplot with our CMake-based build system
+=================================================
-PLplot installation notes for our CMake-based 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-based Build System has been made available as part of our
+Our CMake-based build system has been made available as part of our
development releases of PLplot starting with version 5.7.0 and is now with
the exception of the DJGPP platform our sole build system. It is important
to consult the CMake documentation to get the most out of our build system.
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.
+for your convenience at
+http://www.miscdebris.net/plplot_wiki/index.php?title=General_CMake_documentation_links.
-After consulting that documentation, install
-(http://cmake.org/HTML/Install.html) the appropriate package of
+After consulting that documentation, install 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.
+CMake for your PLplot configuration, but our build system works with the
+latest version (2.6.2) of CMake as well.
+Generic Unix instructions for our build system
+==============================================
-------------------------------------------------------------------------------
-Some general remarks on CMake
-------------------------------------------------------------------------------
+(Optional) set environment variables to help cmake find system components
+that are installed in non-standard locations
+-------------------------------------------------------------------------
-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).
+Here is one particular example (which must be executed before the cmake
+invocation discussed below).
-The approach we have found most useful in using CMake to build PLplot is
-this:
+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
-* Copy the sources in one directory
-* Create a separate directory to build and install the software itself
- (libraries and the executables for the examples)
+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.
-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.
+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.
-CMake has two interfaces:
+(Optional) set environment variables to specify the compilers and compiler
+flags
+--------------------------------------------------------------------------
-* The command-line interface "cmake"
+Here is one particular example (which must be executed before the cmake
+invocation discussed below).
-* The graphical user-interface ccmake (or CmakeSetup under Windows)
+export CC="gcc -O2"
+export CXX="g++ -O2"
+export FC="g77 -O2"
-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.
+If you 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 build system which makes for fast builds,
+but slow execution.
-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.
+cmake invocation
+----------------
-Whichever of two you take, the steps are:
+Here is one typical example.
-* Set up the environment (if this is needed, for instance to find the
- compilers and extra libraries)
+mkdir build_dir
+cd build_dir
+cmake -DCMAKE_INSTALL_PREFIX=/my/prefix \
+../plplot_cmake >& cmake.out
-* Run CMake with the right options to create makefiles or project files
+(CMake is capable of generating builds within the source tree, but we have
+emphasized a build with a separate build tree here because of its
+fundamental advantage that the source tree remains clean with no generated
+files in it.)
-* Run the native build system (nmake or the proper IDE) to actually
- build the library.
+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.
-------------------------------------------------------------------------------
-Generic Unix instructions for our CMake-based build system
-------------------------------------------------------------------------------
+There are a large number of CMake options for PLplot (see
+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".
- + (Optional) set environment variables to help cmake find system components
- that are installed in non-standard locations.
+Note in the above example an initially empty build directory called
+build_dir is used to insure a clean start, and ../plplot_cmake is a freshly
+checked out source tree from our svn repository or the name of the source
+tree created when you unpacked a PLplot source distribution tarball. Note,
+the name "plplot_cmake" is only for this example, and the name will most
+likely be something else on your system.
- Here is one particular example (which must be executed before the cmake
- invocation discussed below).
+To start a fresh build, simply execute "cd build_dir; rm -rf *" before
+invoking cmake. Of course, "rm -rf *" 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.
- 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
+Build and install
+-----------------
- 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.
+make >& make.out
+make install >& make_install.out
- 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.
+Check make.out and make_install.out for any errors. Follow up by testing
+PLplot (see
+http://www.miscdebris.net/plplot_wiki/index.php?title=Testing_PLplot and
+README.testing).
- + (Optional) set environment variables to specify the compilers and compiler
- flags.
+Platform-specific remarks about building PLplot
+===============================================
- Here is one particular example (which must be executed before the cmake
- invocation discussed below).
+See
+http://www.miscdebris.net/plplot_wiki/index.php?title=Specifics_for_various_platforms.
- 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 build system 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 build system.
- ---------------------------------------------------------------------------
-
- No changes from the generic Unix instructions.
-
- ---------------------------------------------------------------------------
- MacOS X instructions for our build system.
- ---------------------------------------------------------------------------
-
- No changes from the generic Unix instructions.
-
- Things to be aware of on OS-X are the following:
- 1. The wxWidgets driver should be off as the version of wxWidgets that
- OS-X (10.4) ships with is not a recent enough version.
- (PLD_wxwidgets = OFF).
- 2. Cmake is really good at finding libraries, but not so good at figuring
- out which is the right library to use when multiple options are present.
- Since a typical OS-X installation will often (unfortunately) have
- multiple versions of the same library in different locations (e.g.
- /sw, /opt, /usr and various Framework directories), care must be taken
- to make sure that the desired library is being used. Furthermore it is
- important to make sure it is the only one being used, and that you are
- not instead pulling the header files from one place and the library
- itself from another.
-
-------------------------------------------------------------------------------
-Windows instructions for our build system (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
-
-
-------------------------------------------------------------------------------
-Cygwin instructions for our build system
-------------------------------------------------------------------------------
-
-* Building and installing PLplot under Cygwin is done in the same way as
- under UNIX or Linux. There is one caveat, however, that has to do with
- the way the Windows platform finds dynamic libraries:
-
- In contrast to UNIX and Linux, there is no facility to build
- into an executable the path to the dynamic libraries (DLLs) it
- requires. Under UNIX and Linux this facility is called the "rpath"
- option. Under Windows and - therefore - under Cygwin there is no such
- option at all. Nor is there is a search path via an environment
- variable like LD_LIBRARY_PATH.
-
- Instead, programs find their libraries exclusively via the PATH
- environment variable.
-
- So, when you have built PLplot and installed it, you must add the
- install directory to your PATH before the examples can run
- successfully.
-
-* This lack of an rpath option is important at build time too, when
- you use dynamic drivers: before building PLplot, add the following
- directories to your path:
-
- + <build>/src
- + <build>/lib/csa
-
- where "build" points to the directory in which you build PLplot.
- This is the easiest way to do so:
-
- export PATH=`pwd`/src:`pwd`/libcsa:$PATH
- cmake ...
This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site.
|
