/usr/lib/swi-prolog/doc/Manual/plld.html

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd">

<HTML>
<HEAD>
<TITLE>SWI-Prolog 5.11.18 Reference Manual: Section 9.5</TITLE><LINK REL=home HREF="index.html">
<LINK REL=contents HREF="Contents.html">
<LINK REL=index HREF="DocIndex.html">
<LINK REL=summary HREF="summary.html">
<LINK REL=previous HREF="foreigninclude.html">
<LINK REL=next HREF="findhome.html">
<STYLE type="text/css">
/* Style sheet for SWI-Prolog latex2html
*/

dd.defbody
{ margin-bottom: 1em;
}

dt.pubdef
{ background-color: #c5e1ff;
}

dt.multidef
{ background-color: #c8ffc7;
}

.bib dd
{ margin-bottom: 1em;
}

.bib dt
{ float: left;
margin-right: 1.3ex;
}

pre.code
{ margin-left: 1.5em;
margin-right: 1.5em;
border: 1px dotted;
padding-top: 5px;
padding-left: 5px;
padding-bottom: 5px;
background-color: #f8f8f8;
}

div.navigate
{ text-align: center;
background-color: #f0f0f0;
border: 1px dotted;
padding: 5px;
}

div.title
{ text-align: center;
padding-bottom: 1em;
font-size: 200%;
font-weight: bold;
}

div.author
{ text-align: center;
font-style: italic;
}

div.abstract
{ margin-top: 2em;
background-color: #f0f0f0;
border: 1px dotted;
padding: 5px;
margin-left: 10%; margin-right:10%;
}

div.abstract-title
{ text-align: center;
padding: 5px;
font-size: 120%;
font-weight: bold;
}

div.toc-h1
{ font-size: 200%;
font-weight: bold;
}

div.toc-h2
{ font-size: 120%;
font-weight: bold;
margin-left: 2em;
}

div.toc-h3
{ font-size: 100%;
font-weight: bold;
margin-left: 4em;
}

div.toc-h4
{ font-size: 100%;
margin-left: 6em;
}

span.sec-nr
{
}

span.sec-title
{
}

span.pred-ext
{ font-weight: bold;
}

span.pred-tag
{ float: right;
padding-top: 0.2em;
font-size: 80%;
font-style: italic;
color: #202020;
}

/* Footnotes */

sup.fn { color: blue; text-decoration: underline; }
span.fn-text { display: none; }
sup.fn span {display: none;}
sup:hover span
{ display: block !important;
position: absolute; top: auto; left: auto; width: 80%;
color: #000; background: white;
border: 2px solid;
padding: 5px; margin: 10px; z-index: 100;
font-size: smaller;
}
</STYLE>
</HEAD>
<BODY BGCOLOR="white">
<DIV class="navigate"><A class="nav" href="index.html"><IMG SRC="home.gif" BORDER=0 ALT="Home"></A>
<A class="nav" href="Contents.html"><IMG SRC="index.gif" BORDER=0 ALT="Contents"></A>
<A class="nav" href="DocIndex.html"><IMG SRC="yellow_pages.gif" BORDER=0 ALT="Index"></A>
<A class="nav" href="summary.html"><IMG SRC="info.gif" BORDER=0 ALT="Summary"></A>
<A class="nav" href="foreigninclude.html"><IMG SRC="prev.gif" BORDER=0 ALT="Previous"></A>
<A class="nav" href="findhome.html"><IMG SRC="next.gif" BORDER=0 ALT="Next"></A>
</DIV>

<H2><A NAME="sec:9.5"><SPAN class="sec-nr">9.5</SPAN> <SPAN class="sec-title">Linking 
embedded applications using swipl-ld</SPAN></A></H2>

<A NAME="sec:plld"></A>

<P>The utility program <B>swipl-ld</B> (Win32: swipl-ld.exe) may be used 
to link a combination of C-files and Prolog files into a stand-alone 
executable.
<B>swipl-ld</B> automates most of what is described in the previous 
sections.

<P>In the normal usage, a copy is made of the default embedding template
<CODE>\ldots/pl/include/stub.c</CODE>. The main() routine is modified to 
suit your application. <A class="func" href="foreigninclude.html#PL_initialise()">PL_initialise()</A> <STRONG>must</STRONG> 
be passed the program-name (<VAR>argv[0]</VAR>) (Win32: the executing 
program can be obtained using GetModuleFileName()). The other elements 
of the command-line may be modified. Next, <B>swipl-ld</B> is typically 
invoked as:

<PRE class="code">
swipl-ld -o output stubfile.c [other-c-or-o-files] [plfiles]
</PRE>

<P><B>swipl-ld</B> will first split the options into various groups for 
both the C-compiler and the Prolog compiler. Next, it will add various 
default options to the C-compiler and call it to create an executable 
holding the user's C-code and the Prolog kernel. Then, it will call the 
SWI-Prolog compiler to create a saved state from the provided Prolog 
files and finally, it will attach this saved state to the created 
emulator to create the requested executable.

