FFGo 1.12.9
A graphical launcher for the FlightGear flight simulator
Requires Python: >=3.4
Keywords: FlightGear, flightgear, flight, simulator, launcher, FFGo, FGo!

===============================================================================
FFGo
===============================================================================
A powerful graphical launcher for FlightGear
-------------------------------------------------------------------------------

This software is a fork of the excellent `FGo!`_ program written by
Robert “erobo” Leda, see HISTORY in the ``docs/README/README_en`` file
for details. It is a graphical launcher for `FlightGear`_, *i.e.,* a
program whose purpose is to allow easy assembling and running of an
``fgfs`` command line.

.. _FGo!: https://sites.google.com/site/erobosprojects/flightgear/add-ons/fgo
.. _FlightGear: https://www.flightgear.org/
.. _Python: https://www.python.org/
.. _CondConfigParser: https://frougon.net/projects/CondConfigParser/

FFGo is written in `Python`_ 3 and is based on `CondConfigParser`_,
which allows many interesting things as shown at:

  https://frougon.net/projects/FFGo/doc/README-conditional-config/


Screenshots
-----------

Screenshots are available at the `FFGo screenshots gallery page
<https://frougon.net/projects/FFGo/gallery/>`_.

.. _end-of-intro:

Home page
---------

FFGo's home page is located at:

  https://frougon.net/projects/FFGo/


Requirements
------------

FFGo requires the following software:

  - Operating system:

      * works on Unix-like systems (including GNU/Linux);
      * works on Windows;
      * should also work on macOS, but no one has reported about this
        so far.

  - `FlightGear`_;
  - `Python`_ 3.4 or later;
  - `Tkinter`_ (part of the Python standard library; often known as
    ``python3-tk`` or ``python-tk`` in Linux package managers); very old
    versions that don't have the Ttk widget set are not supported
    starting from FFGo 1.8.0 (Tk 8.5 should be recent enough);
  - `CondConfigParser`_.

In addition to these mandatory dependencies, FFGo will take advantage of
the following software if installed:

  - `Pillow`_ (a PIL fork that supports Python 3); the corresponding
    `Debian`_ package is ``python3-pil.imagetk``;
  - `GeographicLib`_\'s ``MagneticField`` program, distributed with the
    GeographicLib C++ library. In Debian, this program is part of the
    ``geographiclib-tools`` package, but requires specific dataset files
    to be installed in order to work properly (the
    ``geographiclib-get-magnetic`` script may be helpful to get them
    installed);
  - `GeographicLib`_\'s implementation for Python 3 (present in Debian
    testing and unstable under the name ``python3-geographiclib`` at the
    time of this writing).

If some of these optional components are not installed, or if for some
reason FFGo can't find them, some features will be disabled or work in
degraded mode. For instance, aircraft thumbnails won't be displayed if
the Pillow library isn't installed for the Python interpreter used to
run FFGo.

.. _Tkinter: https://docs.python.org/3/library/tkinter.html
.. _Pillow: https://python-pillow.github.io/
.. _GeographicLib: https://geographiclib.sourceforge.io/

Note:

  The home pages of FFGo's dependencies indicated here are current at
  the time of this writing (March 2025), but might change over time.


Download
--------

The best place to download FFGo from is the `FFGo page on PyPI`_.
Specifically, tarballs for any version are available in the `download
area`_ (also packages in `wheel format`_ since FFGo 1.12.6).
Alternatively, FFGo tarballs and wheel files can be downloaded `from
Florent Rougon's home page <https://frougon.net/projects/FFGo/dist/>`_.

.. _FFGo page on PyPI: https://pypi.org/project/FFGo/
.. _download area: https://pypi.org/project/FFGo/#files
.. _wheel format: https://www.python.org/dev/peps/pep-0427/


Git repository
--------------

FFGo is maintained in a `Git repository
<https://github.com/frougon/FFGo>`_ that can be cloned with::

  git clone https://github.com/frougon/FFGo.git


Debian packages
---------------

If you use Debian_, the first thing to do is, as usual, to check whether
there is an ``ffgo`` package in Debian proper. If not (which is the case
at the time of this writing), you can still install FFGo and its
dependencies with a simple::

  apt-get install ffgo

or

::

  aptitude install ffgo

