<chapter id="Getting_and_Building">
  <title>Getting or Building GPSBabel</title>
<sect1 id="Download">
<title>Downloading - the easy way.</title>
  <para>
GPSBabel is distributed "ready to run" on most common
operating systems via the
<ulink url="https://www.gpsbabel.org/download.html">download page</ulink>.
</para>
  <para> As GPSBabel runs on a wide variety of operating systems,
be sure to visit the
<ulink url="https://www.gpsbabel.org/osnotes.html">OS-Specific notes</ulink> for
additional information.
</para>
</sect1>
<sect1 id="Source">
<title>Building from source.</title>
  <para>
 For operating systems where no binary is provided, or if
you want the latest development version, you will have to build it from
source.  The code should be compilable on any system with
ISO C++17. It's tested on Ubuntu, macOS, and Windows.
Less frequently, someone will build on FreeBSD, OpenBSD, Solaris,
etc.  Clang/LLVM, GNU C++, and MSVC are regularly exercised via automation.
</para>
<para>
You can grab a release from the <ulink url="https://www.gpsbabel.org/download.html">GPSBabel download page</ulink>, but if you're going to be doing any development, you'll find that working from the <ulink url="https://github.com/gpsbabel/gpsbabel">GPSBabel Github repo</ulink> is easier. Checkouts via Git, HTTPS, SSH, and Subversion are supported.
</para>
<para>There are external requirements for bulding.</para>
<variablelist>
<varlistentry>
<term>
<ulink url="http://qt-project.org">Qt</ulink></term>
<listitem>
<para>
Qt version 5.12 or newer is required for all builds.  MacOS and Windows users can download
binaries from <ulink url="http://qt-project.org/downloads">Qt Downloads</ulink>
Fedora or CentOS users may need to 'dnf install qt5-qtbase-devel'.  When in doubt, 'dnf search qt' or 'dnf search qt5' may help you find the correct package name. Ubuntu users may need to 'apt-get install qt5-default'. Package names
and versions in Linux frequently change, so you may need to ask your Linux vendor
for help or look in tools/Docker* for inspiration for our automated builds that
use Docker.
  </para>
</listitem>
</varlistentry>

<varlistentry>
  <term>
   <ulink url="http://libusb.sourceforge.net">libusb 1.0</ulink>
  </term>
<listitem>
  <para>
is needed to communicate with use with older USB Garmins.
For macOS, we use an included copy.
Fedora users may need to 'yum install libusb-devel'.  Ubuntu users may
need to 'apt install libusb-dev' or look in tools/Docker* for inspiration
from our automated Docker builds.</para>
</listitem>
</varlistentry>

</variablelist>
<sect2 id="Internal_History">
<title>Brief history of internals</title>
  <para>
    Parts of GPSBabel have been public since 2002, with some of the original
    design and original code came from 2001. It was originally in C89, not C++
    and while we strongly encourage modern C++ code where we can use it, we've
    not gone back to those older formats - some of which we don't have
    the hardware to test and have fallen out of touch with original authors - and
    rewritten them in Modern C++ style. There are this void*'s everywhere, C String
    use, gross buffer abuse, and other things that look more like a C program from the 80's than a C++ program of modern date.  Code that's earned it's own wings can
    continue to fly with us as long as it passes the tests we have. We've additionally
    not enforced style rules as strongly across modules as we could have. Fixing
    both of these is a goal for us in 2020.
  </para>
</sect2>

<sect2 id="Qt">
  <title>Building with Qt Creator</title>
  <para>
    Qt provides a lovely IDE (Integrated Development Evironment) with an
    editor and debugger. Its use is strongly encouraged for those new to C++.
    Once you have Qt correctly installed, just opening either the <filename>
    GPSBabel.pro</filename> or <filename>gui/app.pro</filename> files from
    the OS file launcher (e.g. a double click in macOS while seeing it in Finder)
    or from a File->Open in an already-running instance of <ulink url="https://www.qt.io/development-tools">Qt Creator</ulink> is the fastest and easiest way for most
    people to get to development because it handles things like build dependencies
    changing and class and method compilation.
  </para>
  <para>A path of low resistance for some users is to use the Qt build files (*.pro)
    and compiler chain, but use the command line.  If you type <ulink url="https://doc.qt.io/qt-5/qmake-manual.html"> qmake</ulink> in our working
    directory, it will build a "native" Build file (Makefile, XCode, Visual Studio)
    which you can use for development.
  </para>
  </sect2>
<sect2 id="Configure">
  <title>Building with configure</title>
<para>
The GNU Build System (configure) is no longer supported and has
been removed.  For command line builds please use <link linkend="qmake">qmake</link>.
</para>
</sect2>
<sect2 id="cmake">
   <title>Building with cmake</title>
<para>
The use of cmake is experimental.  The implementation is not complete.  It is
untested by continuous integration.  It is not recommended for production use.
</para>
</sect2>
    <sect2 id="qmake">
      <title>Building with qmake</title>
      <para>
Those familiar with the command line may be more comfortable
using qmake from the command line. In most cases, the code is as simple to build as running:
</para>
      <para>
        <userinput>qmake &amp;&amp; make</userinput>
      </para>
      <para>
Two build methods are supported with MSVC tools.
</para>
      <simplelist>
        <member>
To create a visual studio project that can be built with msbuild:
<userinput>qmake -tp vc</userinput>
</member>
        <member>
To create a Makefile that can be built with nmake:
<userinput>qmake</userinput>
</member>
      </simplelist>
      <para>
</para>
      <para>There are additional flags that can be passed to qmake to
customize your build of GPSBabel.
</para>
      <variablelist>
        <varlistentry>
          <term>WITH_LIBUSB=no|pkgconfig|system*|included*|custom</term>
          <listitem>
            <para>
