Discussion of readme documentation and packaged scripts.

[sequoia-hope]

Following up to #33

Thanks for the reply! I think there has been a slight misunderstanding. I do have some years of python experience, both professionally at Google and as the developer of a robot stack I wrote in python myself.

The issue I had is that after installation I was unable to run the command "gnssserver" as it is not found. I assume that gnsserver is distributed as a "command line script" and packaged with the module:
https://python-packaging.readthedocs.io/en/latest/command-line-scripts.html

You're saying that normally you choose the location of the bin/scripts folder during installation, but I have only ever used python on linux and when I apt install python, no such selection is presented. So I am not familiar with such a folder. I did run "which python3" which returns /usr/bin, but there is no "scripts" folder in /usr/bin, and there are not python subfolders in /usr/bin either. So I still do not know where this scripts folder is.

Is this scripts folder something that is obvious on windows or mac? I've just never heard of it, and as I am not a beginner by any means I thought perhaps the documentation could be improved and I wanted to provide feedback.

However I may have made some incorrect assumptions. What has actually happened is that I followed the installation instructions, installed the code with pip, and then when I ran the command "gnssserver" I got the error "command not found". Is that expected? Or should this command have been placed in my path during installation? My concern is that perhaps there is a packaging issue. The workaround I found was to run the module directly, but your instructions suggest I should be able to just run "gnssserver", which failed for me after following the installation instructions.

Thanks!

[semuadmin]

Hi @tlalexander

So there are essentially three ways in which a Python application package can be executed:

(in the following examples, typing python3 -m pip is equivalent to typing pip3 - you can normally use either)

1) Individual module:

• Individual modules can be executed with python3 mymodule.py. This is fine for very simple cases.

2) -m switch; site-packages:

• In practice, most real-world Python application packages comprise multiple modules. If these modules are placed in a single packagename folder, traditionally alongside a specially-named __init__.py module, they can be executed using the -m switch:

ubuntu@primary:~$ python3 -m packagename

• If you install a Python application package using the pip package manager (e.g. python3 -m pip install pygnssutils), the folder containing the modules will be automatically installed in the user's site-packages directory. You can always find the location of this directory by typing python3 -m pip show packagename - look for the 'Location:' entry:

ubuntu@primary:~$ python3 -m pip show pygnssutils

Name: pygnssutils
Version: 1.0.10
Summary: GNSS Command Line Utilities
Home-page: 
Author: 
Author-email: semuadmin <semuadmin@semuconsulting.com>
License: BSD 3-Clause License ("BSD License 2.0", "Revised BSD License", "New BSD License", or "Modified BSD License"     
...
Location: /home/ubuntu/.local/lib/python3.10/site-packages
Requires: paho-mqtt, pyserial, pyspartn, pyubx2

• In the example above, the site-packages location is /home/ubuntu/.local/lib/python3.10/site-packages, but your location may be different.

3) Executable script:

• Optionally, developers can also configure the package installation procedure (e.g. setup.py or, more recently, pyproject.toml) to create an executable script which is placed in the user's standard binary executable folder ('bin', or 'script' on Windows).
  This allows the user to run the package from the command line as though it was a standard executable:

ubuntu@primary:~$ gnssserver -h

• NOTE!!!: When you install the package using pip, the installation procedure will output the location of this bin/script folder and it will even give you an explicit warning if this folder is not currently in your PATH:

ubuntu@primary:~$ python3 -m pip install pygnssutils
...
...
Installing collected packages: paho-mqtt, pyrtcm, pynmeagps, pycparser, pyubx2, cffi, cryptography, pyspartn, pygnssutils
  WARNING: The scripts gnssdump, gnssmqttclient, gnssntripclient, gnssserver, ubxload, ubxsave and ubxsetrate are installed in '/home/ubuntu/.local/bin' which is not on PATH.
  Consider adding this directory to PATH or, if you prefer to suppress this warning, use --no-warn-script-location.
Successfully installed cffi-1.15.1 cryptography-41.0.2 paho-mqtt-1.6.1 pycparser-2.21 pygnssutils-1.0.10 pynmeagps-1.0.26 pyrtcm-1.0.10 pyspartn-0.1.9 pyubx2-1.2.27

• In the example above, the bin folder is /home/ubuntu/.local/bin - but, again, this will depend on your specific environment.

• To add this folder to your PATH, you would typically add an entry to your ~/.bashrc or ~/.profile file, as follows (I use the zsh shell, so in my case it's ~/.zshrc or ~/.zprofile):

PATH="/home/ubuntu/.local/bin:${PATH}"
export PATH

(you will have to log off and on, or type something like source ~/.bashrc, for this change to take effect)

So, to summarise, if you take a careful look at the output when you install the package using pip, it will tell you the location of your site-packages and bin folders.

Hope this helps