etc., depending on your package manager of choice. For this to work, you
need to:

  - add the following lines to your ``/etc/apt/sources.list`` (given for
    Debian *unstable* here)::

      deb https://frougon.net/debian-ffgo unstable main
      deb-src https://frougon.net/debian-ffgo unstable main

    Packages for Debian *stable* are also available. If this is what you
    need, just replace *unstable* with *bookworm*, or whatever is the
    codename of the current Debian *stable* release, in these
    ``sources.list`` lines.

  - install `Florent Rougon's OpenPGP key`_ into the ``apt`` keyring (you
    can verify that this is the same key as served `by Github
    <https://github.com/frougon.gpg>`_; you may need to add a trailing
    newline to the latter to ensure a byte-for-byte match).

    .. _Florent Rougon's OpenPGP key: https://frougon.net/keys.html

    In order to tell ``apt`` to trust the key, you can save it for
    instance as ``/etc/apt/trusted.gpg.d/Florent_Rougon.asc``. This
    allows ``apt`` to authenticate the packages. If you don't do this,
    the installation should still be possible but with warnings and, of
    course, reduced security.

After these two steps, don't forget to run::

  apt-get update

(or ``aptitude update``, etc.), otherwise the package manager won't find
the packages available from the newly-added repository.

Notes:

  - The ``ffgo`` package recommends ``python3-pil.imagetk``. This
    package is available in Debian_. If you don't install it, FFGo will
    still work but you won't be able to see the aircraft thumbnails.

  - The ``deb-src`` line in ``/etc/apt/sources.list`` is useful if you
    want to be able to run::

      apt source ffgo

    or similar for its dependencies available from the repository given
    above (currently and for the foreseeable future, only
    CondConfigParser_). Otherwise, you may safely omit that line.

.. _Debian: https://www.debian.org/


Installation
------------

The detailed installation guide for FFGo is in the ``docs/INSTALL``
directory in any release tarball or zip file. In short:

  - If you are using Debian_, please see above.

  - FFGo may be run without installation, provided that all software
    requirements are installed.

  - Otherwise, FFGo can be installed in the standard way for Python
    packages, i.e. with::

      pip install FFGo

    If you have never used `pip`_ before, or if you need more details,
    read the guide in ``docs/INSTALL`` before running this command, and
    **don't invoke it as the superuser** unless you *really* know what
    you are doing!

    Besides FFGo, you may want to also install `Pillow`_ in order to see
    the aircraft thumbnails in FFGo. The presence of Pillow is detected
    at run time, therefore it doesn't matter if Pillow is installed
    before or after FFGo. Similarly, if you want to see magnetic
    variation and magnetic headings in addition to true headings, you'll
    need to install GeographicLib's ``MagneticField`` program. Finally,
    `GeographicLib`_\'s Python implementation is used for some geodetic
    calculations if installed for the Python interpreter used to run
    FFGo. Most computations can normally be done without this module,
    but it may be necessary in some particular cases (computation of
    distance and bearings for the shortest path between nearly antipodal
    points).

.. _pip: https://pypi.org/project/pip/