<P>Below, it is described how the options are split and which additional 
options are passed.

<DL class="latex">
<DT><STRONG>-help</STRONG> <VAR></VAR></DT>
<DD class="defbody">
Print brief synopsis.
</DD>
<DT><STRONG>-pl</STRONG> <VAR>prolog</VAR></DT>
<DD class="defbody">
Select the prolog to use. This prolog is used for two purposes: get the 
home-directory as well as the compiler/linker options and create a saved 
state of the Prolog code.
</DD>
<DT><STRONG>-ld</STRONG> <VAR>linker</VAR></DT>
<DD class="defbody">
Linker used to link the raw executable. Default is to use the C-compiler 
(Win32: <B>link.exe</B>).
</DD>
<DT><STRONG>-cc</STRONG> <VAR>C-compiler</VAR></DT>
<DD class="defbody">
Compiler for <CODE>.c</CODE> files found on the command-line. Default is 
the compiler used to build SWI-Prolog accessible through the Prolog flag
<A class="flag" href="flags.html#flag:c_cc">c_cc</A> (Win32: <B>cl.exe</B>)..
</DD>
<DT><STRONG>-c++</STRONG> <VAR>C++-compiler</VAR></DT>
<DD class="defbody">
Compiler for C++ sources (extensions <CODE>.cpp</CODE>, <CODE>.cxx</CODE>,
<CODE>.cc</CODE> or <CODE>.C</CODE>) files found on the command-line. 
Default is
<B>c++</B> or <B>g++</B> if the C-compiler is <B>gcc</B>) (Win32: 
cl.exe).</DD>
<DT><STRONG>-nostate</STRONG> <VAR></VAR></DT>
<DD class="defbody">
Just relink the kernel, do not add any Prolog code to the new kernel. 
This is used to create a new kernel holding additional foreign 
predicates on machines that do not support the shared-library (DLL) 
interface, or if building the state cannot be handled by the default 
procedure used by
<B>swipl-ld</B>. In the latter case the state is created separately and 
appended to the kernel using <CODE>cat &lt;<VAR>kernel</VAR>&gt; &lt;<VAR>state</VAR>&gt; 
&gt; &lt;<VAR>out</VAR>&gt;</CODE> (Win32: <CODE>copy /b &lt;<VAR>kernel</VAR>&gt;+&lt;<VAR>state</VAR>&gt; &lt;<VAR>out</VAR>&gt;</CODE>)</DD>
<DT><STRONG>-shared</STRONG> <VAR></VAR></DT>
<DD class="defbody">
Link C, C++ or object files into a shared object (DLL) that can be 
loaded by the <A NAME="idx:loadforeignlibrary1:1521"></A><A class="pred" href="foreignlink.html#load_foreign_library/1">load_foreign_library/1</A> 
predicate. If used with
<STRONG>-c</STRONG> it sets the proper options to compile a C or C++ 
file ready for linking into a shared object</DD>
<DT><STRONG>-dll</STRONG> <VAR></VAR></DT>
<DD class="defbody">
<EM>Windows only</EM>. Embed SWI-Prolog into a DLL rather than an 
executable.</DD>
<DT><STRONG>-c</STRONG> <VAR></VAR></DT>
<DD class="defbody">
Compile C or C++ source-files into object files. This turns
<B>swipl-ld</B> into a replacement for the C or C++ compiler where 
proper options such as the location of the include directory are passed 
automatically to the compiler.</DD>
<DT><STRONG>-E</STRONG> <VAR></VAR></DT>
<DD class="defbody">
Invoke the C preprocessor. Used to make <B>swipl-ld</B> a replacement 
for the C or C++ compiler.</DD>
<DT><STRONG>-pl-options</STRONG> <VAR>, ...</VAR></DT>
<DD class="defbody">
Additional options passed to Prolog when creating the saved state. The 
first character immediately following <CODE>pl-options</CODE> is used as 
separator and translated to spaces when the argument is built. Example: <CODE>-pl-options,-F,xpce</CODE> 
passed <CODE>-F xpce</CODE> as additional flags to Prolog.
</DD>
<DT><STRONG>-ld-options</STRONG> <VAR>, ...</VAR></DT>
<DD class="defbody">
Passes options to the linker, similar to <STRONG>-pl-options</STRONG>.
</DD>
<DT><STRONG>-cc-options</STRONG> <VAR>, ...</VAR></DT>
<DD class="defbody">
Passes options to the C/C++ compiler, similar to <STRONG>-pl-options</STRONG>.
</DD>
<DT><STRONG>-v</STRONG> <VAR></VAR></DT>
<DD class="defbody">
Select verbose operation, showing the various programs and their 
options.
</DD>
<DT><STRONG>-o</STRONG> <VAR>outfile</VAR></DT>
<DD class="defbody">
Reserved to specify the final output file.
</DD>
<DT><STRONG>-l</STRONG><VAR>library</VAR></DT>
<DD class="defbody">
Specifies a library for the C-compiler. By default, <CODE>-lswipl</CODE> 
(Win32: libpl.lib) and the libraries needed by the Prolog kernel are 
given.
</DD>
<DT><STRONG>-L</STRONG><VAR>library-directory</VAR></DT>
<DD class="defbody">
Specifies a library directory for the C-compiler. By default the 
directory containing the Prolog C-library for the current architecture 
is passed.
</DD>
<DT><STRONG><STRONG>-g</STRONG> | <STRONG>-I<VAR>include-directory</VAR></STRONG> 
| <STRONG>-D<VAR>definition</VAR></STRONG></STRONG> <VAR></VAR></DT>
<DD class="defbody">
These options are passed to the C-compiler. By default, the include 
directory containing <CODE>SWI-Prolog.h</CODE> is passed. <B>swipl-ld</B> 
adds two additional <STRONG>*</STRONG> <VAR>-D</VAR>def flags:

