---------------------------------------------------------------------- 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, 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. For S57 ENC support, OpenCPN requires the GDAL/OGR library, Version 1.2.0 or better. This library is available from http://www.remotesensing.org/gdal If GDAL/OGR library support is available on your system, OpenCPN may be built to use that library. Use the --with-gdal-system option for configuration. See configuration options below. Otherwise, the default OpenCPN configuration script compiles and links an internal copy of the required GDAL modules. See src/mygdal/* Note that there were problems with the ISO8211 library in Version 1.2.0 as relates to S57 ENC updates. Specifically, OpenCPN requires the inclusion in the library of ddfrecord.cpp Version 1.27 or greater to support ENC updates. Check the source version in your library: ident /libgdal.so | grep ddfrecord.cpp OpenCPN will check for this library compatibility at run-time, display a message, and disable ENC updates as necessary. GDAL/OGR Version 1.2.1 corrects this bug. The current GDAL/OGR Version (1.3.2) (1 Aug, 2006) has been tested OK, as has the internal version included in this distribution of OpenCPN. b. iso8211 class support is required to build OpenCPN from source with S57 ENC support. GDAL/OGR includes and uses iso8211 file support, but the interesting classes and methods are not exported from the GDAL library. So, the relevant files are in the source tree as src/myiso8211. These files are verbatim copies of the files by the same name in 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__) 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. ------------------------ MSVC++ 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... ------------------------ MSVC++ 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 ------------------------ MSVC++ 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. ------------------------- Notes For Advanced Users: OpenCPN requires a functional GDAL/OGR library for S-57 vector chart support. The default makefile setup compiles and links an internal version of these libraries for your build convenience. Source is in However, If you would like to use a GDAL/OGR library already present on your system, you may do so. Edit the makefile.wat file to enable static or dynamic (i.e. DLL) linkage of your GDAL, and specify the library location as required. As a consequence of building with static GDAL/OGR library linkage, the MS linker will emit a .LIB and .EXP file set, and complain about library conflicts with LIBC. These warnings come about as a result of exports defined in gdal.lib. as a part of the default gdalxx.dll build. These files and warnings may be safely ignored. IMPORTANT: Linking with GDAL/OGR as a DLL (e.g.. gdal12.dll) does not work. OGR requires parameter passage via environment variables. The library uses getenv() to fetch parameter values. getenv() does not work from within a DLL, since a DLL has no common data storage with the caller. See MS Knowledge Base Article ID: Q78542 . There are two workarounds. i. Link GDAL/OGR statically or internally (i.e. do not use gdalxx.dll), or ii. Ensure that the following two files are present in the user's current directory at run-time: s57attributes.csv s57objectclasses.csv The wmake install target places these files in the selected install directory automatically, typically C:\Program Files\opencpn Finally, S57ENC support, and related GDAL/OGR compilation and linkage may be disabled completely in makefile.wat by un-defining the variable USE_S57. All of this library linkage gorp may be avoided by simply using the internal GDAL/OGR libraries provided by OpenCPN. 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, 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: --enable-s57enc Compile and enable S57ENC support --enable-s57enc=0 ...or not... Default is ENABLED. --with-gdal-system Use system GDAL/OGR library. Useful in cases where GDAL library is available and current on your system. Default is OFF, using internal GDAL. --with-tess-internal Use internal tesselator, as opposed to OpenGL gluTess. Default is OFF, use system OpenGL. --with-wifi-client Use (undocumented) wifi monitor client interface. Default is OFF. --with-wx-config= Specify the location of a valid wx-config script as created by wxWidgets installation. Default is as found in $PATH. GDAL/OGR and WxWidgets linkages and include paths are discovered by the makefile using conventional gdal-config and wx-config scripts as normally installed by those 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. The directory tree containing the ENC vector charts must be read and write enabled for the current user. This allows the dynamic creation of SENC files and chart thumbnail images as needed. Since this tree, e.g. /usr/local/share/opencpn/ENC_ROOT, is typically owned by root, it must be given (recursively) 0777 permissions. 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\ 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