README.CYGWIN

November 2017 Update

This document offers a method of running Xastir on Windows using
the Cygwin environment.  Cygwin is a large collection of GNU and
Open Source tools which provide functionality similar to a Linux
distribution on Windows.

Microsoft now offers their own Linux solution, using an Ubuntu
Linux framework that runs under Windows.  However, you must be
running a 64 bit version of Windows 10 to use the Microsoft option.
More information may be found in the Xastir Wiki at:

http://xastir.org/index.php/HowTo:Win10

------------------------------------
Installing Xastir on Windows/Cygwin:
------------------------------------

These directions were most recently validated on Windows 10, both 32
and 64 bit, with Cygwin version 2.882.

SPACES IN FILENAMES/USERNAMES:  Cygwin specifically, and Unix boxes in
general, don't much like spaces in filenames, directories, or login
names.  Any of these may cause you headaches while playing with Cygwin.
Create a new login that doesn't have spaces and log in as that user
before installing Cygwin, and whenever you intend to run Cygwin/Xastir.
It's very likely that Xastir won't work for you if you use a login that
has spaces embedded in it.  For additional info, see this link:

   https://cygwin.com/faq/faq.html#faq.using.filename-spaces

The following steps direct you through installing Cygwin, Xastir, and
a few optional map libraries that Xastir can use.  Note that in most
of the places below where the directions state to type commands, this
must be done from within a Cygwin BASH shell, not a DOS window.
Where you are asked to edit files, it's best to use Wordpad instead
of Notepad, as Notepad doesn't do nice things to Unix-format files.

Cygwin now allows you to have Xwindows apps and Windows apps all on
the screen and visible at the same time!  The instructions here set
it up in that manner, so you can have Xastir as just another app on
your Windows desktop.

Please subscribe to the "xastir" mailing list at "http://xastir.org".
There are lots of helpful people there that can aid you in
installing/running Xastir.  You must be subscribed in order to post
messages there.

[ ] Step 1)  Install Cygwin, a free download.

[ ] Step 1a) Go to https://cygwin.com/install.html with your web browser.
Choose the 64 bit or 32 bit version as appropriate for your Windows
operating system.

This will download the Cygwin network installer program onto your
computer.  Remember where you decide to put this program.  I put
mine in my user "Downloads" folder.

Note: It will be beneficial to re-run the Cygwin network installer
from time to time in order to keep Cygwin up to date.  Each time you run
it you'll update any packages that have been changed since you last ran
it.

[ ] Step 1b)  Find the "setup-x86.exe" program (32 bit) or the
"setup-x86_64" (64 bit) program.  Make note of which version you are
using.

Open a Windows Command Prompt as the Administrator and change directory
to the directory where you just saved the setup program.

If you have setup-x86.exe (32 bit), run this command to download
and install the needed Cygwin components:

setup-x86.exe --quiet-mode --packages autoconf,automake,binutils,^
db,font-util,gcc-core,git,GraphicsMagick,gv,libcurl-devel,libdb-devel,^
libgeotiff,libgeotiff-devel,libjasper-devel,libjbig-devel,^
liblcms2-devel,libpcre-devel,libshp-devel,libtiff-devel,libwebp-devel,^
libwmf-devel,libxml2-devel,libGraphicsMagick-devel,libX11-devel,^
libXext-devel,libXm-devel,make,nano,sox,unzip,wget,xfontsel,xinit,^
xorg-x11-fonts-Type1,xorg-x11-fonts-dpi100,libbz2-devel,libproj-devel

If you have setup-x86_64.exe (64 bit), run this command to
download and install the needed Cygwin components:

setup-x86_64.exe --quiet-mode --packages autoconf,automake,binutils,^
db,font-util,gcc-core,git,GraphicsMagick,gv,libcurl-devel,libdb-devel,^
libgeotiff,libgeotiff-devel,libjasper-devel,libjbig-devel,^
liblcms2-devel,libpcre-devel,libshp-devel,libtiff-devel,libwebp-devel,^
libwmf-devel,libxml2-devel,libGraphicsMagick-devel,libX11-devel,^
libXext-devel,libXm-devel,make,nano,sox,unzip,wget,xfontsel,xinit,^
xorg-x11-fonts-Type1,xorg-x11-fonts-dpi100,libbz2-devel,libproj-devel

[ ] Step 1c) Choose a Download Site and then click Next.

