5b708c0d87fb42438b25522f457c478a23b7bfa8
[scilab.git] / scilab / modules / dynamic_link / help / en_US / ilib_for_link.xml
1 <?xml version="1.0" encoding="UTF-8"?>
2 <!--
3  * Scilab ( http://www.scilab.org/ ) - This file is part of Scilab
4  * Copyright (C) INRIA - 
5  * 
6  * This file must be used under the terms of the CeCILL.
7  * This source file is licensed as described in the file COPYING, which
8  * you should have received as part of this distribution.  The terms
9  * are also available at    
10  * http://www.cecill.info/licences/Licence_CeCILL_V2-en.txt
11  *
12  -->
13 <refentry xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:svg="http://www.w3.org/2000/svg" xmlns:mml="http://www.w3.org/1998/Math/MathML" xmlns:db="http://docbook.org/ns/docbook" version="5.0-subset Scilab" xml:lang="en" xml:id="ilib_for_link">
14   <info>
15     <pubdate>$LastChangedDate: 2008-01-14 16:52:36 +0100 (Mon, 14 Jan 2008) $</pubdate>
16   </info>
17   <refnamediv>
18     <refname>ilib_for_link</refname>
19     <refpurpose> utility for shared library management with link</refpurpose>
20   </refnamediv>
21   <refsynopsisdiv>
22     <title>Calling Sequence</title>
23     <synopsis>libn=ilib_for_link(names,files,libs,flag [,makename [,loadername [,libname [,ldflags [,cflags [,fflags [,cc]]]]]]])</synopsis>
24   </refsynopsisdiv>
25   <refsection>
26     <title>Arguments</title>
27     <variablelist>
28       <varlistentry>
29         <term>names</term>
30         <listitem>
31           <para>a string matrix giving the entry names which are to be linked.</para>
32         </listitem>
33       </varlistentry>
34       <varlistentry>
35         <term>files</term>
36         <listitem>
37           <para>string matrix giving source files needed for shared library creation. Since Scilab 5.3.1, object files are deprecated.</para>
38         </listitem>
39       </varlistentry>
40       <varlistentry>
41         <term>libs</term>
42         <listitem>
43           <para>string matrix giving extra libraries needed for shared library creation</para>
44         </listitem>
45       </varlistentry>
46       <varlistentry>
47         <term>flag</term>
48         <listitem>
49           <para>a string flag ("c" or "f") for C or Fortran entry points.</para>
50         </listitem>
51       </varlistentry>
52       <varlistentry>
53         <term>makename</term>
54         <listitem>
55           <para>character string. The pathname of the Makefile file without extension (default value <literal>Makelib</literal>).</para>
56           <para>This parameter is useless since Scilab 5.0.</para>
57           <para>A warning will be displayed in Scilab 5.3 if you use another value that the default.</para>
58
59         </listitem>
60       </varlistentry>
61       <varlistentry>
62         <term>loadername</term>
63         <listitem>
64           <para>character string. The pathname of the loader file (default
65             value is   <literal>loader.sce</literal>).</para>
66         </listitem>
67       </varlistentry>
68       <varlistentry>
69         <term>libname</term>
70         <listitem>
71           <para>optional character string. The name of the generated shared
72             library (default value  is "", and in this case the name is derived
73             from <literal>names(1)</literal>).</para>
74         </listitem>
75       </varlistentry>
76       <varlistentry>
77         <term>ldflags</term>
78         <listitem>
79           <para>optional character string. It can be used to add specific linker options in the
80             generated Makefile. Default value is ""</para>
81         </listitem>
82       </varlistentry>
83       <varlistentry>
84         <term>cflags</term>
85         <listitem>
86           <para>optional character string. It can be used to add specific C compiler options in the
87             generated Makefile. Default value is ""</para>
88         </listitem>
89       </varlistentry>
90       <varlistentry>
91         <term>fflags</term>
92         <listitem>
93           <para>optional character string. It can be used to add specific Fortran compiler options in the
94             generated Makefile. Default value is ""</para>
95         </listitem>
96       </varlistentry>
97       <varlistentry>
98         <term>cc</term>
99         <listitem>
100           <para>optional character string. It can be used to specify a C compiler. Default value is ""</para>
101         </listitem>
102       </varlistentry>
103       <varlistentry>
104         <term>libn</term>
105         <listitem>
106           <para>character string. The path of the really generated shared library file.</para>
107         </listitem>
108       </varlistentry>
109     </variablelist>
110   </refsection>
111   <refsection>
112     <title>Description</title>
113     <para>
114     This tool is used to create shared libraries and to generate a 
115     loader file which can be used to dynamically load the shared library 
116     into Scilab with the <literal>link</literal> function. New entry points 
117     given by <literal>names</literal> are then accessible through the <literal>call</literal> 
118     function or with non linear tools <literal>ode</literal>, <literal>optim</literal>,...</para>
119     <para>
120     The file to compile are supposed to be located given by
121     <literal>makename</literal>. If <literal>makename</literal> sets a path different to the
122     current directory, <literal>loader</literal> script must be located in
123     the same directory using the <literal>loadername</literal> variable.</para>
124     <para>
125     Many examples are provided in <literal>SCI/modules/dynamic_link/examples</literal>
126     directory. They are all released into the public domain.</para>
127         <para><emphasis role="bold">Note that a compiler must be available on the system to use this function.</emphasis></para>
128         <para><emphasis role="bold">Languages handle by this function are: C, C++, Fortran and Fortran 90.</emphasis></para>
129   </refsection>
130   <refsection>
131     <title>Examples (C code)</title>
132     <programlisting role="example"><![CDATA[ 
133 if haveacompiler() then
134
135 chdir(TMPDIR)
136 f1=['int ext1c(int *n, double *a, double *b, double *c)'
137     '{int k;'
138     '  for (k = 0; k < *n; ++k) '
139     '      c[k] = a[k] + b[k];'
140     '  return(0);}'];
141
142 mputl(f1,'fun1.c')
143
144 //creating the shared library (a gateway, a Makefile and a loader are 
145 //generated. 
146
147 ilib_for_link('ext1c','fun1.c',[],"c") 
148
149 // load the shared library 
150
151 exec loader.sce 
152
153 //using the new primitive
154 a=[1,2,3];b=[4,5,6];n=3;
155 c=call('ext1c',n,1,'i',a,2,'d',b,3,'d','out',[1,3],4,'d');
156 if norm(c-(a+b)) > %eps then pause,end
157
158 end
159  ]]></programlisting>
160   </refsection>
161
162   <refsection role="see also">
163 <title>See Also</title>
164     <simplelist type="inline">
165       <member>
166         <link linkend="addinter">addinter</link>
167       </member>
168       <member>
169         <link linkend="link">link</link>
170       </member>
171       <member>
172         <link linkend="ilib_compile">ilib_compile</link>
173       </member>
174       <member>
175         <link linkend="ilib_gen_Make">ilib_gen_Make</link>
176       </member>
177       <member>
178         <link linkend="ilib_gen_gateway">ilib_gen_gateway</link>
179       </member>
180       <member>
181         <link linkend="ilib_gen_loader">ilib_gen_loader</link>
182       </member>
183       <member>
184         <link linkend="ilib_for_link">ilib_for_link</link>
185       </member>
186       <member><link linkend="api_scilab">api_scilab</link></member>
187     </simplelist>
188   </refsection>
189 </refentry>