# JS8Spotter MIT License, Joe Lyman KF7MIX
# You should have received a copy of the source and license with the program

# Running JS8Spotter Under Linux


## Quickstart

I understand that many ham radio operators who use Linux are not actually comfortable
with it, nor do they have context or experience to understand everything that is
required for a python application source distribution such as this one. I hope that
these instructions will serve as a minimum to get things going, but feel free to
reach out via my email listed on QRZ.com if you need additional assistance.

As a quickstart, you should try:

1. Open a terminal emulator window and change directory to the same folder where you
   found this README.linux file
2. Make sure JS8Call is running, then start the JS8Spotter application with the 
   terminal command `python3 ./js8spotter.py`
3. Look for and resolve any errors that occur (see below)


## Note on System Variability

Linux systems vary wildly. This README.linux file can't possibly cover every
situation; in reality, it barely covers anything. You will need to take the very
limited concepts you find here and adapt them to your situation. 


## Which JS8Spotter Distribution Files to Use

Linux users may choose to download the full Windows installer package, but it
includes many files that are not needed on a Linux system. If you downloaded
and unpacked the Windows package, you may wish to remove it and switch to the
source version instead.


## Program Requirements

To run JS8Spotter on Linux you will need a working Python3 installation, and 
pip3 and a pkg manager. On a debian/Ubuntu type system, you might install python3
and pip with the command `sudo apt install python3 python3-pip`.

You'll also need a few additional python modules/libraries. The best way to see
what you will need to have is to open the js8spotter.py file and look at the
imports at the beginning of the file. Another way to determine which modules/
libraries you'll need is to simply run the program and see what it complains
about (this requires the ability to decode the python errors). Open a terminal 
and navigate to the js8spotter directory, then run the program with a command 
like 'python3 ./js8spotter.py'


If you see an error similar to this:

    No module named 'tkinter'

Try to resolve it by installing the missing item with ONE of these style commands:

    pip3 install tkinter
    sudo apt install python3-tk

If you see an error like:

    ImportError: cannot import name 'ImageTk' from 'PIL'

Try to resolve it by installing the missing item with ONE of these commands:

    pip3 install pillow
    sudo apt install python3-pil python3-pil.imagetk

For sound in Linux, install the TkSnack library with apt or pip.

After you install one missing item, run the program again, and work through any
missing items that come up. Most systems require only an additional library or
two, beyond what is installed when you install python3.


## Application Launcher

A script for creating a desktop launcher icon is included with this program.

A video with potentially applicable instructions may be found on my youtube channel.

I personally run JS8Spotter from a terminal window every time. You might prefer
something a little more GUI-centric. In many modern Linux systems you can create
a program launcher by dropping a .desktop file in your ~/Desktop folder. There
are other ways to do this, or to add the program to your system menus, etc. An
example .desktop file (say, ~/Desktop/JS8Spotter.desktop) is below, with my
own static directory variables:


[Desktop Entry]
Type=Application
Name=JS8Spotter
Comment=Companion Program for JS8Call
Path=/home/jlyman/src/js8spotter/
Exec=/home/jlyman/src/js8spotter/js8spotter.py
Icon=/home/jlyman/src/js8spotter/js8spotter.ico


## Python Script Executable

If you create a .desktop file, you'll need to set your script up to be executable.
On many systems, adding the line '#!/usr/bin/env python3' to the top of the file,
then setting it executable with `chmod a+x`, will do the trick. However, you might
keep your env binary elsewhere, or prefer not to set things world executable. So,
do whatever is right for you in this regard.


## More Help?

You perhaps have noticed that I'm taking a minimalist approach to the Linux (SRC)
release of this program and its configuration. I'm a fan of minimalism, it's one
of the reasons I love Linux. There are no plans for repo builds or packages; the
above is the plan. If you need more help than what is in here, email me via QRZ
and I'll see what I can do!