[ ] Step 1d) The Select Packages screen will display.  You don't have
to actually select any, the right packages have been selected for you.
But, if you wish, you can review the selection and make changes if you
know what you are doing.  Click Next and the Resolving Dependencies
screen will display.

[ ] Step 1e)  Click Next and the packages will get downloaded and
installed.  Repeat the above if you have network difficulties, until
the install succeeds completely.
   
 
In addition to the base packages, the following packages required to
compile and run Xastir, along with their dependencies, will be installed.

[ ] autoconf
[ ] automake
[ ] binutils
[ ] db
[ ] font-util
[ ] gcc-core
[ ] git
[ ] GraphicsMagick
[ ] gv
[ ] gzip
[ ] libbz2-devel
[ ] libcurl-devel
[ ] libdb-devel
[ ] libgeotiff 
[ ] libgeotiff-devel
[ ] libjasper-devel
[ ] libjbig-devel
[ ] liblcms2-devel
[ ] libpcre-devel
[ ] libproj-devel
[ ] libshp-devel
[ ] libtiff-devel
[ ] libwebp-devel
[ ] libwmf-devel
[ ] libxml2-devel
[ ] libGraphicsMagick-devel
[ ] libX11-devel
[ ] libXext-devel
[ ] libXm-devel
[ ] make
[ ] nano (a windows-style text editor, optional)
[ ] patch
[ ] sox
[ ] unzip
[ ] wget (Optional: Can use libcurl instead)
[ ] xfontsel
[ ] xinit
[ ] xorg-x11-fonts-Type1
[ ] xorg-x11-fonts-dpi100


[ ] Step 1f) You may receive a Postinstall script errors screen.
It is not necessarily an issue, but you are advised to check the
contents of /cygwin/var/log/setup.log.full or
/cygwin64/var/log/setup.log.full.  Click Next to proceed.

[ ] Step 1g)  At the end of the install it'll ask you if you wish to
create desktop icons and menu entries.  Definitely select these!  It
doesn't mean that Cygwin will start automatically each time you
reboot your computer or login (it doesn't start automatically).  It
_does_ mean that you'll have an icon to click on manually to get
things going.

This will create a Black/Green Cygwin icon on the desktop and a menu
entry so that you can start Cygwin through the menu system as well.

[ ] Step 1h) Click "Finish".  Cygwin is now installed.  One more
pop-up informs you Cygwin has been installed.  Sometimes this last
dialog gets hidden behind other windows, and it does seem to need OK
clicked to complete the installation.  Click the OK button on that
last dialog to _really_ complete the installation.  The Command
Prompt in the window will not return.  When it prints "Ending Cygwin
install" it is done.  You can press enter and the prompt will
reappear.

The Black/Green Cygwin icon will start up a BASH window, without
starting up Xwindows.  Think of it as being similar to a DOS window,
but with a lot more power.  It understands Unix commands though, not
DOS commands.

[ ] Note:  I've had the Cygwin network install fail before during
the downloading stage without informing me in any recognizable
manner.  You might want to re-do step 1 to make sure nothing
further gets downloaded/installed.  Once you get to that point, Step
1 is complete.

[ ] Step 2)  Start the X Server:

Click on the Windows menu icon or press the Windows button.  Look for
the Cygwin-X program group and click on the XWin Server.  It will create
a green "X" icon in the system tray.

Right-click on green "X" icon in the system tray.  Select Systems Tools,
and then Cygwin Terminal.

[ ] Step 3)  Test Cygwin and create startup shortcuts:

You should get a shell window that looks very much like a DOS window.
It's a BASH shell window and understands Unix commands instead of DOS
commands.

Once you've gotten to this stage, you now have Cygwin and Xwindows
installed and operational.  Next we go after Xastir itself.

[ ] Step 4)  Download Xastir sources.  Use the Cygwin Terminal window
that you just started.  Type the three lines below into the shell exactly
as shown.

  mkdir git
  cd git
  git clone http://github.com/Xastir/Xastir

The end result when it succeeds will be a new directory "~\git\Xastir\"
which contains all of the Xastir source code.  You can type "ls Xastir"
(that's lower-case LS) to see the file listing.

Side Note:  Here's the coolest thing about Git:  Once you've done
this initial source-code download, you'll never have to do the whole
Xastir download again.  You'll just go into the "git/xastir"
directory and type "git pull", which will snag just the _changes_
to the files since you last updated, and is very fast.  Compile and
install at that point and you'll be running the latest developer's
version in just a few minutes!  It's very easy to keep up with the
developers this way.

[ ] Step 5)  Configure/compile/install Xastir.  Type these commands
into the BASH shell, waiting until each one completes before typing
the next command:

    cd ~/git/Xastir
    ./bootstrap.sh
    mkdir -p build
    cd build
    ../configure
    make
    make install-strip

