summaryrefslogtreecommitdiffstats
path: root/scilab/modules/dynamic_link/help/en_US/ilib_for_link.xml
blob: d0ae845d5a6f2747a866926595fc7d96b0e0da33 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
<?xml version="1.0" encoding="UTF-8"?>
<!--
 * Scilab ( http://www.scilab.org/ ) - This file is part of Scilab
 * Copyright (C) INRIA - 
 * 
 * This file must be used under the terms of the CeCILL.
 * This source file is licensed as described in the file COPYING, which
 * you should have received as part of this distribution.  The terms
 * are also available at    
 * http://www.cecill.info/licences/Licence_CeCILL_V2-en.txt
 *
 -->
<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">
  <info>
    <pubdate>$LastChangedDate: 2008-01-14 16:52:36 +0100 (Mon, 14 Jan 2008) $</pubdate>
  </info>
  <refnamediv>
    <refname>ilib_for_link</refname>
    <refpurpose> utility for shared library management with link</refpurpose>
  </refnamediv>
  <refsynopsisdiv>
    <title>Calling Sequence</title>
    <synopsis>libn=ilib_for_link(names,files,libs,flag [,makename [,loadername [,libname [,ldflags [,cflags [,fflags [,cc]]]]]]])</synopsis>
  </refsynopsisdiv>
  <refsection>
    <title>Arguments</title>
    <variablelist>
      <varlistentry>
        <term>names</term>
        <listitem>
          <para>a string matrix giving the entry names which are to be linked.</para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term>files</term>
        <listitem>
          <para>string matrix giving source files needed for shared library creation. Since Scilab 5.3.1, object files are deprecated.</para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term>libs</term>
        <listitem>
          <para>string matrix giving extra libraries needed for shared library creation</para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term>flag</term>
        <listitem>
          <para>a string flag ("c" or "f") for C or Fortran entry points.</para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term>makename</term>
        <listitem>
          <para>character string. The pathname of the Makefile file without extension (default value <literal>Makelib</literal>).</para>
          <para>This parameter is useless since Scilab 5.0.</para>
          <para>A warning will be displayed in Scilab 5.3 if you use another value that the default.</para>

        </listitem>
      </varlistentry>
      <varlistentry>
        <term>loadername</term>
        <listitem>
          <para>character string. The pathname of the loader file (default
	    value is   <literal>loader.sce</literal>).</para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term>libname</term>
        <listitem>
          <para>optional character string. The name of the generated shared
	    library (default value  is "", and in this case the name is derived
	    from <literal>names(1)</literal>).</para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term>ldflags</term>
        <listitem>
          <para>optional character string. It can be used to add specific linker options in the
	    generated Makefile. Default value is ""</para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term>cflags</term>
        <listitem>
          <para>optional character string. It can be used to add specific C compiler options in the
	    generated Makefile. Default value is ""</para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term>fflags</term>
        <listitem>
          <para>optional character string. It can be used to add specific Fortran compiler options in the
	    generated Makefile. Default value is ""</para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term>cc</term>
        <listitem>
          <para>optional character string. It can be used to specify a C compiler. Default value is ""</para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term>libn</term>
        <listitem>
          <para>character string. The path of the really generated shared library file.</para>
        </listitem>
      </varlistentry>
    </variablelist>
  </refsection>
  <refsection>
    <title>Description</title>
    <para>
    This tool is used to create shared libraries and to generate a 
    loader file which can be used to dynamically load the shared library 
    into Scilab with the <literal>link</literal> function. New entry points 
    given by <literal>names</literal> are then accessible through the <literal>call</literal> 
    function or with non linear tools <literal>ode</literal>, <literal>optim</literal>,...</para>
    <para>
    The file to compile are supposed to be located given by
    <literal>makename</literal>. If <literal>makename</literal> sets a path different to the
    current directory, <literal>loader</literal> script must be located in
    the same directory using the <literal>loadername</literal> variable.</para>
    <para>
    Many examples are provided in <literal>SCI/modules/dynamic_link/examples</literal>
    directory. They are all released into the public domain.</para>
	<para><emphasis role="bold">Note that a compiler must be available on the system to use this function.</emphasis></para>
	<para><emphasis role="bold">Languages handle by this function are: C, C++, Fortran and Fortran 90.</emphasis></para>

    <para>On the internal technical level, under GNU/Linux and Mac OS X, the ilib_* function are based on the autotools. First, a configure is executed to detect compilers available. Then, a make is launched with the provided arguments. For more information: <ulink url="http://wiki.scilab.org/Full%20technical%20description%20of%20the%20incremental%20link">Full technical description of the incremental link / dynamic link</ulink></para>

    <para>Since version 5.3.2, under GNU/Linux, Scilab detects where the libstdc++ is located (thanks to the command <emphasis role="italic">gcc -print-search-dirs|grep ^install:|awk '{print $2}'</emphasis>). Previously, the dynamic link was using the libstdc++ embedded in Scilab.</para>

  </refsection>
  <refsection>
    <title>Examples (C code)</title>
    <programlisting role="example"><![CDATA[ 
if haveacompiler() then

chdir(TMPDIR)
f1=['int ext1c(int *n, double *a, double *b, double *c)'
    '{int k;'
    '  for (k = 0; k < *n; ++k) '
    '      c[k] = a[k] + b[k];'
    '  return(0);}'];

mputl(f1,'fun1.c')

//creating the shared library (a gateway, a Makefile and a loader are 
//generated. 

ilib_for_link('ext1c','fun1.c',[],"c") 

// load the shared library 

exec loader.sce 

//using the new primitive
a=[1,2,3];b=[4,5,6];n=3;
c=call('ext1c',n,1,'i',a,2,'d',b,3,'d','out',[1,3],4,'d');
if norm(c-(a+b)) > %eps then pause,end

end
 ]]></programlisting>
  </refsection>

  <refsection role="see also">
<title>See Also</title>
    <simplelist type="inline">
      <member>
        <link linkend="addinter">addinter</link>
      </member>
      <member>
        <link linkend="link">link</link>
      </member>
      <member>
        <link linkend="ilib_compile">ilib_compile</link>
      </member>
      <member>
        <link linkend="ilib_gen_Make">ilib_gen_Make</link>
      </member>
      <member>
        <link linkend="ilib_gen_gateway">ilib_gen_gateway</link>
      </member>
      <member>
        <link linkend="ilib_gen_loader">ilib_gen_loader</link>
      </member>
      <member>
        <link linkend="ilib_for_link">ilib_for_link</link>
      </member>
      <member><link linkend="api_scilab">api_scilab</link></member>
    </simplelist>
  </refsection>
</refentry>