# Getting or Building GPSBabel

## Downloading - the easy way.

GPSBabel is distributed "ready to run" on most common operating systems via the download page.

As GPSBabel runs on a wide variety of operating systems, be sure to visit the OS-Specific notes for additional information.

## Building from source.

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.

You can grab a release from the GPSBabel download page, but if you're going to be doing any development, you'll find that working from the GPSBabel Github repo is easier. Checkouts via Git, HTTPS, SSH, and Subversion are supported.

There are external requirements for bulding.

Qt

  Qt version 5.12 or newer is required for all builds. MacOS and Windows users can download binaries from Qt Downloads 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.

libusb 1.0

  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.

### Brief history of internals

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.

### Building with Qt Creator

Qt provides a lovely IDE (Integrated Development Environment) with an editor and debugger. Its use is strongly encouraged for those new to C++. Once you have Qt correctly installed, just opening the `CMakeLists.txt` from the File->Open menu in an already-running instance of Qt Creator 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.

A path of low resistance for some users is to use the CMakeLists.txt file from the command line. If you type cmake . in our working directory it will create a buildsystem with the default generator (Unix Makefiles or Visual Studio) which you can use for development.

### Building from the command line

Those familiar with the command line may be more comfortable using cmake from the command line. It is important to set the CMAKE_BUILD_TYPE when generating a build system with single configuration generators such as Unix Makefiles and Ninja. With multi-configuration generators such as Visual Studio and Xcode the build type is selected at build time instead of when generating the build system.

- To create a buildsystem using Ninja: `cmake -G Ninja -DCMAKE_BUILD_TYPE=Release .`
- To create a visual studio project that can be built with msbuild: `cmake -G "Visual Studio 17 2022" .`
- To create a Xcode project: `cmake -G Xcode .`

There are additional variables that can be defined cmake on the cmake command line to customize your build of GPSBabel.

GPSBABEL_WITH_LIBUSB = no|pkgconfig|system*|included*|custom

  note that libusb is NOT used on windows.

  no

    build without libusb-1.0. functionality will be limited.

  pkgconfig

    build with libusb-1.0 found by pkg-config.

  system

    build with libusb-1.0 found on system library path and under libusb-1.0 on system include path (default, linux, openbsd).

  included

    build with libusb-1.0 included with gpsbabel (default, macOS only).

  custom

    build with user supplied libusb-1.0. LIBS and INCLUDEPATH may need to be set with GPSBABEL_EXTRA_LINK_LIBRARIES and GPSBABEL_EXTRA_INCLUDE_DIRECTORIES.

GPSBABEL_WITH_SHAPELIB = no|pkgconfig|included*|custom
  no

    build without shapelib. functionality will be limited.

  pkgconfig

    build with shapelib found by pkg-config.

  included

    build with shapelib included with gpsbabel (default).

  custom

    build with user supplied shapelib. LIBS and INCLUDEPATH may need to be set with GPSBABEL_EXTRA_LINK_LIBRARIES and GPSBABEL_EXTRA_INCLUDE_DIRECTORIES.

GPSBABEL_WITH_ZLIB = no|pkgconfig|included*|custom
  no

    build without zlib. functionality will be limited.

  pkgconfig

    build with zlib found by pkg-config.

  included

    build with zlib included with gpsbabel (default).

  custom

    build with user supplied zlib. LIBS and INCLUDEPATH may need to be set with GPSBABEL_EXTRA_LINK_LIBRARIES and GPSBABEL_EXTRA_INCLUDE_DIRECTORIES.

GPSBABEL_MAPPREVIEW

  This options enables the map preview feature. With the feature disabled QtWebEngine and QtWebEngineWdigets are not used. Note that QtWebKit and QtWebKitWidgets are not longer supported.

GPSBABEL_EMBED_MAP

  Embed gmapbase.html for map preview. When using this option gmapbase.html will be compiled into the executable and does not need to be distributed.

GPSBABEL_EMBED_TRANSLATIONS

  Embed translations. When using this option the gpsbabel provided translations will be compiled into the executable and do not need to be distributed. The Qt provided translations still need to be distributed.

GPSBABEL_ENABLE_PCH

  Enable precompiled headers when building the target gpsbabel.

GPSBABEL_EXTRA_COMPILE_OPTIONS

  Extra compile options when building the target gpsbabel.

GPSBABEL_EXTRA_INCLUDE_DIRECTORIES

  Extra directories to include when building the target gpsbabel.

GPSBABEL_LINK_LIBRARIES

  Extra libraries to link when building the target gpsbabel.

GPSBABEL_LINK_OPTIONS

  Extra link options when building the target gpsbabel.

GPSBABEL_DOCVERSION

  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.

GPSBABEL_WEB

  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 "gpsbabel.org".

Additional targets are available for special purposes.

check

  Run the basic test suite.

check-vtesto

  Run valgrind memcheck.

gpsbabel

  Build the command line tool.

gpsbabel.hmtl

  Create the html documentation.

gpsbabel.org

  Create documentation for use on www.gpsbabel.org.

gpsbabel.pdf

  Create the pdf documentation.

package_app

  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. On windows an image will be created in the directory gui/package, and an installer will be created gui/Setup-x.y.z-Setup.exe.

### Runtime Dependencies:

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.