note that libusb is NOT used on windows.
</para>
            <variablelist>
              <varlistentry>
                <term>no</term>
                <listitem>
                  <para>build without libusb-1.0.  functionality will be limited.</para>
                </listitem>
              </varlistentry>
              <varlistentry>
                <term>pkgconfig</term>
                <listitem>
                  <para>build with libusb-1.0 found by pkg-config.</para>
                </listitem>
              </varlistentry>
              <varlistentry>
                <term>system</term>
                <listitem>
                  <para>build with libusb-1.0 found on system library path and under
libusb-1.0 on system include path (default, linux, openbsd).</para>
                </listitem>
              </varlistentry>
              <varlistentry>
                <term>included</term>
                <listitem>
                  <para>build with libusb-1.0 included with gpsbabel (default, macOS only).</para>
                </listitem>
              </varlistentry>
              <varlistentry>
                <term>custom</term>
                <listitem>
                  <para>build with user supplied libusb-1.0. LIBS and INCLUDEPATH may need to
be set, e.g. LIBS+=... INCLUDEPATH+=...</para>
                </listitem>
              </varlistentry>
            </variablelist>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term>WITH_SHAPELIB=no|pkgconfig|included*|custom</term>
          <listitem>
            <variablelist>
              <varlistentry>
                <term>no</term>
                <listitem>
                  <para>build without shapelib.  functionality will be limited.</para>
                </listitem>
              </varlistentry>
              <varlistentry>
                <term>pkgconfig</term>
                <listitem>
                  <para>build with shapelib found by pkg-config.</para>
                </listitem>
              </varlistentry>
              <varlistentry>
                <term>included</term>
                <listitem>
                  <para>build with shapelib included with gpsbabel (default).</para>
                </listitem>
              </varlistentry>
              <varlistentry>
                <term>custom</term>
                <listitem>
                  <para>build with user supplied shapelib. LIBS and INCLUDEPATH may need to
be set, e.g. LIBS+=... INCLUDEPATH+=...</para>
                </listitem>
              </varlistentry>
            </variablelist>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term>WITH_ZLIB=no|pkgconfig|included*|custom</term>
          <listitem>
            <variablelist>
              <varlistentry>
                <term>no</term>
                <listitem>
                  <para>build without zlib.  functionality will be limited.</para>
                </listitem>
              </varlistentry>
              <varlistentry>
                <term>pkgconfig</term>
                <listitem>
                  <para>build with zlib found by pkg-config.</para>
                </listitem>
              </varlistentry>
              <varlistentry>
                <term>included</term>
                <listitem>
                  <para>build with zlib included with gpsbabel (default).</para>
                </listitem>
              </varlistentry>
              <varlistentry>
                <term>custom</term>
                <listitem>
                  <para>build with user supplied zlib. LIBS and INCLUDEPATH may need to be
set, e.g. LIBS+=... INCLUDEPATH+=...</para>
                </listitem>
              </varlistentry>
            </variablelist>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term>CONFIG+=disable-mappreview</term>
          <listitem>
            <para>
This options disables the map preview feature.  With the feature disabled
QtWebEngine and QtWebEngineWdigets are not used. Note that QtWebKit and
QtWebKitWidgets are not longer supported.
</para>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term>DOCVERSION=...</term>
          <listitem>
            <para>
string appended to documentation location for www.gpsbabel.org.  The default
value is the version string, e.g. "1.7.0".  This is used by the gpsbabel.org
target, you are unlikely to need it unless you are maintaining
www.gpsbabel.org.
</para>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term>WEB=DIR</term>
          <listitem>
            <para>
Path where the documentation will be stored for www.gpsbabel.org.  This is
used by the gpsbabel.org target, you are unlikely to need it unless you are
maintaining www.gpsbabel.org.  The default location is "../babelweb"
</para>
          </listitem>
        </varlistentry>
      </variablelist>
      <para>
Additional makefile targets are available for special purposes.
</para>
      <variablelist>
        <varlistentry>
          <term>check</term>
          <listitem>
            <para>Run the basic test suite.</para>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term>check-vtesto</term>
          <listitem>
            <para>Run valgrind memcheck.</para>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term>gpsbabel</term>
          <listitem>
            <para>Build the command line tool.</para>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term>gpsbabel.hmtl</term>
          <listitem>
            <para>Create the html documentation.</para>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term>gpsbabel.org</term>
          <listitem>
            <para>Create documentation for use on www.gpsbabel.org.</para>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term>gpsbabel.pdf</term>
          <listitem>
            <para>Create the pdf documentation.</para>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term>gui</term>
          <listitem>
            <para>Build the graphical user interface.</para>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term>unix-gui</term>
          <listitem>
            <para>Build the graphical user interface and collect the components for
distribution.  On Linux the gpsbabel generated components will be under
gui/GPSBabelFE, any dynamically linked required libraries are not included.
On macOS an app bundle will be created at gui/GPSBabelFE.app and an apple disk
image will be created at gui/GPSBabelFE.dmg.</para>
          </listitem>
        </varlistentry>
      </variablelist>
    </sect2>
    <sect2 id="Runtime_Dependencies">
      <title>Runtime Dependencies:</title>
      <para>
On non-macOS unix builds by default we now compile in the gpsbabel generated
translation files, i.e. gpsbabelfe_*.qm, gpsbabel_*.qm, as well as
gmapbase.html.  When compiled in these files do not need to be distributed.
These are used by the GUI.  Additional translation files from Qt will also be
used if they are found.  They may be in a package such as qttranslations5-l10n
or qt5-qttranslations.
</para>
    </sect2>
</sect1>
</chapter>
