----------------------------------------------------------------------
1.  Overview
----------------------------------------------------------------------

a.  Opencpn was built with the following objectives in mind.

    i.   Intended use as primary navigation interface for vessels
         with full-time helm-visible navigational suites.
         Other tools may be better for offline route planning, tide
         and current prediction, online logging, etc.
    ii.  Quick startup and shutdown.
    iii. Those and only those toolbar buttons really needed for
         daily operation.
    iv.  Portability, thus wxWidgets core components.  Currently
         tested and in production use on W98, XP, OSx, and Linux.
    v.   Conventional ( i.e. popular and modern ) chart format
         support.  In the real world, this means BSB format raster
         charts, and S57ENC format vector charts.



        And, of course, opencpn is all GPL'ed (or equivalent)
                        Open Source code.


    Personal Note:
    Opencpn is in primary daily use as the navigation package aboard
    M/V Dyad, a 48 ft trawler yacht cruising from Newfoundland to the
    Bahamas yearly.

----------------------------------------------------------------------
2.  Library Notes & Requirements
----------------------------------------------------------------------

a.  External OGR/GDAL library support is deprecated from OpenCPN Version
1.2.4 and greater.  The required support modules and classes are
integrated into the OpenCPN source tree. See src/mygdal.

b.  iso8211 class support is required to build OpenCPN from source with
S57 ENC support.  The relevant files are in the source tree as src/myiso8211.
These files are verbatim copies of the files by the same name in the
open source GDAL/OGR library Version 1.2.1.

Thanks to Frank Warmerdam and others for GDAL/OGR.
What an impressive body of work!

c.  OpenCPN S57 ENC support works best with access to the OpenGL Utility
library GLU.  GLU is used to tesselate large polygon areas into small
triangles for faster display rendering.  If you cannot use, or do not have
the OpenGL Utility library, you may choose to build OpenCPN with internal
tesselator support.  The internal tesselator is sub-optimal compared to GLU,
but it does work, if somewhat slower. OpenGLU is better.
See the Build Notes section for applicable tesselator configuration options.


d.  OpenCPN requires WxWidgets Version 2.6.2 or greater.  It has been tested
with the following wxWidgets hosts:

         Universal/Native X11 (__WXX11__)
         GTK2                 (__WXGTK__)
         MSWindows            (__WXMSW__)
         MAC OSx              (__WXOSX__)

See below for information on obtaining and installing wxWidgets.

----------------------------------------------------------------------
3.  Platform Specific Build Notes
----------------------------------------------------------------------

a.  MS Windows

If you would like to build OpenCPN for MS Windows from source, perform
the following steps.

If you experience difficulties, post a note on the OpenCPN project forum
at sourceforge.net.  The development team will try to help you out.

---------------------------
STEP 0:  Background
---------------------------

OpenCPN for MS Windows (TM) is built using the Watcom C/C++ command line tools.
You may download (for free) the latest version from:

		http://www.openwatcom.org/
		
Version 1.6 tools are current.
		
 
---------------------------
STEP 1:  Download wxWidgets
---------------------------
To simplify the implementation of a near-identical user
interface across platforms, OpenCPN uses classes and
resources from wxWidgets, a portable GUI framework for C++
(and Python). You must download and build wxWidgets before
attempting to compile OpenCPN.

OpenCPN builds use wxWidgets 2.6.x series (or later) for 
Microsoft Windows (MSW), available at 
"http://www.wxwidgets.org/".

When you download and execute the MSW setup.exe program for wxWidgets,
the wxWidgets files will be installed to your system.
Make a note of the base install location, which will be something like
		
		C:\wxWidgets-2.8.3
		
You will need this later.		


------------------------
STEP 2:  Build wxWidgets
------------------------
When you have downloaded and installed wxWidgets, you must
build it.   The standard wxWidgets build procedures work fine,
and are dependent on your system build tools and environment.
See the README files in the wxWidgets installation directory.

For example, if you use the MSVC makefile build methodology, then
in the directory c:\wxWidgets-2.8.3\build\msw, the command

		wmake -f makefile.wat
		
will build a statically linkable Debug configuration of wxWidgets.
		
Build the configurations for all the wxWidgets projects 
corresponding to which configurations of OpenCPN that you want 
to build. OpenCPN for Windows may be built in Debug and Release
configurations.  OpenCPN can use either multithreaded static or 
multithreaded dynamic libraries. Choose...

------------------------
STEP3:  Set OpenCPN Options
------------------------
Set the required build options in file:
	makefile.wat
See the comments within.

In particular, YOU MUST set the location of the installed wxWidgets
libraries. e.g.
		WX_BASE = c:\wxWidgets-2.8.3