You may also find the installation instructions from `FFGo's page on the
FlightGear wiki`_ helpful. If you have a problem, you can always ask in
FFGo's thread on the FlightGear forum (see below in `Getting help,
discussing`_).

.. _FFGo's page on the FlightGear wiki: https://wiki.flightgear.org/FFGo


Running
-------

- If you've installed FFGo using a ready-made package (Linux or BSD
  distribution, etc.), just run ``ffgo`` from the command line, or
  choose FFGo in your desktop menu, etc.

- If you chose to run FFGo without installing it:

  From your file manager, you may click on the ``ffgo-launcher.py`` file
  in the top-level directory obtained after unpacking a release tarball
  or zip file. Alternatively, you can run it from a terminal with a
  command such as ``./ffgo-launcher.py`` or ``python3
  ffgo-launcher.py``. Just make sure you are running
  ``ffgo-launcher.py`` with the `Python`_ interpreter for which you
  installed the dependencies.

- Otherwise, if you installed FFGo with `pip`_:

  pip should have installed an ``ffgo`` executable in the directory it
  normally installs scripts into. This directory may be a ``Scripts``
  subdirectory of your Python installation, or a ``bin`` subdirectory of
  the virtual environment if you ran pip in a venv, etc. It depends on
  how you ran pip (inside or outside a venv, etc.). More details are
  given in ``docs/INSTALL``, and if this is not enough, please refer to
  the `pip`_ documentation.

  Note for Windows users:

    On Windows, `pip`_ will install an ``ffgo-noconsole.exe`` executable
    along with ``ffgo.exe`` (typically in ``C:\PythonXY\Scripts`` for a
    Python installation with version X.Y). The difference between these
    two files is that ``ffgo.exe`` opens a Windows terminal (“console”)
    containing all FFGo messages, while ``ffgo-noconsole.exe`` doesn't.

In any case, it is suggested that you skim through the documentation
available from the Help menu after you start FFGo. This will direct you
to the important first-time settings, hopefully give you useful tips,
etc.


Documentation
-------------

- Apart from this text (which corresponds to ``README.rst`` in a release
  tarball or zip file), FFGo's documentation can be found in the
  ``docs`` top-level directory after unpacking a release tarball or zip
  file. Once FFGo is installed, users should start by reading
  ``docs/README/README_<language code>`` (the language code is ``en``
  for English; this text is also accessible from FFGo's *Help* menu). In
  a second time, ``docs/README.conditional-config`` (`available online
  <https://frougon.net/projects/FFGo/doc/README-conditional-config/>`_)
  explains how to use the full power of FFGo's configuration system.

  If you got FFGo from the `Git repository`_ instead of a release tarball,
  part of the documentation is in source form only (written for
  `Sphinx`_). There is a special section in ``docs/INSTALL`` which
  explains how to build it in this situation [#]_. In any case, this
  documentation (for the latest FFGo release) is always `available online
  <https://frougon.net/projects/FFGo/doc/README-conditional-config/>`_.

  .. _Sphinx: https://www.sphinx-doc.org/

  .. [#] Basically, it boils down to installing a recent enough `Sphinx`_
         and running ``make doc`` from the top-level directory.

- There is also some `FFGo documentation on the FlightGear wiki`_, in
  particular screenshots illustrating most features, and maybe more
  practically-oriented installation instructions than those from
  ``docs/INSTALL/INSTALL_en`` (at the time of this writing).

  .. _FFGo documentation on the FlightGear wiki: https://wiki.flightgear.org/FFGo


Getting help, discussing
------------------------

At the time of this writing, there is a thread dedicated to FFGo on the
`FlightGear forum`_ at the following address:

  https://forum.flightgear.org/viewtopic.php?f=18&t=27054

.. _FlightGear forum: https://forum.flightgear.org/

This is where most discussions about FFGo take place. If you have a
question or a problem related to FFGo, this is a good place for asking.


Bugs
----

If you think you have found a bug, you can `file an issue on GitHub
<https://github.com/frougon/FFGo/issues>`_. If you are not sure that
what you are seeing is actually a bug, I suggest to discuss it instead
in the `FFGo forum thread`_. In either case, be very precise telling:

  - your operating system;

  - the versions of FFGo and its dependencies (Python, CondConfigParser,
    FlightGear... also Pillow and GeographicLib if you have them
    installed);

  - how you installed FFGo (with `pip`_, or a distribution package,
    or...);

  - the exact contents of the FFGo log file, which is
    ``~/.ffgo/Logs/FFGo.log`` on every operating system except Windows,
    and ``%APPDATA%/FFGo/Logs/FFGo.log`` on Windows.

    Note for Windows users:

      Since Windows seems to hide the ``%APPDATA%`` folder nowadays,
      Windows users may have to use their favorite search engine in
      order to find how to access this folder on their computer (hint:
      maybe `<https://www.youtube.com/watch?v=Xa0H8lND9Qs>`_
      and
      `<https://docs.microsoft.com/en-us/windows/uwp/design/app-settings/store-and-retrieve-app-data>`_
      can be helpful);

  - step-by-step instructions describing what you did to trigger the bug.

The FFGo log file normally contains the versions of all major
dependencies of FFGo, therefore the second instruction above should be a
no-brainer if you carried out the fourth one correctly. These versions
should also be available using Help → About in FFGo.

.. _FFGo forum thread: https://forum.flightgear.org/viewtopic.php?f=18&t=27054


License
-------

FFGo is distributed under the terms of the `WTFPL`_ version 2, dated
December 2004.

.. _WTFPL: https://www.wtfpl.net/


.. 
  # Local Variables:
  # coding: utf-8
  # fill-column: 72
  # End: