Skip to content

INSTALLATION.md

Latest commit

 

History

History
292 lines (191 loc) · 17.2 KB

INSTALLATION.md

File metadata and controls

292 lines (191 loc) · 17.2 KB

PyGPSClient Installation

Basics | Prerequisites | User Privileges | Install with pip | Install with pipx | Install with script | Troubleshooting | License | Author Information

Some Basics on Python Installation

Experienced Python users can skip this section.

global vs venv

There are, in essence, two options available when installing Python applications like PyGPSClient using the standard pip installation manager:

  1. Install into the global system environment¹.
  2. Install into a dedicated virtual environment ('venv').

Though by no means mandatory, it is generally considered best practice to use a separate virtual environment for each application, as this allows you to:

  1. Install application-specific packages without messing up your global Python installation.
  2. Use different versions of the same package across applications.
  3. Keep your application dependencies clean and organized.

Some platforms (e.g. Ubuntu Linux and Homebrew-installed Python environments) enforce the use of virtual environments via a so-called 'Externally Managed Environment' constraint². Attempting to install a package into the global environment will result in an error: externally-managed-environment error.

¹ In practice, 'global' generally means the user's home environment. Installing into the platform's global system environment typically results in a Defaulting to user installation because normal site-packages is not writeable warning.

² Though not recommended, this constraint can generally be removed by simply deleting or renaming the file /usr/lib/python3.x/EXTERNALLY-MANAGED.

sdist vs wheel (bdist)

There are two file formats in common use for distributing Python packages:

  1. sdist (source distribution) - a platform-independent TAR compressed archive (.tar.gz) of the Python and any non-Python source code in raw form, including a special PKG-INFO file which holds the project metadata. Packages with 'extension modules', written in languages like C, C++ and Rust, need to be compiled into platform-dependent executable code at time of installation. This may in turn require certain external 'build dependencies' (files required for successful code compilation) to be pre-installed on the target platform.
  2. wheel (binary distribution or bdist) - a platform-dependent ZIP compressed archive (.whl) of the Python source and the compiled, executable code for any non-Python extension modules that need to be copied when installing the package (e.g. .so files on Linux, .dylib on MacOS or .dll on Windows).

By default, pip will look for wheel first, and only resort to using sdist where no wheel is available for the target platform.

For pure Python packages like PyGPSClient and its subsidiary GNSS utilities, which contain no non-Python extension modules, the differences between sdist and wheel distributions are to some extent academic - a single pygpsclient pygpsclient-*-none-any.whl package can be installed on any target architecture. The distinction is, however, relevant for some of PyGPSClient's optional dependencies (e.g. cryptography and rasterio) - see troubleshooting for further details.

site_packages and binaries directories

pip installs application source code and distribution metadata into a ../site_packages directory.

If the installation also entails one or more binary executables, these will be installed into a ../bin directory (or ..\Scripts on Windows). In the case of PyGPSClient, for example, pip installs a binary executable ../bin/pygpsclient (or ..\Scripts\pygpsclient.exe on Windows), which allows the application to be executed from the command line or standard application shortcut³.

The exact location of the site_packages and binary directories will depend on the platform and installation specifics. A virtual environment ('venv') will contain its own dedicated site_packages and binary directories e.g. ../venv/bin and ../venv/lib/python3.13/site_packages.

NB To facilitate operation, it is highly recommended that these directories are included in your system's PATH environment variable.

³ The pygpsclient executable does not actually contain compiled Python source code - it is simply an executable form of the standard python -m pygpsclient command.

Prerequisites

All platforms

