/usr/share/doc/geographiclib/html/install.html is in geographiclib-tools 1.21-1ubuntu1.
This file is owned by root:root, with mode 0o644.
The actual contents of the file can be viewed below.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 | <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
<title>GeographicLib: Installing %GeographicLib</title>
<link href="tabs.css" rel="stylesheet" type="text/css"/>
<link href="doxygen.css" rel="stylesheet" type="text/css" />
</head>
<body>
<div id="top"><!-- do not remove this div! -->
<div id="titlearea">
<table cellspacing="0" cellpadding="0">
<tbody>
<tr style="height: 56px;">
<td style="padding-left: 0.5em;">
<div id="projectname">GeographicLib
 <span id="projectnumber">1.21</span>
</div>
</td>
</tr>
</tbody>
</table>
</div>
<!-- Generated by Doxygen 1.7.5 -->
<div id="navrow1" class="tabs">
<ul class="tablist">
<li><a href="index.html"><span>Main Page</span></a></li>
<li class="current"><a href="pages.html"><span>Related Pages</span></a></li>
<li><a href="namespaces.html"><span>Namespaces</span></a></li>
<li><a href="annotated.html"><span>Classes</span></a></li>
<li><a href="files.html"><span>Files</span></a></li>
<li><a href="dirs.html"><span>Directories</span></a></li>
</ul>
</div>
</div>
<div class="header">
<div class="headertitle">
<div class="title">Installing GeographicLib </div> </div>
</div>
<div class="contents">
<div class="textblock"><center> Back to <a class="el" href="intro.html">Introduction</a>. Forward to <a class="el" href="start.html">Getting started</a>. Up to <a class="el" href="index.html#contents">Contents</a>. </center><p>GeographicLib has been developed under Linux with the g++ compiler (versions 4.0 and later) and under Windows with Visual Studio 2005, 2008, and 2010. Earlier versions were tested also under Darwin and Solaris. It should compile on a wide range of other systems. First download either <a href="http://sourceforge.net/projects/geographiclib/files/distrib/GeographicLib-1.21.tar.gz/download">GeographicLib-1.21.tar.gz</a> or <a href="http://sourceforge.net/projects/geographiclib/files/distrib/GeographicLib-1.21.zip/download">GeographicLib-1.21.zip</a> (or <a href="http://sourceforge.net/projects/geographiclib/files/distrib/GeographicLib-1.21-win32.exe/download">GeographicLib-1.21-win32.exe</a> or <a href="http://sourceforge.net/projects/geographiclib/files/distrib/GeographicLib-1.21-win64.exe/download">GeographicLib-1.21-win64.exe</a> for binary installation under Windows). Then pick one of the first five options below:</p>
<ul>
<li><a class="el" href="install.html#cmake">Installation with cmake</a>. This is the preferred installation method as it will work on the widest range of platforms. However it requires that you have <a href="http://www.cmake.org">cmake</a> installed.</li>
<li><a class="el" href="install.html#autoconf">Installation using the autoconfigure tools</a>. This method works for most Unix-like systems, including Linux and Mac OS X.</li>
<li><a class="el" href="install.html#gnu">Installation with GNU compiler and Make</a>. This is a simple installation method that works with g++ and GNU make on Linux and many Unix platforms.</li>
<li><a class="el" href="install.html#windows">Installation on Windows</a>. This is a simple installation method that works with Visual Studio 2005, 2008, and 2010 under Windows.</li>
<li><a class="el" href="install.html#windowsbin">Using a binary installer for Windows</a>. Use this installation method if you only need to use the <a class="el" href="utilities.html">Utility programs</a> supplied with GeographicLib. (This method also installs the header files and the static library for use by Visual Studio 2010.)</li>
<li><a class="el" href="install.html#qt">Building the library for use with Qt</a>. How to compile GeographicLib so that it can be used by Qt programs.</li>
<li><a class="el" href="install.html#maintainer">Maintainer tasks</a>. This describes addition tasks of interest only to the maintainers of this code.</li>
</ul>
<p>This section documents only how to install the <em>software</em>. If you wish to use GeographicLib to evaluate geoid heights or the earth's gravitational or magnetic fields, then you must also install the relevant data files. See <a class="el" href="geoid.html#geoidinst">Installing the geoid datasets</a>, <a class="el" href="gravity.html#gravityinst">Installing the gravity models</a>, and <a class="el" href="magnetic.html#magneticinst">Installing the magnetic field models</a> for instructions.</p>
<p>The first two installation methods use two important techniques which make software maintanence simpler</p>
<ul>
<li><b>Out-of-source builds:</b> This means that you create a separate directory for compiling the code. In the description here the directories are called BUILD and are located in the top-level of the source tree. You might want to use a suffix to denote the type of build, e.g., BUILD-vc9 for Visual Studio 9, or BUILD-shared for a build which creates a shared library. The advantages of out-of-source builds are:<ul>
<li>You don't mess up the source tree, so it's easy to "clean up". Indeed the source tree might be on a read-only file system.</li>
<li>Builds for multiple platforms or compilers don't interfere with each other.</li>
</ul>
</li>
<li><b>The library is installed:</b> After compilation, there is a separate <em>install</em> step which copies the headers, libraries, tools, and documentation to a "central" location. You may at this point delete the source and build directories. If you have administrative privileges, you can install GeographicLib for the use of all users (e.g., in /usr/local). Otherwise, you can install it for your personal use (e.g., in $HOME/packages).</li>
</ul>
<h2><a class="anchor" id="cmake"></a>
Installation with cmake</h2>
<p>This is the recommended method of installation; however it requires that <a href="http://www.cmake.org">cmake</a> be installed on your system. This permits GeographicLib to be built either as a shared or a static library on a wide variety of systems. cmake can also determine the capabilities of your system and adjust the compilation of the libraries and examples appropriately.</p>
<p>cmake is available for most computer platforms. On Linux systems cmake will typically one of the standard packages and can be installed by a command like </p>
<div class="fragment"><pre class="fragment">
yum install cmake </pre></div><p> (executed as root). On other systems, download a binary installer from <a href="http://www.cmake.org">http://www.cmake.org</a> click on download, and save and run the appropriate installer. Run the cmake command with no arguments to get help. Other useful tools are ccmake and cmake-gui which offer curses and graphical interfaces to cmake. Building under cmake depends on whether it is targeting an IDE (interactive development environment) or generating Unix-style makefiles. The instructions below have been tested with makefiles and g++ on Linux and with the Visual Studio IDE on Windows.</p>
<p>Here are the steps to compile and install GeographicLib:</p>
<ul>
<li>Unpack the source, running one of <div class="fragment"><pre class="fragment">
tar xfpz GeographicLib-1.21.tar.gz
unzip -q GeographicLib-1.21.zip </pre></div> then enter the directory created with one of <div class="fragment"><pre class="fragment">
cd GeographicLib-1.21 </pre></div></li>
<li>Create a separate build directory and enter it, for example, <div class="fragment"><pre class="fragment">
mkdir BUILD
cd BUILD</pre></div></li>
<li>Run cmake, pointing it to the source directory (..). On Linux, Unix, and MacOSX systems, the command is <div class="fragment"><pre class="fragment">
cmake .. </pre></div> For Windows, the command is typically one of <div class="fragment"><pre class="fragment">
cmake -G "Visual Studio 10" -D CMAKE_INSTALL_PREFIX=C:/pkg-vc10/GeographicLib ..
cmake -G "Visual Studio 9 2008" -D CMAKE_INSTALL_PREFIX=C:/pkg-vc9/GeographicLib ..
cmake -G "Visual Studio 8 2005" -D CMAKE_INSTALL_PREFIX=C:/pkg-vc8/GeographicLib ..
</pre></div> Instead of setting CMAKE_INSTALL_PREFIX, you can (on Windows) set CMAKE_PREFIX_PATH to point to its parent directory, e.g., <div class="fragment"><pre class="fragment">
cmake -G "Visual Studio 10" -D CMAKE_PREFIX_PATH=C:/pkg-vc10 ..
</pre></div> The definitions of CMAKE_INSTALL_PREFIX are optional (see below). The settings given above are recommended to ensure that packages that use GeographicLib use the version compiled with the right compiler. If you need to rerun cmake, use <div class="fragment"><pre class="fragment">
cmake . </pre></div> possibly including some options via <code>-D</code> (see the next step).</li>
<li>cmake allows you to configure how GeographicLib is built and installed by supplying options, for example <div class="fragment"><pre class="fragment">
cmake -D CMAKE_INSTALL_PREFIX=/tmp/geographic . </pre></div> The options you might need to change are<ul>
<li><code>CMAKE_INSTALL_PREFIX</code> (default: /usr/local on non-Windows systems, C:/Program Files/GeographicLib on Windows systems) specifies where the library will be installed. For windows systems, it is recommended to use a prefix which includes the compiler version, as shown above (and also, possibly, whether this is a 64-bit build, e.g., <code>cmake -G "Visual Studio 10 Win64" -D CMAKE_INSTALL_PREFIX=C:/pkg-vc10-x64/GeographicLib ..</code>) If you just want to try the library to see if it suits your needs, pick <code>CMAKE_INSTALL_PREFIX</code>=/tmp/geographic, for example, and set <code>GEOGRAPHIC_SHARED_LIB</code>=OFF.</li>
<li><code>GEOGRAPHICLIB_DATA</code> (default: /usr/local/share/GeographicLib for non-Windows systems, C:/Documents and Settings/All Users/Application Data/GeographicLib for Windows systems) specifies the default location for the various datasets for use by <a class="el" href="classGeographicLib_1_1Geoid.html" title="Looking up the height of the geoid.">GeographicLib::Geoid</a>, <a class="el" href="classGeographicLib_1_1GravityModel.html" title="Model of the earth's gravity field.">GeographicLib::GravityModel</a>, and <a class="el" href="classGeographicLib_1_1MagneticModel.html" title="Model of the earth's magnetic field.">GeographicLib::MagneticModel</a>. See <a class="el" href="geoid.html#geoidinst">Installing the geoid datasets</a>, <a class="el" href="gravity.html#gravityinst">Installing the gravity models</a>, and <a class="el" href="magnetic.html#magneticinst">Installing the magnetic field models</a> for more information.</li>
<li><code>GEOGRAPHIC_SHARED_LIB</code> (default: ON for non-Windows systems, OFF for Windows systems) determines whether a shared or static library is built. The default is OFF for Windows because there's no standard place to install the dlls.</li>
<li><code>CMAKE_BUILD_TYPE</code> (default: Release). This flags only affects non-IDE compile environments (like make + g++). The default is actually blank, but this is treated as Release. Choose one of <div class="fragment"><pre class="fragment">
Debug
Release
RelWithDebInfo
MinSizeRel
</pre></div> (With IDE compile environments, you get to select the build type in the IDE.)</li>
<li><code>MATLAB_COMPILER</code> (default: OFF). Set this to either "mex" (for Matlab) or "mkoctfile" (for Octave) to specify the compiler to use for the Matlab/Octave interface. See <a class="el" href="other.html#matlab">Matlab and Octave interfaces</a> for more information.</li>
<li><code>MAINTAINER</code> (default: ON for non-Windows environments provided doxygen, pod2man, and pod2html are found). This affects whether the targets for creating source packages are activated. See <a class="el" href="install.html#maintainer">Maintainer tasks</a> for details.</li>
<li><code>GEOGRAPHICLIB_EXAMPLES</code> (default: ON for the maintainer and OFF otherwise). If set to ON, then the short example programs in the <code>examples</code> directory are built.</li>
</ul>
</li>
<li>Build and install the software. In non-IDE environments, run <div class="fragment"><pre class="fragment">
make # compile the library and the examples
make test # run some tests
make install # as root, if CMAKE_INSTALL_PREFIX is a system directory
</pre></div> On IDE environments, run your IDE (e.g., Visual Studio), load GeographicLib.sln, pick the build type (e.g., Release), and select "Build
Solution". If this succeeds, select "RUN_TESTS" to build. Finally, select "INSTALL" to build.</li>
<li>The headers, library, and utilities are installed in the include/GeographicLib, lib, and bin directories under <code>CMAKE_INSTALL_PREFIX</code>. (dll dynamic libraries are installed in bin.) The Matlab/Octave interface is installed in libexec/GeographicLib/matlab. For documentation, open <a href="index.html">share/doc/GeographicLib/html/index.html</a> in a web browser.</li>
</ul>
<h2><a class="anchor" id="autoconf"></a>
Installation using the autoconfigure tools</h2>
<p>The method works on most Unix-like systems including Linux and Mac OS X. Here are the steps to compile and install GeographicLib:</p>
<ul>
<li>Unpack the source, running <div class="fragment"><pre class="fragment">
tar xfpz GeographicLib-1.21.tar.gz </pre></div> then enter the directory created <div class="fragment"><pre class="fragment">
cd GeographicLib-1.21 </pre></div></li>
<li>Create a separate build directory and enter it, for example, <div class="fragment"><pre class="fragment">
mkdir BUILD
cd BUILD</pre></div></li>
<li>Configure the software, specifing the path of the source directory, with <div class="fragment"><pre class="fragment">
../configure </pre></div></li>
<li>By default GeographicLib will be installed under /usr/local. You can change this with, for example <div class="fragment"><pre class="fragment">
../configure --prefix=/tmp/geographic </pre></div></li>
<li>Compile and install the software with <div class="fragment"><pre class="fragment">
make
make install </pre></div></li>
<li>The headers, library, and utilities are installed in the include/GeographicLib, lib, and bin directories under <code>prefix</code>. This installation method does not compile the Matlab/Octave interface; however the source for the interface is installed in libexec/GeographicLib/matlab, see <a class="el" href="other.html#matlab">Matlab and Octave interfaces</a> of instructions on compiling the interface. For documentation, open <a href="index.html">share/doc/GeographicLib/html/index.html</a> in a web browser.</li>
</ul>
<h2><a class="anchor" id="gnu"></a>
Installation with GNU compiler and Make</h2>
<p>This method requires the standard GNU suite of tools, in particular make and g++. This builds a static library and the examples.</p>
<p>Here are the steps to compile and install GeographicLib:</p>
<ul>
<li>Unpack the source, running <div class="fragment"><pre class="fragment">
tar xfpz GeographicLib-1.21.tar.gz </pre></div> then enter the directory created <div class="fragment"><pre class="fragment">
cd GeographicLib-1.21 </pre></div></li>
<li>Edit <div class="fragment"><pre class="fragment">
include/GeographicLib/Config.h </pre></div> If your C++ compiler does not recognize the long double type (unlikely), insert <div class="fragment"><pre class="fragment"><span class="preprocessor"> #undef HAVE_LONG_DOUBLE </span>
</pre></div> If you machine using big endian ordering, then insert <div class="fragment"><pre class="fragment"><span class="preprocessor"> #define WORDS_BIGENDIAN 1 </span>
</pre></div></li>
<li>Build and install the software: <div class="fragment"><pre class="fragment">
make # compile the library and the examples
make install # as root </pre></div> The installation is in directories under /usr/local. You can specify a different installation directory with, for example, <div class="fragment"><pre class="fragment">
make PREFIX=/tmp/geographic install </pre></div></li>
<li>The headers, library, and utilities are installed in the include/GeographicLib, lib, and bin directories under <code>PREFIX</code>. This installation method does not compile the Matlab/Octave interface; however the source for the interface is installed in libexec/GeographicLib/matlab, see <a class="el" href="other.html#matlab">Matlab and Octave interfaces</a> of instructions on compiling the interface. For documentation, open <a href="index.html">share/doc/GeographicLib/html/index.html</a> in a web browser.</li>
</ul>
<h2><a class="anchor" id="windows"></a>
Installation on Windows</h2>
<p>This method requires Visual Studio 2005, 2008, or 2010. This builds a static library and the utilities. If you only have Visual Studio 2003, use cmake to create the necessary solution file, see <a class="el" href="install.html#cmake">Installation with cmake</a>. (cmake is needed to build the Matlab interface and to run the tests.)</p>
<ul>
<li>Unpack the source, running <div class="fragment"><pre class="fragment">
unzip -q GeographicLib-1.21.zip </pre></div></li>
<li>Open GeographicLib-1.21/windows/GeographicLib-vc10.sln in Visual Studio 2010 (for Visual Studio 2005 and 2008, replace -vc10 by -vc8 or -vc9).</li>
<li>Pick the build type (e.g., Release), and select "Build Solution".</li>
<li>The library and the compiled examples are in the windows/Release.</li>
<li>Copy the library windows/Release/Geographic.lib and the headers in include/GeographicLib somewhere convenient. The headers should remain in a directory named GeographicLib. If you expect to use the Matlab/Octave interface, copy matlab/*.m and matlab/*.cpp to a directory in your matlab/octave path, see <a class="el" href="other.html#matlab">Matlab and Octave interfaces</a> for instructions on compiling the interface. For documentation, open <a href="index.html">doc/html/index.html</a> in a web browser.</li>
</ul>
<h2><a class="anchor" id="windowsbin"></a>
Using a binary installer for Windows</h2>
<p>Use this method if you only need to use the GeographicLib utilities. The header files and static library are provided, but can only be used by Visual Studio 2010 in release mode. However, if you plan to use the library, it is advisable to build it with the compiler you are using for your own code using either <a class="el" href="install.html#cmake">Installation with cmake</a> or <a class="el" href="install.html#windows">Installation on Windows</a>.</p>
<p>Download and run <a href="http://sourceforge.net/projects/geographiclib/files/distrib/GeographicLib-1.21-win32.exe/download">GeographicLib-1.21-win32.exe</a> or <a href="http://sourceforge.net/projects/geographiclib/files/distrib/GeographicLib-1.21-win64.exe/download">GeographicLib-1.21-win64.exe</a>:</p>
<ul>
<li>read the MIT/X11 License agreement,</li>
<li>select whether you want your PATH modified,</li>
<li>select the installation folder, by default C:\pkg-vc10\GeographicLib-1.21 or C:\pkg-vc10-x64\GeographicLib-1.21,</li>
<li>select the start menu folder,</li>
<li>and install.</li>
</ul>
<p>(Note that the default installation folder adheres the the convention given in <a class="el" href="install.html#cmake">Installation with cmake</a>.) The start menu will now include links to the documentation for the library and for the utilities (and a link for uninstalling the library). If you ask for your PATH to be modified, it will include C:/pkg-vc10/GeographicLib-1.21/bin where the utilities are installed. The headers and library are installed in the include/GeographicLib and lib folders. With the 64-bit installer, the Matlab interface is installed in the libexec/GeographicLib/matlab folder. Add this to your path in Matlab to access this interface. The binaries were built using Visual Studio 10 (2010) in Release mode. The Matlab interface was compiled with Matlab R2010b 64-bit, however it may work with some other 64-bit versions of Matlab.</p>
<h2><a class="anchor" id="qt"></a>
Building the library for use with Qt</h2>
<p>If Qt is using a standard compiler, then build GeographicLib with that same compiler (and optimization flags) as Qt.</p>
<p>If you are using the mingw compiler on Windows for Qt, then you need to build GeographicLib with mingw. You can accomplish this with cmake under cygwin with, for example, </p>
<div class="fragment"><pre class="fragment">
export PATH="`cygpath -m c:/QtSDK/mingw/bin`:$PATH"
mkdir BUILD
cd BUILD
cmake -G "MinGW Makefiles" -D CMAKE_INSTALL_PREFIX=C:/pkg-mingw/GeographicLib ..
mingw32-make
mingw32-make install </pre></div><p> If cmake complains that sh mustn't be in your path, invoke cmake with </p>
<div class="fragment"><pre class="fragment">
env PATH="$( echo $PATH | tr : '\n' |
while read d; do test -f "$d/sh.exe" || echo -n "$d:"; done |
sed 's/:$//' )" cmake -G "MinGW Makefiles" -D CMAKE_INSTALL_PREFIX=C:/pkg-mingw/GeographicLib ..
</pre></div><p> If cmake is not available, there is a simple project file that compiles the GeographicLib library <em>only</em> with the Qt compiler: </p>
<div class="fragment"><pre class="fragment">
cd src
qmake Geographic.pro # configure the project
make # build the library </pre></div><p> The library will be in the src directory (or the src/release or src/debug directory under Windows). The headers are in include/GeographicLib.</p>
<h2><a class="anchor" id="maintainer"></a>
Maintainer tasks</h2>
<p>Check the code out of git with </p>
<div class="fragment"><pre class="fragment">
git clone git://geographiclib.git.sf.net/gitroot/geographiclib/geographiclib
</pre></div><p> The autoconf configuration script, the html version of the documentation, and the formatted man pages not checked into git. In order to create the autoconf configuration script, run </p>
<div class="fragment"><pre class="fragment">
sh autogen.sh </pre></div><p> in the top level directory. Provided you are running on a system with doxygen, pod2man, and pod2html installed, then you can create the documentation and the man pages by building the system using cmake (the <code>MAINTAINER</code> configuration variable set to ON, if the necessary tools are found) or configure.</p>
<p>In the case of cmake, you then run </p>
<div class="fragment"><pre class="fragment">
make dist </pre></div><p> which will copy the documentation and man pages from the build directory back into the source tree and package the resulting source tree for distribution as </p>
<div class="fragment"><pre class="fragment">
GeographicLib-1.21.tar.gz
GeographicLib-1.21.zip </pre></div><p> Finally, </p>
<div class="fragment"><pre class="fragment">
make package </pre></div><p> or building PACKAGE in Visual Studio will create a binary installer for GeographicLib. For Windows, this requires in the installation of <a href="http://nsis.sourceforge.net">NSIS</a>.</p>
<p>With configure, run </p>
<div class="fragment"><pre class="fragment">
make dist-gzip </pre></div><p> which will create the additional files and packages the results ready for distribution as </p>
<div class="fragment"><pre class="fragment">
geographiclib-1.21.tar.gz </pre></div><center> Back to <a class="el" href="intro.html">Introduction</a>. Forward to <a class="el" href="start.html">Getting started</a>. Up to <a class="el" href="index.html#contents">Contents</a>. </center> </div></div>
<hr class="footer"/><address class="footer"><small>
Generated on Tue Apr 24 2012 17:54:16 for GeographicLib by  <a href="http://www.doxygen.org/index.html">
<img class="footer" src="doxygen.png" alt="doxygen"/>
</a> 1.7.5
</small></address>
</body>
</html>
|