<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
<title>PPL C Language Interface: Main Page</title>
<link href="tabs.css" rel="stylesheet" type="text/css"/>
<link href="doxygen.css" rel="stylesheet" type="text/css"/>
</head>
<body>
<!-- Generated by Doxygen 1.6.3 -->
<div class="navigation" id="top">
<div class="tabs">
<ul>
<li class="current"><a href="main.html"><span>Main Page</span></a></li>
<li><a href="pages.html"><span>Related Pages</span></a></li>
<li><a href="modules.html"><span>Modules</span></a></li>
<li><a href="annotated.html"><span>Classes</span></a></li>
</ul>
</div>
</div>
<div class="contents">
<h1>PPL C Language Interface Documentation</h1><h3 class="version">0.11.2 </h3><p>All the declarations needed for using the PPL's C interface (preprocessor symbols, data types, variables and functions) are collected in the header file <code>ppl_c.h</code>. This file, which is designed to work with pre-ANSI and ANSI C compilers as well as C99 and C++ compilers, should be included, either directly or via some other header file, with the directive </p>
<div class="fragment"><pre class="fragment"><span class="preprocessor">#include <ppl_c.h></span>
</pre></div><p> If this directive does not work, then your compiler is unable to find the file <code>ppl_c.h</code>. So check that the library is installed (if it is not installed, you may want to <code>make install</code>, perhaps with root privileges) in the right place (if not you may want to reconfigure the library using the appropriate pathname for the <code>--prefix</code> option); and that your compiler knows where it is installed (if not you should add the path to the directory where <code>ppl_c.h</code> is located to the compiler's include file search path; this is usually done with the <code>-I</code> option).</p>
<p>The name space of the PPL's C interface is <code>PPL_*</code> for preprocessor symbols, enumeration values and variables; and <code>ppl_*</code> for data types and function names. The interface systematically uses <em>opaque data types</em> (generic pointers that completely hide the internal representations from the client code) and provides all required access functions. By using just the interface, the client code can exploit all the functionalities of the library yet avoid directly manipulating the library's data structures. The advantages are that (1) applications do not depend on the internals of the library (these may change from release to release), and (2) the interface invariants can be thoroughly checked (by the access functions).</p>
<dl class="note"><dt><b>Note:</b></dt><dd>All functions taking as input argument an opaque pointer datatype assume that such an argument is actually <em>referring to a valid PPL object</em>. For instance, a function with an argument having type <code>ppl_MIP_Problem_t</code> will expect a valid MIP_Problem object, previously initialized by calling, e.g., <code>ppl_new_MIP_Problem</code>. If that is not the case (e.g., if a null pointer is passed in), the behavior is undefined.</dd></dl>
<p>The PPL's C interface is initialized by means of the <code>ppl_initialize</code> function. This function must be called <em>before using any other interface of the library</em>. The application can release the resources allocated by the library by calling the <code>ppl_finalize</code> function. After this function is called <em>no other interface of the library may be used</em> until the interface is re-initialized using <code>ppl_initialize</code>.</p>
<p>Any application using the PPL should make sure that only the intended version(s) of the library are ever used. The version used can be checked at compile-time thanks to the macros PPL_VERSION_MAJOR, PPL_VERSION_MINOR, PPL_VERSION_REVISION and PPL_VERSION_BETA, which give, respectively major, minor, revision and beta numbers of the PPL version. This is an example of their use: </p>
<div class="fragment"><pre class="fragment"><span class="preprocessor">#if PPL_VERSION_MAJOR == 0 && PPL_VERSION_MINOR < 6</span>
<span class="preprocessor"></span><span class="preprocessor"># error "PPL version 0.6 or following is required"</span>
<span class="preprocessor">#endif</span>
</pre></div><p> Compile-time checking, however, is not normally enough, particularly in an environment where there is dynamic linking. Run-time checking can be performed by means of the functions <code>ppl_version_major</code>, <code>ppl_version_minor</code>, <code>ppl_version_revision</code>, and <code>ppl_version_beta</code>. The PPL's C interface also provides functions <code>ppl_version</code>, returning character string containing the full version number, and <code>ppl_banner</code>, returning a string that, in addition, provides (pointers to) other useful information for the library user.</p>
<p>All programs using the PPL's C interface must link with the following libraries: <code>libppl_c</code> (PPL's C interface), <code>libppl</code> (PPL's core), <code>libgmpxx</code> (GMP's C++ interface), and <code>libgmp</code> (GMP's library core). On most Unix-like systems, this is done by adding <code>-lppl_c</code>, <code>-lppl</code>, <code>-lgmpxx</code>, and <code>-lgmp</code> to the compiler's or linker's command line. For example: </p>
<div class="fragment"><pre class="fragment">
gcc myprogram.o -lppl_c -lppl -lgmpxx -lgmp
</pre></div><p> If this does not work, it means that your compiler/linker is not finding the libraries where it expects. Again, this could be because you forgot to install the library or you installed it in a non-standard location. In the latter case you will need to use the appropriate options (usually <code>-L</code>) and, if you use shared libraries, some sort of run-time path selection mechanisms. Consult your compiler's documentation for details. Notice that the PPL is built using <a href="http://www.gnu.org/software/libtool/">Libtool</a> and an application can exploit this fact to significantly simplify the linking phase. See Libtool's documentation for details. Those working under Linux can find a lot of useful information on how to use program libraries (including static, shared, and dynamically loaded libraries) in the <a href="http://www.dwheeler.com/program-library/">Program Library HOWTO</a>.</p>
<p>For examples on how to use the functions provided by the C interface, you are referred to the directory <code>demos/ppl_lpsol/</code> in the source distribution. It contains a <em>Mixed Integer (Linear) Programming</em> solver written in C. In order to use this solver you will need to install <a href="http://www.gnu.org/software/glpk/">GLPK</a> (the GNU Linear Programming Kit): this is used to read linear programs in MPS format. </p>
</div>
<hr class="footer"/><address style="text-align: right;"><small>Generated on Sun Feb 27 10:12:18 2011 for PPL C Language Interface by
<a href="http://www.doxygen.org/index.html">
<img class="footer" src="doxygen.png" alt="doxygen"/></a> 1.6.3 </small></address>
</body>
</html>