In the following, python3 & pip refer to the Python 3 executables. You may need to substitute python for python3, depending on your particular environment (on Windows it's generally python).

  • Graphical User Interface (window system / manager)
  • Python >= 3.10⁴
  • Tk (tkinter) >= 8.6⁵ (tkinter is a commonly used library for developing Graphical User Interfaces (GUI) in Python)
  • Screen resolution >= 640 x 480 (VGA); Ideally 1920 x 1080, though at lower screen resolutions (<= 1024 width), top level dialogs will be resizable and scrollable.

NB It is highly recommended to use the latest official Python.org installation package for your platform, rather than any pre-installed version.

NB It is highly recommended that the Python 3 binaries (../bin or ..\Scripts) directory is included in your PATH (most standard Python 3 installation packages will do this automatically if you select the 'Add to PATH' option during installation).

⁴ PyGPSClient's optional spatialite database recording facility is dependent upon the following:

  • The Python environment must support the loading of sqlite3 extensions i.e. it must have been compiled with the --enable-loadable-sqlite-extensions option. This is true by default for most Windows and Linux platforms but NOT for most MacOS platforms.
  • The mod_spatialite module (.so, .dll or .dylib) must be installed and in the PATH (or LD_LIBRARY_PATH on Linux).

Windows 10 or later

Normally installs without any additional steps.

MacOS 13 or later

⁵ The version of Python supplied with some older Apple MacOS platforms includes a deprecated version of tkinter (8.5). Use an official Python.org installation package instead.

NB: Python does NOT normally require Homebrew or MacPorts to be installed on MacOS. The Python organisation provides serviceable 64-bit universal installation packages for all current and legacy versions of Python, including release candidates.

However, if you wish to install Python using Homebrew to take advantage of certain non-default configurations (e.g. support for sqlite3 extensions), use the python-tk formula rather than python, e.g.

brew install python-tk@3.13 libspatialite

Note also that the Homebrew formulae for python-tk>=3.12 include the latest tkinter 9.0 (rather than 8.6). There are known compatibility issues between tkinter 9.0 and other Python packages (e.g. ImageTk) on some platform configurations, which may result in PyGPSClient being unable to load. If you encounter these issues, consider using brew install python-tk@3.11 or an official Python.org installation package instead.

Note that on MacOS, serial ports may appear as /dev/tty* or /dev/cu*. To understand the differences between the two, see here.

Linux (including Raspberry Pi OS)

Some older Linux distributions may not include all the necessary pip, venv, tkinter, Pillow or spatialite libraries by default e.g. for Debian-based distibutions, a combination of some or all of the following:

sudo apt install python3-pip python3-tk python3-pil python3-venv python3-pil.imagetk libjpeg-dev zlib1g-dev tk-dev libspatialite

For Arch-based distributions:

sudo pacman -S tk libspatialite

⁴ Support for the sqlite3 mod_spatialite extension may require a custom version of Python to be compiled from source if a suitable version is not available from any of the distribution's repos.

User Privileges

To access the serial port (/dev/tty*) on most Linux platforms, you will need to be a member of whichever group or "Gid" the /dev/tty* device belongs to. Failure to do this will typically result in an error [Errno 13] could not open port /dev/ttyACM0 [Errno 13] permission denied /dev/ttyACM0

To check and set the necessary group permissions (substitute your particular serial port for ttyACM0):

stat /dev/ttyACM0 | grep Gid

Access: (0660/crw-rw----) Uid: ( 0/ root) Gid: ( 20/ dialout) <-- group in this case is dialout

Add your user to this group using usermod (you will need to log out and in again for this to take effect):

sudo usermod -aG dialout myuser

For Debian-based platforms, the group is normally dialout or tty; on Arch-based platforms it is normally uucp.

Other than this, no special privileges are required.

Install using pip

The recommended way to install the latest version of PyGPSClient is with pip:

python3 -m pip install --upgrade pygpsclient

It is generally considered best practice to install into a virtual environment:

python3 -m venv pygpsclient
source pygpsclient/bin/activate # (or .\pygpsclient\Scripts\activate on Windows)
python3 -m pip install --upgrade pygpsclient
pygpsclient

NB: It is recommended to use the form python3 -m pip install (or less ambiguously python3.*, where * is the Python minor version e.g. python3.13) rather than simply pip3 install, particularly if you have multiple Python environments on your platform.

To deactivate the virtual environment:

deactivate

To reactivate and run from the virtual environment:

source pygpsclient/bin/activate # (or .\pygpsclient\Scripts\activate on Windows)
pygpsclient

To upgrade PyGPSClient to the latest version from the virtual environment:

source pygpsclient/bin/activate # (or .\pygpsclient\Scripts\activate on Windows)
python3 -m pip install --upgrade pygpsclient

The pip installation process places an executable file in the Python binaries folder (../bin/pygpsclient on Linux & MacOS, ..\Scripts\pygpsclient.exe on Windows). The PyGPSClient application may be started by double-clicking on this executable file from your file manager or, if the binaries folder is in your PATH⁵, by opening a terminal and typing (all lowercase):

pygpsclient

pygpsclient accepts optional command line arguments for a variety of configurable parameters. These will override any saved configuration file settings. Type the following for help:

pygpsclient -h

⁵ NB: If the Python 3 binaries folder is not in your PATH, you will need to add the fully-qualified path to the pygpsclient executable in the command above.

Tip: The location of the relevant binaries folder(s) can usually be found by executing the following commands:

python3 -c "import os,sysconfig;print(sysconfig.get_path('scripts'))"
python3 -c "import os,sysconfig;print(sysconfig.get_path('scripts',f'{os.name}_user'))"

NB The pip installation process does not automatically create a desktop application launcher, but this can be done manually - see APPLAUNCH.

Optional dependencies

The following Python packages are optional:

  1. rasterio - required for automated extents detection in the PyGPSClient Import Custom Map facility.
  2. cryptography - required to decrypt SPARTN messages in the PyGPSClient console.
python3 -m pip install rasterio
python3 -m pip install cryptography

... or, on some Linux distributions:

sudo apt install python3-rasterio

(see troubleshooting below for potential issues on some Linux / ARM platforms)

Install using pipx

pipx is essentially a wrapper around the standard pip command which provides simplified syntax for virtual environment installation:

python3 -m pip install pipx # if not already installed
pipx ensurepath # ensures venv binaries folder is in PATH
pipx install pygpsclient

pipx will typically create a virtual environment in the user's home folder e.g. /home/user/.local/share/pipx/venvs/pygpsclient or C:\Users\user\pipx\venvs\pygpsclient>.

Install using installation script

The following scripts require sudo/admin privileges and will prompt for the sudo password.

Debian Linux

An installation shell script is available for use on most vanilla 64-bit Debian-based desktop environments, including Raspberry Pi OS Trixie and Ubuntu LTS. The script...

  • Installs all necessary Python system libraries.
  • Installs PyGPSClient into a virtual environment in the user's home directory and adds this environment to the user's PATH.
  • Adds user to the relevant /dev/tty* group.
  • Creates a desktop application launcher which can be accessed from the Applications..Other menu.
wget https://raw.githubusercontent.com/semuconsulting/PyGPSClient/refs/heads/master/examples/pygpsclient_debian_install.sh
# or use curl -O ... if you prefer
chmod +x pygpsclient_debian_install.sh
./pygpsclient_debian_install.sh

Arch Linux

A similar installation shell script is available for use on most vanilla 64-bit Arch-based desktop environments (e.g. Xfce / LightDM):

curl -O https://raw.githubusercontent.com/semuconsulting/PyGPSClient/refs/heads/master/examples/pygpsclient_arch_install.sh
# or use wget ... if you prefer
chmod +x pygpsclient_arch_install.sh
./pygpsclient_arch_install.sh

MacOS

A similar installation shell script is available for MacOS 13 or later running a ZSH shell (Homebrew or MacPorts are NOT required). This will also install the latest official version of Python 3 with tkinter 8.6:

curl -O https://raw.githubusercontent.com/semuconsulting/PyGPSClient/refs/heads/master/examples/pygpsclient_macos_install.sh
chmod +x pygpsclient_macos_install.sh
./pygpsclient_macos_install.sh

Windows

TBC. Anyone conversant with PowerShell is welcome to contribute an equivalent installation script for Windows 11.

Troubleshooting

  1. [Errno 13] could not open port /dev/tty**** [Errno 13] permission denied /dev/tty**** error on Linux when attempting to access serial port. Refer to User Privileges.

  2. The optional rasterio package is only available as an sdist on some Linux / ARM platforms and the consequent GDAL build and configuration requirements may be problematic e.g. WARNING:root:Failed to get options via gdal-config. Refer to rasterio installation and GDAL installation for assistance but - be warned - the process is not for the faint-hearted.

    In practice, rasterio is only required for automatic extents detection in PyGPSClient's Import Custom Map facility. As a workaround, extents can be entered manually, or you can try importing maps on a different platform and then copy-and-paste the relevant usermaps_l extents configuration to the target platform.

  3. The optional cryptography package is only available as an sdist on some 32-bit Linux / ARM platforms and the consequent OpenSSL build requirements may be problematic e.g. Building wheel for cryptography (PEP 517): finished with status 'error'. Refer to cryptography installation for assistance.

License

License

BSD 3-Clause License

Copyright © 2020, semuadmin (Steve Smith) All rights reserved.

Application icons from iconmonstr ©.

Author Information

semuadmin@semuconsulting.com