NOTE:  You'll probably want to run the configure step from an xterm
window with the X11 server running of course.  If you do this from a
non-X11 window then the configure test for "gv" will fail, as "gv"
requires an X11 server even when asking it for it's version number.
Without "gv" support you won't be able to print from Xastir.

Once you get through the above commands, Xastir is compiled and
installed on your system, with minimal map support.  Later sections
of this document detail adding additional map libraries in order to
give you access to the full mapping capability of Xastir.

---------------------------------------------------------------------

[ ] Step 6)  Actually run the darn thing:

Let's start from scratch to make sure it all works.  Close any
Cygwin/BASH windows you may have.

Click on the shortcut you created to start Xwindows.

From the resulting BASH window, type "xastir &".  Xastir should
start up shortly.

As built, using this documentation, the following map types are
supported.

Built-in map types:
      gnis   USGS GNIS Datapoints
       pop   USGS GNIS Datapoints w/population
       map   APRSdos Maps
       map   WinAPRS/MacAPRS/X-APRS Maps

Support for these additional map types has been compiled in:
       geo   Image Map (ImageMagick/GraphicsMagick library, many
                        formats allowed)
       geo   URL (Internet maps via libcurl library)
       geo   URL (OpenStreetMaps via libcurl library
                  Copyright OpenStreetMap and contributors, CC-BY-SA)
       shp   ESRI Shapefile Maps (Shapelib library)
       tif   USGS DRG Geotiff Topographic Maps (libgeotiff/libproj)
       xpm   X Pixmap Maps (XPM library)

The README.MAPS file has instructions for where to get maps and where
to put them under the Xastir hierarchy.

If you have any WinAPRS, DosAPRS, or PocketAPRS maps, now is a good
time to place them in the /cygwin/usr/local/share/xastir/maps folder
(or a subdirectory of it).  You can also use "*.geo" files and the
associated image files with Xastir.  You may place them in this
directory (or a subdirectory of it) as well.

FILESYSTEM PATHS (WINDOWS VS CYGWIN):

From Windows, just prefix all paths with "/cygwin" or "/cygwin64" as
appropriate.  For instance, maps go into /cgwin/usr/local/share/xastir/maps
instead of /usr/local/share/xastir/maps.  Xastir will continue to see
them as "/usr/local/share/xastir/maps" though from inside Cygwin.  It kind
of looks like a miniature Unix box from inside Cygwin.

LANGUAGE OPTIONS:

To set a new language or change the language current choice, use
this command line instead from inside an Xterm:

     xastir -l <language>

Current choices are:

    Dutch English French German Italian Portuguese Spanish
    ElmerFudd MuppetsChef OldeEnglish PigLatin PirateEnglish

This option will be stored in the users config file for the next
time Xastir is run. On new installs Xastir will default to English
until you use this command line option once.

CYGWIN vs LINUX/UNIX:

Another difference with Cygwin as opposed to Unix-like operating
systems:  You can't do the make install portion if Xastir is up and
running.  You have to kill Xastir first before you do "make install"
or "make install-strip".  Otherwise the newly compiled Xastir won't
replace the old one.

Another interesting "feature" of Cygwin/Xwindows is that some of the
modifier keys like ScrollLock/CapsLock/NumLock must be pressed while
that X-window is the active foreground window.  If not, the event
can be missed, and Xwindows can get out of sync with the actual
state of the key.  This doesn't appear to be an Xastir-specific
problem, but a Cygwin/Xwindow problem.  With just a BASH shell under
Cygwin (not involving Xwindows), the problem doesn't appear to
happen.  Just inside Xwindows on Cygwin.

When specifying serial ports to use with Xastir,

    "COM1" is called "/dev/ttyS0" in Cygwin (and Linux)
    "COM2" is called "/dev/ttyS1" in Cygwin (and Linux)

Note the capital 'S'.

OPTIONAL

Please see the INSTALL file and the Help menu in Xastir itself
for additional information not mentioned in this document.

Additional info can be found on the cygwin web-site:

    http://www.cygwin.com