<DL class="latex">
<DT><STRONG>-D</STRONG><VAR><CODE>__SWI_PROLOG__</CODE></VAR></DT>
<DD class="defbody">
Indicates the code is to be connected to SWI-Prolog.
</DD>
<DT><STRONG>-D</STRONG><VAR><CODE>__SWI_EMBEDDED__</CODE></VAR></DT>
<DD class="defbody">
Indicates the creation of an embedded program.
</DD>
</DL>

</DD>
<DT><STRONG></STRONG> <VAR>*.o | *.c | *.C | *.cxx | *.cpp</VAR></DT>
<DD class="defbody">
Passed as input files to the C-compiler
</DD>
<DT><STRONG></STRONG> <VAR>*.pl | *.qlf</VAR></DT>
<DD class="defbody">
Passed as input files to the Prolog compiler to create the saved-state.
</DD>
<DT><STRONG></STRONG> <VAR><CODE>*</CODE></VAR></DT>
<DD class="defbody">
I.e. all other options. These are passed as linker options to the 
C-compiler.
</DD>
</DL>

<H3><A NAME="sec:9.5.1"><SPAN class="sec-nr">9.5.1</SPAN> <SPAN class="sec-title">A 
simple example</SPAN></A></H3>

<P>The following is a very simple example going through all the steps 
outlined above. It provides an arithmetic expression evaluator. We will 
call the application <B>calc</B> and define it in the files <CODE>calc.c</CODE> 
and <CODE>calc.pl</CODE>. The Prolog file is simple:

<PRE class="code">
calc(Atom) :-
        term_to_atom(Expr, Atom),
        A is Expr,
        write(A),
        nl.
</PRE>

<P>The C-part of the application parses the command-line options, 
initialises the Prolog engine, locates the calc/1 predicate and calls 
it. The coder is in <A class="fig" href="plld.html#fig:calc">figure 9</A>.

<PRE class="code">
#include &lt;stdio.h&gt;
#include &lt;SWI-Prolog.h&gt;

#define MAXLINE 1024

int
main(int argc, char **argv)
{ char expression[MAXLINE];
  char *e = expression;
  char *program = argv[0];
  char *plav[2];
  int n;

  /* combine all the arguments in a single string */

  for(n=1; n&lt;argc; n++)
  { if ( n != 1 )
      *e++ = ' ';
    strcpy(e, argv[n]);
    e += strlen(e);
  }

  /* make the argument vector for Prolog */

  plav[0] = program;
  plav[1] = NULL;

  /* initialise Prolog */

  if ( !PL_initialise(1, plav) )
    PL_halt(1);

  /* Lookup calc/1 and make the arguments and call */

  { predicate_t pred = PL_predicate("calc", 1, "user");
    term_t h0 = PL_new_term_refs(1);
    int rval;

    PL_put_atom_chars(h0, expression);
    rval = PL_call_predicate(NULL, PL_Q_NORMAL, pred, h0);

    PL_halt(rval ? 0 : 1);
  }

  return 0;
}
</PRE>

<TABLE ALIGN=center WIDTH="75%"><TR><TD>
<B>Figure 9 : </B>C-source for the calc application</TABLE>

<A NAME="fig:calc"></A>

<P>The application is now created using the following command-line:

<PRE class="code">
% swipl-ld -o calc calc.c calc.pl
</PRE>

<P>The following indicates the usage of the application:

<PRE class="code">
% calc pi/2
1.5708
</PRE>

<P></BODY></HTML>
swi-prolog-nox 5.10.4-3ubuntu1 / usr / lib / swi-prolog / doc / Manual / plld.html
