GeographicLib
1.43
|
GeographicLib has been developed under Linux with the g++ compiler (versions 4.0 and later) and under Windows with Visual Studio 2010, 2012, and 2013. Earlier versions were tested also under Visual Studio 2005 and 2008 and under Darwin and Solaris. It should compile on a wide range of other systems. First download either GeographicLib-1.43.tar.gz or GeographicLib-1.43.zip (or GeographicLib-1.43-win32.exe or GeographicLib-1.43-win64.exe for binary installation under Windows). Then pick one of the first five options below:
This section documents only how to install the software. 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 Installing the geoid datasets, Installing the gravity models, and Installing the magnetic field models for instructions.
The first two installation methods use two important techniques which make software maintenance simpler
This is the recommended method of installation; however it requires that cmake 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.
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
yum install cmake
(executed as root). The minimum version of cmake supported for building GeographicLib is 2.8.4 (which was released on 2011-02-16). (Actually, a few earlier versions will also work for non-Windows platforms.)
On other systems, download a binary installer from http://www.cmake.org 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. It is known to work also for Visual Studio 12 Express (2013).
Here are the steps to compile and install GeographicLib:
tar xfpz GeographicLib-1.43.tar.gz unzip -q GeographicLib-1.43.zipthen enter the directory created with one of
cd GeographicLib-1.43
mkdir BUILD cd BUILD
cmake ..For Windows, the command is typically one of
cmake -G "Visual Studio 10" -D CMAKE_INSTALL_PREFIX=C:/pkg-vc10/GeographicLib-1.43 .. cmake -G "Visual Studio 9 2008" -D CMAKE_INSTALL_PREFIX=C:/pkg-vc9/GeographicLib-1.43 ..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
cmake .possibly including some options via
-D
(see the next step).cmake -D CMAKE_INSTALL_PREFIX=/tmp/geographic .The options you might need to change are
COMMON_INSTALL_PATH
governs the installation convention. If it is on ON (the Linux default), the installation is to a common directory, e.g., /usr/local. If it is OFF (the Windows default), the installation directory contains the package name, e.g., C:/pkg/GeographicLib-1.43. The installation directories for the documentation, cmake configuration, python and matlab interfaces all depend on the variable with deeper paths relative to CMAKE_INSTALL_PREFIX being used when it's ON:CMAKE_INSTALL_PREFIX
(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., cmake -G "Visual Studio 10 Win64" -D CMAKE_INSTALL_PREFIX=C:/pkg-vc10-x64/GeographicLib-1.43 ..
). If you just want to try the library to see if it suits your needs, pick, for example, CMAKE_INSTALL_PREFIX
=/tmp/geographic.GEOGRAPHICLIB_DATA
(default: /usr/local/share/GeographicLib for non-Windows systems, C:/ProgramData/GeographicLib for Windows systems) specifies the default location for the various datasets for use by Geoid, GravityModel, and MagneticModel. See Installing the geoid datasets, Installing the gravity models, and Installing the magnetic field models for more information.GEOGRAPHICLIB_LIB_TYPE
(allowed values: SHARED, STATIC, or BOTH), specifies the types of libraries build. The default is STATIC for Windows and SHARED otherwise. If building GeographicLib for system-wide use, BOTH is recommended, because this provides users with the choice of which library to use.CMAKE_BUILD_TYPE
(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 Debug Release RelWithDebInfo MinSizeRel(With IDE compile environments, you get to select the build type in the IDE.)
GEOGRAPHICLIB_DOCUMENTATION
(default: OFF). If set to ON, then html documentation is created from the source files, provided a sufficiently recent version of doxygen can be found. Otherwise, the html documentation will redirect to the appropriate version of the online documentation.BUILD_NETGEOGRAPHICLIB
(default: OFF). If set to ON, build the managed C++ wrapper library NETGeographicLib. This only makes sense for Windows systems.GEOGRAPHICLIB_PRECISION
specifies the precision to be used for "real" (i.e., floating point) numbers. Here are the possible valuesmake # compile the library and the examples make test # run some tests make install # as root, if CMAKE_INSTALL_PREFIX is a system directoryPossible additional targets are
make dist make exampleprograms make netexamples (supported only for Release configuration)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 install (RUN_TESTS and INSTALL are in the CMakePredefinedTargets folder). Alternatively, you run the Visual Studio compiler from the command line with
cmake --build . --config Release --target ALL_BUILD cmake --build . --config Release --target RUN_TESTS cmake --build . --config Release --target INSTALLFor maximum flexibility, it's a good idea to build and install both the Debug and Release versions of the library (in that order). The installation directories will then contain the release versions of the tools and both versions (debug and release) of the libraries. If you use cmake to configure and build your programs, then the right version of the library (debug vs. release) will automatically be used.
CMAKE_INSTALL_PREFIX
. (dll dynamic libraries are installed in bin.) For documentation, open in a web browser PREFIX/share/doc/GeographicLib/html/index.html, if COMMON_INSTALL_PATH is ON, or PREFIX/doc/index.html, otherwise.The method works on most Unix-like systems including Linux and Mac OS X. Here are the steps to compile and install GeographicLib:
tar xfpz GeographicLib-1.43.tar.gzthen enter the directory created
cd GeographicLib-1.43
mkdir BUILD cd BUILD
../configure
../configure --prefix=/tmp/geographic
make make install
prefix
. For documentation, open share/doc/GeographicLib/html/index.html in a web browser.This method requires the standard GNU suite of tools, in particular make and g++. This builds a static library and the examples.
Here are the steps to compile and install GeographicLib:
tar xfpz GeographicLib-1.43.tar.gzthen enter the directory created
cd GeographicLib-1.43
include/GeographicLib/Config.hIf your C++ compiler does not recognize the long double type (unlikely), insert
make # compile the library and the examples make install # as rootThe installation is in directories under /usr/local. You can specify a different installation directory with, for example,
make PREFIX=/tmp/geographic install
PREFIX
. For documentation, open share/doc/GeographicLib/html/index.html in a web browser.This method requires Visual Studio 2008 or 2010. This builds a static library and the utilities. If you have some other version of Visual Studio, use cmake to create the necessary solution file, see Installation with cmake. (cmake is needed to run the tests.)
unzip -q GeographicLib-1.43.zip
The Visual Studio 10 solution also contains projects to build NETGeographicLib and the C# example project.
Binary installers are available for some platforms
Use this method if you only need to use the GeographicLib utilities. The header files and static and shared versions of library are also provided; these can only be used by Visual Studio 11 2012 (in either release or debug mode). However, if you plan to use the library, it may be advisable to build it with the compiler you are using for your own code using either Installation with cmake or Installation on Windows.
Download and run GeographicLib-1.43-win32.exe or GeographicLib-1.43-win64.exe:
(Note that the default installation folder adheres the the convention given in Installation with cmake.) 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-vc11/GeographicLib-1.43/bin where the utilities are installed. The headers and library are installed in the include/GeographicLib and lib folders. The MATLAB interface is installed in the matlab folder. Add this to your path in MATLAB to access this interface. The libraries were built using using Visual Studio 11 2012 in release and debug modes. The utilities were linked against the release-mode shared library.
NETGeographicLib library dlls (release and debug) are included with the binary installers; these are linked against the shared library for GeographicLib.
You can install using Homebrew. Follow the directions on http://brew.sh/ for installing this package manager. Then type
brew install geographiclib
Now links to GeographicLib are installed under /usr/local.
Some Linux distributions, Fedora, Debian, and Ubuntu, offer GeographicLib as a standard package. Typically these will be one or two versions behind the latest.
If Qt is using a standard compiler, then build GeographicLib with that same compiler (and optimization flags) as Qt.
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,
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
If cmake complains that sh mustn't be in your path, invoke cmake with
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 ..
If cmake is not available, there is a simple project file that compiles the GeographicLib library only with the Qt compiler:
cd src qmake GeographicLib.pro # configure the project make # build the library
The library will be in the src directory (or the src/release or src/debug directory under Windows). The headers are in include/GeographicLib.
Check the code out of git with
git clone -b master git://git.code.sf.net/p/geographiclib/code geographiclib
Here the "master" branch is checked out. There are three branches in the git repository:
The autoconf configuration script and the formatted man pages are not checked into master branch of the repository. In order to create the autoconf configuration script, run
sh autogen.sh
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 or configure.
In the case of cmake, you then run
make dist
which will copy the man pages from the build directory back into the source tree and package the resulting source tree for distribution as
GeographicLib-1.43.tar.gz GeographicLib-1.43.zip
Finally,
make package
or building PACKAGE in Visual Studio will create a binary installer for GeographicLib. For Windows, this requires in the installation of NSIS. On Windows, you should configure GeographicLib with PACKAGE_DEBUG_LIBS
=ON, build both Release and Debug versions of the library and finally build PACKAGE in Release mode. This will get the release and debug versions of the library included in the package. For example, the 64-bit binary installer is created with
cmake -G "Visual Studio 10 Win64" \ -D GEOGRAPHICLIB_LIB_TYPE=BOTH \ -D PACKAGE_DEBUG_LIBS=ON \ -D BUILD_NETGEOGRAPHICLIB=ON \ .. cmake --build . --config Debug --target ALL_BUILD cmake --build . --config Release --target ALL_BUILD cmake --build . --config Release --target matlabinterface cmake --build . --config Release --target PACKAGE
With configure, run
make dist-gzip
which will create the additional files and packages the results ready for distribution as
geographiclib-1.43.tar.gz