or the Cygwin/XFree86 web-site:

    http://cygwin.com/xfree/


Keeping up-to-date:

Once a week or once a month, run the Cygwin network installer
program (setup-x86.exe or setup-x86_64.exe).  After it finishes,
open a Cygwin terminal window and type these commands to update the
Xastir source code:

    cd ~/git/xastir
    git pull

Every once in a while Windows will refuse to allow you to
delete/rename one of the files.  The only way I've found to get
around this problem is to reboot.  I sometimes see this when trying
to do a "git pull", and Windows won't allow one or more files to get
updated.

You can now repeat step 5 to update Xastir.

-------------------------------------------
OPTIONAL:  ADDING ADDITIONAL MAP LIBRARIES:
-------------------------------------------

These additional Xastir libraries have been tested on Cygwin:

    ImageMagick (no need to use if using GraphicsMagick)
    Festival

Anyone testing additional libraries is encouraged to share their
findings on the Xastir mailing lists (you must be subscribed in
order to post messages there).  The libraries which have _not_ been
made to work yet on Cygwin are:

    AX25
    GPSMan/gpsmanshp

The AX25 libraries will probably never work, as they are for Linux
only.  GPSMan/gpsmanshp may work on Cygwin at some point if enough
work is done to figure out and document the process.


OPTIONAL:  Install Festival support:
------------------------------------

Note: The most recent version of Festival is 2.4.  According to the
README for this version, "Do NOT use Windows with Cygwin".  With that
warning up front, here are instructions that were previously used to
make a legacy version of Festival work with Xastir.  They were not
revalidated during the November 2017 update to this document.

Allows using a synthesized voice from within Xastir for alerts,
reading messages to you, and other cool things.  Tom Russo did the
initial work on this, Henk de Groot optimized it:

1) Start BASH shell in Cygwin

2) Make ~/festival download directory and
    /usr/local/festival installation directory

3) Download festival components from festvox.org into ~/festival, in
   the Windows environment the corresponding path is:

     C:\Cygwin\home\%USERNAME%\festival

    get the following files:

     speech_tools-1.2.95-beta.tar.gz
     festival-1.95-beta.tar.gz
     festlex-CMU.tar.gz
     festlex-POSLEX.tar.gz
     festvox-kallpc16k.tar.gz

4) Build festival and company:

    cd /usr/local/festival
    tar xzf ~/festival/speech_tools-1.2.95-beta.tar.gz
    tar xzf ~/festival/festival-1.95-beta.tar.gz
    tar xzf ~/festival/festlex_CMU.tar.gz
    tar xzf ~/festival/festlex_POSLEX.tar.gz
    tar xzf ~/festival/festvox_kallpc16k.tar.gz

    cd speech_tools
    ./configure && make
    cd ../festival
    ./configure && make

   These packages are build and used where they are compiled.

5) Test festival:

    cd /usr/local/festival/festival/examples
    sh saytime

   Festival should say the time if everything went fine

6) Add /festival/festival/bin to PATH in .profile and .bashrc. For
   me both files look like this:

    .profile and .bashrc:
    -------------------
    export PATH=$PATH:/lib:/usr/lib:/usr/X11R6/lib:/usr/local/lib:/usr/local/bin:/usr/local/festival/festival/bin:~/bin:.

    -------------------

7) Configure and build xastir.  Configure should report that
   festival is found.

8) Start the festival server:

    festival --server &

   To do this automatically I added the following lines to my
   .bash_profile:

    -------------------
    if  [ `ps -ef | grep festival | wc -l` -eq 0 ]
    then
      festival --server &
      sleep 1
    fi
    -------------------

9) Run xastir, do File->Configure->Speech, add things to say, and
   listen.



OPTIONAL:  How to make Sound Alerts work under Cygwin:
------------------------------------------------------

There is currently (November 2017) a problem using sound alerts
under Cygwin.  It is recommended that sound alerts are turned off
within Cygwin or you may experience lockups.

You'll need to add the .wav files to Xastir.

git clone http://github.com/Xastir/Xastir-sounds

cd Xastir-sounds
cp -r sounds/* /usr/local/share/xastir/sounds/


November 2017 documentation updates by K2DLS.  There may be
out-of-date items that remain in this document.  Please report
issues via the Xastir mailing list.

APRS(tm) is a Trademark of Bob Bruninga

Copyright (C) 2000-2019 The Xastir Group