Menu
▾
▴
[Plplot-cvs] SF.net SVN: plplot:[9051] trunk/doc/docbook/src/ocaml.xml
|
From: <and...@us...> - 2008-12-06 17:05:07
|
Revision: 9051
http://plplot.svn.sourceforge.net/plplot/?rev=9051&view=rev
Author: andrewross
Date: 2008-12-06 17:05:03 +0000 (Sat, 06 Dec 2008)
Log Message:
-----------
ANR for Hezekiah M. Carty. Commit of ocaml documentation - new file
missing from AWI's previous commit.
Added Paths:
-----------
trunk/doc/docbook/src/ocaml.xml
Added: trunk/doc/docbook/src/ocaml.xml
===================================================================
--- trunk/doc/docbook/src/ocaml.xml (rev 0)
+++ trunk/doc/docbook/src/ocaml.xml 2008-12-06 17:05:03 UTC (rev 9051)
@@ -0,0 +1,109 @@
+<!-- -*- mode: nxml -*- -->
+<!--
+ ocaml.xml: "OCaml Language" chapter
+
+Copyright (C) 2008 Jerry Bauck (original Ada version used as base)
+Copyright (C) 2008 Hezekiah M. Carty
+
+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="OCaml">
+ <title>OCaml Language</title>
+ <para> This document describes the OCaml bindings to the PLplot technical plotting software, how to obtain the necessary software components, and how to use them together.</para>
+
+ <sect1 id="ocaml_overview">
+ <title>Overview</title>
+ <para> The OCaml bindings for PLplot provide a way for OCaml programmers to access the powerful PLplot technical plotting facilities directly from OCaml programs while working completely in OCaml—the OCaml programmer never needs to know or worry that PLplot itself is written in another language.</para>
+ </sect1>
+ <sect1 id="ocaml_bindings">
+
+ <title>The Bindings</title>
+ <para>The bindings are a re-expression and extension of the C-language API and as such are a kind of abstract layer between the user's code and the PLplot binary library. Additionally, there are a few capabilities not in the official API but nonetheless which are available to the C programmer which are included in the bindings and thus are directly available to the OCaml programmer. The OCaml PLplot API is all defined within the Plplot module. In general, it is suggested to include the line "open Plplot" in OCaml code using PLplot. The function and constant definitions are named such that they should avoid namespace collisions with other libraries. PLplot functions have a "pl" prefix while constants/variant types have a "PL_" prefix.</para>
+ <para> The core binding provides a close to direct mapping to the underlying C code. It follows the C API very closely, with the exception of a few parameters which become redundant under OCaml (ex. array lengths are determined automatically by OCaml and function callbacks which are handled slightly differently than in C).</para>
+ <para> There are also a selection of functions which provide support for operations outside of the base C API.</para>
+ <sect2 id="ocaml_core">
+ <title>Core Binding</title>
+ <para> The core binding is mostly a direct and obvious mapping of the C application programming interface (API) to OCaml. Thus, for example, where a C function such as plcol0 requires a single integer argument, there is a corresponding OCaml function also called plcol0 which also requires a single integer argument. (plcol0 happens to set the drawing color using a number which is associated with a set of colors). Various constants from the C API are also included here as OCaml variant types with a "PL_" prefix to avoid namespace clashes when the Plplot module is opened. For example, where the C PLplot API uses GRID_* to select between the data gridding methods, the OCaml API uses PL_GRID_*.</para>
+ </sect2>
+ <sect2 id="ocaml_specific">
+ <title>OCaml specific functions and functionality</title>
+ <para> Several of the PLplot core functions allow the user to provide a transformation callback function to adjust the location of the plotted data. This is handled differently in the OCaml bindings than in order to keep the interface between C and OCaml as simple as possible. Rather than passing transformation functions directly to each PLplot function which supports a coordinate transformation, the coordinate tranform functions are set globally using the plset_pltr and plset_mapform functions. Similarly, the functions plunset_pltr and plunset_mapform can be used to clear the globally defined coordinate transformation function. Note that the transform functions are only used in the functions which support them in the C API (ex. plmap)- they are not automatically applied to plotted data in other function calls (ex. plline). For demonstrations of their use, see OCaml PLplot examples 16 and 20 for plset_pltr and example 19 for plset_mapform.</para>
+ </sect2>
+ </sect1>
+ <sect1 id="ocaml_examples">
+ <title> The Examples</title>
+ <para> An important part of the OCaml bindings is the examples, some 28 of which demonstrate how to use many of the features of the PLplot package. These examples also serve as a testbed for the bindings in OCaml and other languages by checking the Postscript files that are generated by each example against those generated by the C versions. These examples have been completely re-written in OCaml (but retain a C flavor in the names that are given to objects). All of the OCaml examples generate exactly the same Postscript as the C versions, examples 14 and 17 excepted since they have not been translated yet.</para>
+ </sect1>
+ <sect1 id="ocaml_obtaining">
+ <title>Obtaining the Software</title>
+ <para> There are three software components that you will need: the OCaml compiler, the PLplot library, and the camlidl OCaml >-< C binding generator. As of version 5.9.1, the OCaml bindings are included in the core PLplot distribution.</para>
+ <sect2 id="ocaml_obtaining_ocaml">
+ <title>Obtaining the OCaml compiler</title>
+ <para> You will need the OCaml compiler in order to build and use the OCaml PLplot bindings. OCaml includes both a bytecode compiler (ocamlc) and a native code compiler (ocamlopt). Both of these are supported by PLplot.</para>
+ <para> Your computer may already have OCaml installed, or you can download it from <ulink url="http://caml.inria.fr/">caml.inria.fr</ulink>. Several Linux distributions including Debian, Ubuntu and Fedora have OCaml binary packages available. Another route to obtaining OCaml is by using GODI, a source-based distribution of OCaml and a number of OCaml libraries. GODI can be retrieved from <ulink url="http://godi.camlcity.org/">godi.camlcity.org</ulink>. GODI has support for building and installing under Linux, Apple's OS X and MS Windows.</para>
+ </sect2>
+ <sect2 id="ocaml_obtaining_plplot">
+ <title>Download and install PLplot</title>
+ <para> PLplot can be downloaded from the PLplot home page at <ulink url="http://sourceforge.net/projects/plplot">sourceforge.net—plplot</ulink>. Follow the installation instructions after downloading. The installation process is more involved than other open source software and requires that your computer has cmake installed. Packages are available for several major Linux distributions, though the OCaml bindings are only included in versions 5.9.1 and later. OCaml bindings are available for versions 5.8.0 and 5.9.0 at <ulink url="http://ocaml-plplot.googlecode.com/">ocaml-plplot.googlecode.com</ulink>. These bindings are not as complete as the bindings included in the official PLplot releases but are still quite functional.</para>
+ </sect2>
+ </sect1>
+ <sect1 id="ocaml_howto">
+ <title>How to use the OCaml bindings</title>
+ <sect2 id="ocaml_sample_project">
+ <title>Sample command line project</title>
+ <para> It is instructive to present a simple example that can be compiled and run from the command line. Although this example is specific to one installation, it should be fairly straightforward to adapt it to another installation. Toward that end, it is helpful to understand the PLplot lingo of "build directory" and "installation directory."</para>
+ <para> Here is a simple program that will generate a plot of part of a parabola.</para>
+ <programlisting>
+ open Plplot
+ let simple_example () =
+ let xs = Array.init 21 (fun xi -> float xi -. 10.0) in
+ let ys = Array.map (fun x -> x**2.0) xs in
+ plinit ();
+ plenv (-10.0) 10.0 0.0 100.0 0 0;
+ plline xs ys;
+ plend ();
+ ()
+
+ let () = simple_example ()
+ </programlisting>
+ <para> Next is a command line that will compile, bind, and link it. It requires that the OCaml findlib program is installed and in your $PATH and that the above code be saved as simple_example.ml</para>
+ <programlisting>
+ ocamlfind opt -package plplot -linkpkg -o simple_example simple_example.ml
+ </programlisting>
+ <para> The resulting binary program can be run by typing <command>./simple_example</command></para>
+
+ </sect2>
+ </sect1>
+ <sect1 id="ocaml_known_issues">
+ <title>Known Issues</title>
+ <para></para>
+
+ </sect1>
+</chapter>
This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site.
|
