/usr/share/doc/geographiclib/html/start.html is in geographiclib-doc 1.49-2.
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 | <!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"/>
<meta http-equiv="X-UA-Compatible" content="IE=9"/>
<meta name="generator" content="Doxygen 1.8.13"/>
<meta name="viewport" content="width=device-width, initial-scale=1"/>
<title>GeographicLib: Getting started</title>
<link href="tabs.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="jquery.js"></script>
<script type="text/javascript" src="dynsections.js"></script>
<script type="text/x-mathjax-config">
MathJax.Hub.Config({
extensions: ["tex2jax.js"],
jax: ["input/TeX","output/HTML-CSS"],
});
</script><script type="text/javascript" src="/usr/share/javascript/mathjax/MathJax.js/MathJax.js"></script>
<link href="doxygen.css" rel="stylesheet" type="text/css" />
</head>
<body>
<div id="top"><!-- do not remove this div, it is closed by doxygen! -->
<div id="titlearea">
<table cellspacing="0" cellpadding="0">
<tbody>
<tr style="height: 56px;">
<td id="projectalign" style="padding-left: 0.5em;">
<div id="projectname">GeographicLib
 <span id="projectnumber">1.49</span>
</div>
</td>
</tr>
</tbody>
</table>
</div>
<!-- end header part -->
<!-- Generated by Doxygen 1.8.13 -->
<script type="text/javascript" src="menudata.js"></script>
<script type="text/javascript" src="menu.js"></script>
<script type="text/javascript">
$(function() {
initMenu('',false,false,'search.php','Search');
});
</script>
<div id="main-nav"></div>
</div><!-- top -->
<div class="header">
<div class="headertitle">
<div class="title">Getting started </div> </div>
</div><!--header-->
<div class="contents">
<div class="textblock"><center> Back to <a class="el" href="install.html">Installing GeographicLib</a>. Forward to <a class="el" href="utilities.html">Utility programs</a>. Up to <a class="el" href="index.html#contents">Contents</a>. </center><p>Much (but not all!) of the useful functionality of <a class="el" href="namespaceGeographicLib.html" title="Namespace for GeographicLib. ">GeographicLib</a> is available via simple command line utilities. Interfaces to some of them are available via the web. See <a class="el" href="utilities.html">Utility programs</a> for documentation on these.</p>
<p>In order to use <a class="el" href="namespaceGeographicLib.html" title="Namespace for GeographicLib. ">GeographicLib</a> from C++ code, you will need to</p><ul>
<li>Include the header files for the <a class="el" href="namespaceGeographicLib.html" title="Namespace for GeographicLib. ">GeographicLib</a> classes in your code. E.g.,<div class="fragment"><div class="line"><span class="preprocessor">#include <<a class="code" href="LambertConformalConic_8hpp.html">GeographicLib/LambertConformalConic.hpp</a>></span> </div></div><!-- fragment --></li>
<li>Include the <a class="el" href="namespaceGeographicLib.html" title="Namespace for GeographicLib. ">GeographicLib</a>:: namespace prefix to the <a class="el" href="namespaceGeographicLib.html" title="Namespace for GeographicLib. ">GeographicLib</a> classes, or include<div class="fragment"><div class="line"><span class="keyword">using namespace </span><a class="code" href="namespaceGeographicLib.html">GeographicLib</a>; </div></div><!-- fragment --> in your code.</li>
<li>Finally compile and link your code. You have two options here.<ul>
<li>Use cmake to build your package. If you are familiar with cmake this typically will be far the simplest option.</li>
<li>Set the include paths and linking options "manually".</li>
</ul>
</li>
<li><p class="startli">Building your code with cmake. In brief, the necessary steps are:</p><ul>
<li>include in your CMakeLists.txt files<pre class="fragment"> find_package (GeographicLib 1.34 REQUIRED)
include_directories (${GeographicLib_INCLUDE_DIRS})
add_definitions (${GeographicLib_DEFINITIONS})
add_executable (program source1.cpp source2.cpp)
target_link_libraries (program ${GeographicLib_LIBRARIES}) </pre> If you're using cmake version 2.8.11 or later, you can omit the <code>include_directories </code> and <code>add_definitions</code> lines.</li>
<li>configure your package, e.g., with<pre class="fragment"> mkdir BUILD
cd BUILD
cmake -G "Visual Studio 12" -A x64 \
-D CMAKE_PREFIX_PATH=C:/pkg-vc10-x64 \
-D CMAKE_INSTALL_PREFIX=C:/pkg-vc10-x64/testgeographic \
.. </pre> Note that you almost always want to configure and build your code somewhere other than the source directory (in this case, we use the BUILD subdirectory). Also, on Windows, make sure that the version of Visual Sudio (12 in the example above) architecture (x64 in the example above) matches that used to build <a class="el" href="namespaceGeographicLib.html" title="Namespace for GeographicLib. ">GeographicLib</a>.</li>
<li>build your package. On Linux and MacOS this usually involves just running make. On Windows, you can load the solution file created by cmake into Visual Studio; alternatively, you can get cmake to run build your code with<pre class="fragment"> cmake --build . --config Release --target ALL_BUILD </pre> You might also want to install your package (using "make install" or build the "INSTALL" target with the command above).</li>
</ul>
<p>The most import step is the find_package command. The cmake documentation describes the locations searched by find_package (the appropriate rule for <a class="el" href="namespaceGeographicLib.html" title="Namespace for GeographicLib. ">GeographicLib</a> are those for "Config" mode lookups). In brief, the locations that are searched are (from least specific to most specific, i.e., in <em>reverse</em> order) are</p><ul>
<li>under the system paths, i.e., locations such as <code>C:/Program Files</code> and <code>/usr/local</code>);</li>
<li>frequently, it's necessary to search within a "package directory" (or set of directories) for external dependencies; this is given by a (semicolon separated) list of directories specified by the cmake variable <code>CMAKE_PREFIX_PATH</code> (illustrated above);</li>
<li>the package directory for <a class="el" href="namespaceGeographicLib.html" title="Namespace for GeographicLib. ">GeographicLib</a> can be overridden with the <em>environment variable</em> <code>GeographicLib_DIR</code> (which is the directory under which <a class="el" href="namespaceGeographicLib.html" title="Namespace for GeographicLib. ">GeographicLib</a> is installed);</li>
<li>finally, if you need to point to a particular build of <a class="el" href="namespaceGeographicLib.html" title="Namespace for GeographicLib. ">GeographicLib</a>, define the <em>cmake variable</em> <code>GeographicLib_DIR</code>, which specifies the absolute path of the directory containing the configuration file <code>geographiclib-config.cmake</code> (for debugging this may be the top-level <em>build</em> directory, as opposed to <em>installation</em> directory, for <a class="el" href="namespaceGeographicLib.html" title="Namespace for GeographicLib. ">GeographicLib</a>).</li>
</ul>
<p>Typically, specifying nothing or <code>CMAKE_PREFIX_PATH</code> suffices. However the two <code>GeographicLib_DIR</code> variables allow for a specific version to be chosen. On Windows systems (with Visual Studio), find_package will only find versions of <a class="el" href="namespaceGeographicLib.html" title="Namespace for GeographicLib. ">GeographicLib</a> built with the right version of the compiler. (If you used a non-cmake method of installing <a class="el" href="namespaceGeographicLib.html" title="Namespace for GeographicLib. ">GeographicLib</a>, you can try copying cmake/FindGeographicLib.cmake to somewhere in your <code>CMAKE_MODULE_PATH</code> in order for find_package to work. However, this method has not been thoroughly tested.)</p>
<p class="startli">If <a class="el" href="namespaceGeographicLib.html" title="Namespace for GeographicLib. ">GeographicLib</a> is not found, check the values of <code>GeographicLib_CONSIDERED_CONFIGS</code> and <code>GeographicLib_CONSIDERED_VERSIONS</code>; these list the configuration files and corresponding versions which were considered by find_package.</p>
<p class="startli">If <a class="el" href="namespaceGeographicLib.html" title="Namespace for GeographicLib. ">GeographicLib</a> is found, then the following cmake variables are set:</p><ul>
<li><code>GeographicLib_FOUND</code> = 1</li>
<li><code>GeographicLib_VERSION</code> = 1.49</li>
<li><code>GeographicLib_INCLUDE_DIRS</code></li>
<li><code>GeographicLib_LIBRARIES</code> = one of the following two:</li>
<li><code>GeographicLib_SHARED_LIBRARIES</code> = <a class="el" href="namespaceGeographicLib.html" title="Namespace for GeographicLib. ">GeographicLib</a></li>
<li><code>GeographicLib_STATIC_LIBRARIES</code> = GeographicLib_STATIC</li>
<li><code>GeographicLib_DEFINITIONS</code> = one of the following two:</li>
<li><code>GeographicLib_SHARED_DEFINITIONS</code> = -DGEOGRAPHICLIB_SHARED_LIB=1</li>
<li><code>GeographicLib_STATIC_DEFINITIONS</code> = -DGEOGRAPHICLIB_SHARED_LIB=0</li>
<li><code>GeographicLib_LIBRARY_DIRS</code></li>
<li><code>GeographicLib_BINARY_DIRS</code></li>
<li><code>GEOGRAPHICLIB_DATA</code> = value of this compile-time parameter</li>
</ul>
<p>Either of <code>GeographicLib_SHARED_LIBRARIES</code> or <code>GeographicLib_STATIC_LIBRARIES</code> may be empty, if that version of the library is unavailable. If you require a specific version, SHARED or STATIC, of the library, add a <code>COMPONENTS</code> clause to find_package, e.g., </p><pre class="fragment"> find_package (GeographicLib 1.34 REQUIRED COMPONENTS SHARED) </pre><p> causes only packages which include the shared library to be found. If the package includes both versions of the library, then <code>GeographicLib_LIBRARIES</code> and <code>GeographicLib_DEFINITIONS</code> are set to the shared versions, unless you include</p><pre class="fragment"> set (GeographicLib_USE_STATIC_LIBS ON) </pre><p> <em>before</em> the find_package command. You can check whether <code>GeographicLib_LIBRARIES</code> refers to the shared or static library with</p><pre class="fragment"> get_target_property(_LIBTYPE ${GeographicLib_LIBRARIES} TYPE) </pre><p> which results in <code>_LIBTYPE</code> being set to <code>SHARED_LIBRARY</code> or <code>STATIC_LIBRARY</code>. On Windows, cmake takes care of linking to the release or debug version of the library as appropriate. (This assumes that the Release and Debug versions of the libraries were built and installed. This is true for the Windows binary installer for <a class="el" href="namespaceGeographicLib.html" title="Namespace for GeographicLib. ">GeographicLib</a> version 1.34 and later.)</p>
</li>
<li>Here are the steps to compile and link your code using <a class="el" href="namespaceGeographicLib.html" title="Namespace for GeographicLib. ">GeographicLib</a> "manually".<ul>
<li>Tell the compiler where to find the header files. With g++ and with /usr/local specified as the installation directory, this is accomplished with<pre class="fragment"> g++ -c -g -O3 -I/usr/local/include testprogram.cpp</pre> With Visual Studio, specify the include directory in the IDE via, e.g., <pre class="fragment"> C/C++ -> General -> Additional Include Directories = C:\pkg-vc10\GeographicLib\include</pre></li>
<li>If using the shared (or static) library with Visual Studio, define the macro <code>GEOGRAPHICLIB_SHARED_LIB=1</code> (or <code>0</code>), e.g., <pre class="fragment"> C/C++ -> Preprocessor -> Preprocessor Definitions = GEOGRAPHICLIB_SHARED_LIB=1</pre> This is only needed for Windows systems when both shared and static libraries have been installed. (If you configure your package with cmake, this definition is added automatically.)</li>
<li>Tell the linker the name, Geographic, and location of the library. Using g++ as the linker, you would use<pre class="fragment"> g++ -g -o testprogram testprogram.o -L/usr/local/lib -lGeographic</pre> With Visual Studio, you supply this information in the IDE via, e.g.,<pre class="fragment"> Linker -> Input -> Additional Dependencies = Geographic-i.lib (for shared library)
Linker -> Input -> Additional Dependencies = Geographic.lib (for static library)
Linker -> General -> Additional Library Directories = C:\pkg-vc10\Geographic\lib</pre> Note that the library name is <b>Geographic</b> and not <a class="el" href="namespaceGeographicLib.html" title="Namespace for GeographicLib. ">GeographicLib</a>. For the Debug version of your program on Windows add "_d" to the library, e.g., Geographic_d-i.lib or Geographic_d.lib.</li>
<li>Tell the runtime environment where to find the shared library (assuming you compiled Geographic as a shared library). With g++, this is accomplished by modifying the link line above to read<pre class="fragment"> g++ -g -o testprogram testprogram.o -Wl,-rpath=/usr/local/lib \
-L/usr/local/lib -lGeographic</pre> (There are two other ways to specify the location of shared libraries at runtime: (1) define the environment variable <code>LD_LIBRARY_PATH</code> to be a colon-separated list of directories to search; (2) as <b>root</b>, specify /usr/local/lib as a directory searched by ldconfig(8).) On Windows, you need to ensure that Geographic.dll or Geographic_d.dll is in the same directory as your executable or else include the directory containing the dll in your <code>PATH</code>.</li>
<li>You can also use the pkg-config utility to specify compile and link flags. This requires that pkg-config be installed and that it's configured to search, e.g., /usr/local/lib/pgkconfig; if not, define the environment variable <code>PKG_CONFIG_PATH</code> to include this directory. The compile and link steps under Linux would typically be <pre class="fragment"> g++ -c -g -O3 `pkg-config --cflags geographiclib` testprogram.cpp
g++ -g -o testprogram testprogram.o `pkg-config --libs geographiclib`</pre></li>
</ul>
</li>
</ul>
<p>Here is a very simple test code, which uses the <a class="el" href="classGeographicLib_1_1Geodesic.html" title="Geodesic calculations ">Geodesic</a> class: </p><div class="fragment"><div class="line"><span class="comment">// Small example of using the GeographicLib::Geodesic class</span></div><div class="line"></div><div class="line"><span class="preprocessor">#include <iostream></span></div><div class="line"><span class="preprocessor">#include <<a class="code" href="Geodesic_8hpp.html">GeographicLib/Geodesic.hpp</a>></span></div><div class="line"></div><div class="line"><span class="keyword">using namespace </span><a class="code" href="namespacestd.html">std</a>;</div><div class="line"><span class="keyword">using namespace </span><a class="code" href="namespaceGeographicLib.html">GeographicLib</a>;</div><div class="line"></div><div class="line"><span class="keywordtype">int</span> <a class="code" href="CartConvert_8cpp.html#a814244b02f6701fd8ead246678bb3dae">main</a>() {</div><div class="line"> <span class="keyword">const</span> <a class="code" href="classGeographicLib_1_1Geodesic.html">Geodesic</a>& geod = <a class="code" href="classGeographicLib_1_1Geodesic.html#a479d30b83e1d2d32ad31c96b4df1543a">Geodesic::WGS84</a>();</div><div class="line"> <span class="comment">// Distance from JFK to LHR</span></div><div class="line"> <span class="keywordtype">double</span></div><div class="line"> lat1 = 40.6, lon1 = -73.8, <span class="comment">// JFK Airport</span></div><div class="line"> lat2 = 51.6, lon2 = -0.5; <span class="comment">// LHR Airport</span></div><div class="line"> <span class="keywordtype">double</span> s12;</div><div class="line"> geod.<a class="code" href="classGeographicLib_1_1Geodesic.html#afdca5eb7c37fa2fecf124aecd6c436fd">Inverse</a>(lat1, lon1, lat2, lon2, s12);</div><div class="line"> cout << s12 / 1000 << <span class="stringliteral">" km\n"</span>;</div><div class="line">}</div></div><!-- fragment --><p> This example is <code>examples/example-Geodesic-small.cpp</code>. If you compile, link, and run it according to the instructions above, it should print out</p><pre class="fragment"> 5551.76 km </pre><p> Here is a complete CMakeList.txt files you can use to build this test code using the installed library:</p><pre class="fragment">project (geodesictest)
cmake_minimum_required (VERSION 2.8.4)
find_package (GeographicLib 1.34 REQUIRED)
if (NOT MSVC)
set (CMAKE_INSTALL_RPATH_USE_LINK_PATH TRUE)
endif ()
if (CMAKE_VERSION VERSION_LESS 2.8.11)
include_directories (${GeographicLib_INCLUDE_DIRS})
add_definitions (${GeographicLib_DEFINITIONS})
endif ()
add_executable (${PROJECT_NAME} example-Geodesic-small.cpp)
target_link_libraries (${PROJECT_NAME} ${GeographicLib_LIBRARIES})
if (MSVC)
get_target_property (_LIBTYPE ${GeographicLib_LIBRARIES} TYPE)
if (_LIBTYPE STREQUAL "SHARED_LIBRARY")
# On Windows systems, copy the shared library to build directory
add_custom_command (TARGET ${PROJECT_NAME} POST_BUILD
COMMAND ${CMAKE_COMMAND} -E
copy $<TARGET_FILE:${GeographicLib_LIBRARIES}> ${CMAKE_CFG_INTDIR}
COMMENT "Copying shared library for GeographicLib")
endif ()
endif () </pre><p>The next steps are:</p><ul>
<li>Learn about and run the <a class="el" href="utilities.html">Utility programs</a>.</li>
<li>Read the section, <a class="el" href="organization.html">Code organization</a>, for an overview of the library.</li>
<li>Browse the <a href="annotated.html">Class List</a> for full documentation on the classes in the library.</li>
<li>Look at the example code in the examples directory. Each file provides a very simple standalone example of using one <a class="el" href="namespaceGeographicLib.html" title="Namespace for GeographicLib. ">GeographicLib</a> class. These are included in the descriptions of the classes.</li>
<li>Look at the source code for the utilities in the tools directory for more examples of using <a class="el" href="namespaceGeographicLib.html" title="Namespace for GeographicLib. ">GeographicLib</a> from C++ code, e.g., <a class="el" href="GeodesicProj_8cpp.html" title="Command line utility for geodesic projections. ">GeodesicProj.cpp</a> is a program to performing various geodesic projections.</li>
</ul>
<p>Here's a list of some of the abbreviations used here with links to the corresponding Wikipedia articles:</p><ul>
<li><a href="https://en.wikipedia.org/wiki/WGS84">WGS84</a>, World Geodetic System 1984.</li>
<li><a href="https://en.wikipedia.org/wiki/Universal_Transverse_Mercator_coordinate_system">UTM</a>, Universal Transverse Mercator coordinate system.</li>
<li><a href="https://en.wikipedia.org/wiki/Universal_Polar_Stereographic">UPS</a>, Universal Polar Stereographic coordinate system.</li>
<li><a href="https://en.wikipedia.org/wiki/Military_grid_reference_system">MGRS</a>, Military Grid Reference System.</li>
<li><a href="https://en.wikipedia.org/wiki/Geoid">EGM</a>, Earth Gravity Model.</li>
<li><a href="https://en.wikipedia.org/wiki/World_Magnetic_Model">WMM</a>, World Magnetic Model.</li>
<li><a href="https://en.wikipedia.org/wiki/IGRF">IGRF</a>, International Geomagnetic Reference Field.</li>
</ul>
<center> Back to <a class="el" href="install.html">Installing GeographicLib</a>. Forward to <a class="el" href="utilities.html">Utility programs</a>. Up to <a class="el" href="index.html#contents">Contents</a>. </center> </div></div><!-- contents -->
<!-- start footer part -->
<hr class="footer"/><address class="footer"><small>
Generated by  <a href="http://www.doxygen.org/index.html">
<img class="footer" src="doxygen.png" alt="doxygen"/>
</a> 1.8.13
</small></address>
</body>
</html>
|