------------------------
STEP4:  Build OpenCPN 
------------------------
From an MS-Dos command line window, in the opencpn base directory, do:

            wmake -f makefile.wat clean
            wmake -f makefile.wat

The opencpn.exe, (debug version) file will be built in the .\debug_ directory.

For a release build, edit the file makefile.wat and change the definition of
BUILD to
		BUILD = release
		
Then, 		
            wmake -f makefile.wat clean
            wmake -f makefile.wat
			
The release opencpn.exe file will be built in the .\release_ directory.


In either case, do:
            wmake -f makefile.wat install

This will copy the appropriate files to the install location specified in
makefile.wat, typically c:\Program Files\opencpn

OpenCPN is now ready to run.

c. For Macintosh OSx

If you would like to build OpenCPN for Macintosh OSx from source, perform
the following steps.

If you experience difficulties, post a note on the OpenCPN project forum
at sourceforge.net.  The development team will try to help you out.

---------------------------
STEP 0:  Background
---------------------------

OpenCPN for OSx (TM) is built using the XCode tools from Apple.
You may download (for free) the latest version from:

		http://developer.apple.com/tools/download/
		
Version 3.0 tools are what the latest build was tested with.
Version 3.1 is available but has not been tested.
		
 
---------------------------
STEP 1:  Download wxWidgets
---------------------------
To simplify the implementation of a near-identical user
interface across platforms, OpenCPN uses classes and
resources from wxWidgets, a portable GUI framework for C++
(and Python). You must download and build wxWidgets before
attempting to compile OpenCPN. Currently testing is being
done with 2.8.8

OpenCPN builds use wxWidgets 2.8.7 series (or later) for 
Macintosh OSx, available at 
"http://www.wxwidgets.org/".

When you download and execute the configuration tool for wxWidgets,
the wxWidgets files will be installed to your system.
Make a note of the base install location, which will be something like
		
		\Users\YourUserName\wxWidgets-2.8.8
		
You will need this later.		

------------------------
STEP 2:  Build wxWidgets
------------------------
When you have downloaded and installed wxWidgets, you must
build it.   The standard wxWidgets build procedures work fine,
and are dependent on your system build tools and environment.
See the README files in the wxWidgets installation directory.

Currently testing is being done with the XCode build, Xcode 3.0, and the
default settings. Locate the wxWindows.xcodeproj and open it with
XCode. You will need to copy the setup.h file from the src/mac directory
to /src before the build.

If you are using a different version of wxWidgets or Xcode here are the
basic steps you will need to follow.

The build system for wxWidgets uses a configure command to setup the
many options provided. These are the configure commands used to build
the libraries we tested with. they are a good place to start.

system 10.4 building wxMac 2.6.4

../configure --with-mac --enable-monolithic --disable-shared --disable-dynlib --disable-dynamicloader -enable-debug -enable-debug_gdb --enable-stdpathscd

system 10.5 building wxMac 2.8.7

../configure  --with-libpng --enable-monolithic --disable-shared --disable-dynlib --disable-dynamicloader -enable-debug -enable-debug_gdb --with-macosx-sdk=/Developer/SDKs/MacOSX10.5.sdk --with-macosx-version-min=10.4 --with-zlib=builtin

Copy the new libraries to the opencpn directory. These libraries
are normally in \Users\YourUserName\opencpn\buildosx\libraries

------------------------
STEP4:  Build OpenCPN 
------------------------

Note: The current project setup assumes the opencpn and wxWidgets-2.8.8 are at the same level in the same directory.
If this is not the case, you will have to adjust the search paths in the project 
to point to the include files for wxWidgets.

Start the XCode Tools and open the openCPNOSx.xcodeproj in \Users\YourUserName\opencpn\buildosx\

Select 'Build' from the build menu

OpenCPN is now ready to run.

------------------------
STEP4 (alternative)
      Build OpenCPN using ./configure && make [&& make dmg]
------------------------
OpenCPN will build for Mac OS X from a shell script by using the
familiar Autotools configure and make:

% cd opencpn; ./configure --with-wx-config=path/to/your/wx-config && make

If make sucessfully completes you should have a directory called OpenCPN.app
which you can open with finder or from the command like with 'open'. As always
if you have questions or problems please let the OpenCPN development team know
by posting to the OpenCPN project forum at sourceforge.net.

If you'd like to build a disk image (dmg file) then use the dmg target like so:

% make dmg

-------------------------
Notes For Advanced Users:

a. Windows

b. LINUX

i.  Obtain wxWidgets

Download wxWidgets 2.6.x (or later) from:

        http://www.wxWidgets.org/

        If you install the RPM, make sure you install the devel RPM
        as well, otherwise, you won't be able to compile opencpn
        from source.

