<!-- -*-  mode: nxml -*- -->
<!--
    os_notes.xml: "Notes for each Operating System that We Support" chapter
    
    Copyright (C) 1994  Geoffrey Furnish and Maurice LeBrun
    Copyright (C) 1999, 2000, 2001, 2002, 2003  Rafael Laboissiere
    Copyright (C) 1999, 2000, 2001, 2002, 2003, 2007  Alan W. Irwin
    Copyright (C) 2003  Joao Cardoso

Redistribution and use in source (XML DocBook) and "compiled" forms
(HTML, PDF, PostScript, DVI, TeXinfo and so forth) with or without
modification, are permitted provided that the following conditions are
met:

1. Redistributions of source code (XML DocBook) must retain the
above copyright notice, this list of conditions and the following
disclaimer as the first lines of this file unmodified.

2. Redistributions in compiled form (transformed to other DTDs,
converted to HTML, PDF, PostScript, and other formats) must
reproduce the above copyright notice, this list of conditions and
the following disclaimer in the documentation and/or other
materials provided with the distribution.

Important: THIS DOCUMENTATION IS PROVIDED BY THE PLPLOT PROJECT "AS IS"
AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE PLPLOT PROJECT BE LIABLE
FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR
BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS DOCUMENTATION,
EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
-->

<chapter id="os-notes">
  <title>Notes for each Operating System that We Support</title>
  
  <para>
    The purpose of this Chapter is to present notes for each operating system
    that we support. Currently, those are all operating systems supported by
    CMake (all forms of Unix including Linux and Mac OS X, and all forms of
    Windows including MinGW, MinGW/MSYS, Cygwin, and essentially all Windows
    variants directly supported by Microsoft).
  </para>

  <sect1 id="linux-unix-notes">
    <title>Linux/Unix Notes</title>
    <sect2>
      <title>Linux/Unix Configure, Build, and Installation</title>
      <para>
	Here is the short story:
	<programlisting>
	  # Note many other cmake options are available besides -DCMAKE_INSTALL_PREFIX
	  # Inspect CMakeCache.txt after a preliminary cmake run to see an annotated
	  # list of the available options.  Then remove CMakeCache.txt and try again.
	  cmake -DCMAKE_INSTALL_PREFIX=&lt;install-prefix&gt; \
	  &lt;path-to-source-tree&gt; &gt;&amp; cmake.out
	  make &gt;&amp; make.out
	  #(optional, requires -DBUILD_TEST=ON option for cmake)
	  ctest &gt;&amp; ctest.out
	  make install &gt;&amp; make_install.out
	  cd &lt;install-prefix&gt;/share/plplot&lt;version&gt;/examples/
	  make &gt;&amp; make_examples.out
	  ./plplot-test.sh &gt;&amp; plplot-test.sh.out
	</programlisting>
      </para>
      <para>
	The longer (CMake) story is currently documented <ulink
	url="http://sourceforge.net/p/plplot/wiki/Building_PLplot">here</ulink>.
	The eventual plan is to incorporate that material in this documentation,
	but we haven't done it yet so this section NEEDS DOCUMENTATION.
      </para>

    </sect2>
    <sect2> 
      <title>Linux/Unix Building of C Programmes that Use the 
      Installed PLplot Libraries</title> 
      
      <para> This is incomplete.  For now follow what is done to build
      our installed examples (see "make &gt;&amp; make_examples.out above) using
      pkg-config.  NEEDS DOCUMENTATION.
      </para>

    </sect2>

  </sect1>
  <sect1 id="windows-notes">
    <title>Windows Notes</title>
    <sect2>
      <title>Windows Configure and Build</title>
      <para>
	This (CMake) story is currently documented <ulink
	url="http://sourceforge.net/p/plplot/wiki/Specifics_for_various_platforms#Windows">here</ulink>.
	The eventual plan is to incorporate that material into this documentation,
	but we haven't done it yet so this section NEEDS DOCUMENTATION.
      </para>
    </sect2>

  </sect1>

  <sect1 id="macosx-notes">
    <title>Mac OS X Notes</title>
    <para>
      PLplot has been tested with Mac OS X 10.8 and 10.9 using the
      Apple LLVM version 6.0 compiler provided by XCode 6.1.1.  CMake
      must be installed in order to build PLplot and version 3.1.3
      from MacPorts has been tested.
    </para>
    <para>
      If language bindings (e.g. Python) are needed, PLplot has been
      tested with the ports from MacPorts.  When using MacPorts, there
      is a secondary dependency that occurs if SWIG is installed.  For
      example, if python is installed from MacPorts, swig-python must
      also be installed.
    </para>
    <para>
      If both XQuartz and the xorg-libX11 port is installed, CMake may
      fail to configure PLplot correctly and the build will fail.  If
      this occurs, use the following CMake command string.
      <programlisting>
	cmake -DX11_X11_LIB=/opt/X11/lib/libX11.dylib \
	  -DX11_X11_INCLUDE_PATH=/opt/X11/include -DENABLE_tk=OFF \
	  &lt;path-to-source-tree&gt; &gt;&amp; cmake.out
      </programlisting>
    </para>
    <sect2>
      <title>Mac OS X Configure and Build</title>
      <para>
	The build process for Mac OS X follows the same basic steps
	used Linux and Unix platforms.  
      </para>
      <para>
	The following steps will configure and build PLplot on Mac OS
	X that do not have the XQuartz and xorg-libX11 conflict.
	<programlisting>
	  # Note many other cmake options are available besides -DCMAKE_INSTALL_PREFIX
	  # Inspect CMakeCache.txt after a preliminary cmake run to see an annotated
	  # list of the available options.  Then remove CMakeCache.txt and try again.
	  cmake -DCMAKE_INSTALL_PREFIX=&lt;install-prefix&gt; \
	  &lt;path-to-source-tree&gt; &gt;&amp; cmake.out
	  make &gt;&amp; make.out
	  #(optional, requires -DBUILD_TEST=ON option for cmake)
	  ctest &gt;&amp; ctest.out
	  make install &gt;&amp; make_install.out
	  cd &lt;install-prefix&gt;/share/plplot&lt;version&gt;/examples/
	  make &gt;&amp; make_examples.out
	  ./plplot-test.sh &gt;&amp; plplot-test.sh.out
	</programlisting>
      </para>
    </sect2>
  </sect1>
</chapter>