ii. Compile Opencpn

Opencpn uses the GNU Automake system, so...

        ./configure
        make

        su, <password>

        make install	# as root

By default, the GNU installer installs opencpn executable to /usr/local/bin,
and the required data files to /usr/local/share/opencpn.
This location may be changed using the "--program-prefix=" parameter during
configuration.


Some configure options specific to opencpn are available:

        --disable-s57enc            Disable S57ENC support
                                    Default is ENABLED.

        --with-gdal-system          Deprecated from Version 1.2.4

        --with-tess-internal        Use internal tesselator, as opposed
                                    to system library OpenGL gluTess.
                                    Default is OFF, use system OpenGL.

        --with-wifi-client          Use (undocumented) wifi monitor client
                                    interface.
                                    Default is OFF.

        --with-wx-config=<file>	    Specify the location of a valid wx-config
                                    script as created by wxWidgets installation.
                                    Default is as found in $PATH.            

WxWidgets linkages and include paths are discovered by the
makefile using conventional wx-config scripts as
normally installed by this packages.

iii.  Known Build Bugs/Gotchas

(1). This particular flavor of wxWidgets, 

  (__WXX11__, version 2.6...2.8, compiled without wxWidgets 2.4 compatibility)

contains a bug related to TCP/IP sockets.  The configure script detects this bug
and disables all OpenCPN socket support, meaning that the GPSD network GPS input
option is unavailable.    This bug does not appear in __WXMSW__ nor __WXGTK__.
You may workaround this bug by rebuilding wxWidgets with "--enable-compat24".

----------------------------------------------------------------------
4.  File and Directory Permissions under Linux
----------------------------------------------------------------------

a.  As from opencpn Version 1.2.6, the SENC files and thumbnail bitmaps
are stored in user space.  Accordingly, the directory tree containing
the ENC chart files need no longer export write permission for opencpn.
Unix permissions of 0755 are sufficient, assuming the directory is owned
by root.

b.  It is sufficient for all other directories in /usr/share/opencpn
to have permissions 0755, i.e. exec/searchable and readable by all.

----------------------------------------------------------------------
5. Support File Locations
----------------------------------------------------------------------

a.  Opencpn requires numerous auxiliary data files.  These files
are installed by the installer into the following locations by default:

      Linux   - /usr/local/share/opencpn/
      Windows - \Program Files\opencpn\
      Mac     - /Users/YourUserName/openCPNfiles/

The following directories exist within the above:
         .../bitmaps                     - self evident
         .../tcdata                      - tide and current location data
         .../s57data                     - data files for S57ENC support
         .../wvsdata                     - World Vector Shoreline data

b.  Opencpn config files are expected in the following locations:

      Linux   - ~/.opencpn/opencpn.conf
      Windows - \Program Files\opencpn\opencpn.ini

The installer will place nice default files for your use.  The first
execution of opencpn will update as needed.  If for some reason the
config file is not found, opencpn will offer to create a useable
starting configuration.


----------------------------------------------------------------------
6. Serial Port GPS/AIS Data Input and Autopilot Output
----------------------------------------------------------------------

a.  LINUX
Opencpn runs at user privilege.  This means that in order to
read GPS input data and/or write autopilot output data, the serial
devices to be used must exhibit read and write permission for the
user in question.  For linux, these devices are created at startup.
Typically, the devices as created are owned by root, with additional
specific group (e.g. "uucp") r/w access,  i.e. permissions are 0660.

This configuration WILL NOT WORK for OpenCPN unless the user happens
to belong to the group under which the devices were created,
typically "uucp".  Not likely...

For the more general case, you must ensure that device permissions
will enable opencpn to read and write serial devices without root
privileges.  There are several ways to do this.

On a Linux with udev, check the files in /etc/udev/rules.d to
ensure that /dev/tty* devices are all created with the same group
and with 0666 permissions.  More generally, you may need to run mknod
or MAKEDEV as root to create a properly permissioned serial device before
executing opencpn.  For example:

      linux# mknod -m 666 /dev/ttyS0 c 4 64

If you use USB serial port adapters and your system has the Linux
hotplug facility installed, Todo............

Test your GPS input.  At user privilege,

      linux$ stty -F /dev/ttyXXX ispeed 4800
      linux$ cat </dev/ttyXXX

replace ttyXXX with the filename of the port.  This will probably be
either /dev/ttyUSB0 or /dev/ttyS0.  When you run this command, you
should see text lines beginning with $ come to stdout (possibly after
a short initial burst of binary garbage).  If you don't see this, you
may have OS-level problems with your serial support, but more likely
have the wrong device or permissions.  Look again.

