* Bug 14098 [doc]: genlib() and library pages updated for Scilab 6
[scilab.git] / scilab / modules / functions / help / en_US / libraries / genlib.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) ????-2008 - INRIA
5  * Copyright (C) 2012 - 2016 - Scilab Enterprises
6  * Copyright (C) 2021 - Samuel GOUGEON
7  *
8  * This file is hereby licensed under the terms of the GNU GPL v2.0,
9  * pursuant to article 5.3.4 of the CeCILL v.2.1.
10  * This file was originally licensed under the terms of the CeCILL v2.1,
11  * and continues to be available under such terms.
12  * For more information, see the COPYING file which you should have received
13  * along with this program.
14  *
15 -->
16 <refentry xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink"
17           xmlns:svg="http://www.w3.org/2000/svg" xmlns:db="http://docbook.org/ns/docbook"
18           xmlns:scilab="http://www.scilab.org" xml:lang="en" xml:id="genlib">
19     <refnamediv>
20         <refname>genlib</refname>
21         <refpurpose>
22             builds a library from a set of *.sci files defining functions in a given directory
23         </refpurpose>
24     </refnamediv>
25     <refsynopsisdiv>
26         <title>Syntax</title>
27         <synopsis>
28             genlib(lib_name)
29             genlib(lib_name, dir_name)
30             genlib(lib_name, dir_name, Force)
31             genlib(lib_name, dir_name, Force, verb)
32             genlib(lib_name [,path=dir_name] [,verbose=verb] [,force=Force])
33         </synopsis>
34     </refsynopsisdiv>
35     <refsection>
36         <title>Arguments</title>
37         <variablelist>
38             <varlistentry>
39                 <term>lib_name</term>
40                 <listitem>
41                     Scilab string:  The identifying name ascribed to the library to build.
42                     <para/>
43                 </listitem>
44             </varlistentry>
45             <varlistentry>
46                 <term>dir_name</term>
47                 <listitem>
48                     Scilab string:  The pathname of the directory containing
49                     <literal>.sci</literal> functions files, and where the <literal>lib</literal>
50                     file generated and defining the library will be stored.
51                     By default, the current working directory is considered.
52                     <warning>
53                         The <varname>dir_name</varname> directory and its <literal>lib</literal>
54                         and <literal>.bin</literal> files must be writable.
55                     </warning>
56                     <para/>
57                 </listitem>
58             </varlistentry>
59             <varlistentry>
60                 <term>Force</term>
61                 <listitem>
62                     boolean value (default value is <literal>%f</literal>). Set it to
63                     <literal>%t</literal> to force the sci-files recompilation.
64                     <para/>
65                 </listitem>
66             </varlistentry>
67             <varlistentry>
68                 <term>verb</term>
69                 <listitem>
70                     boolean value (default value is <literal>%f</literal>). Set it to
71                     <literal>%t</literal> to display more information during the build.
72                     <para/>
73                 </listitem>
74             </varlistentry>
75         </variablelist>
76     </refsection>
77     <refsection>
78         <title>Description</title>
79         <para>
80             <literal>genlib(..)</literal> selects all files belonging to the
81             <varname>dir_name</varname> directory and with the <literal>.sci</literal> extension.
82             If any, subdirectories are never considered. If it is required, they must be compiled
83             apart into independent libraries.
84         </para>
85         <para>
86             Then, an XML editable file named <literal>lib</literal> is created in the
87             <varname>dir_name</varname> directory. The name <varname>lib_name</varname>
88             of the library is recorded into it.
89         </para>
90         <para>
91             Then, for each <literal>.sci</literal> file:
92             <itemizedlist>
93                 <listitem>
94                     If
95                     <itemizedlist>
96                         <listitem>
97                             there is no related <literal>.bin</literal> file in <varname>dir_name</varname>
98                             with the same basename (as for the initial build of the library), or
99                         </listitem>
100                         <listitem>
101                             the content of the <literal>.sci</literal> file has changed since
102                             the previous build,
103                         </listitem>
104                     </itemizedlist>
105                     <para/>
106                     <para>
107                         the <literal>.sci</literal> file is compiled (<emphasis>almost</emphasis>
108                         as it would be with <literal>exec(..)</literal>):
109                         <itemizedlist>
110                             <listitem>
111                                 <para>
112                                     If it contains at least one <literal>function .. endfunction</literal>
113                                     block, a <literal>.bin</literal> binary file with the same basename
114                                     is generated and stored in <varname>dir_name</varname>.
115                                     It contains the binary code of ALL functions defined in the
116                                     <literal>.sci</literal> source file.
117                                     <itemizedlist>
118                                         <listitem>
119                                             If the name of one of the function(s) defined in the
120                                             file is the basename of the <literal>.sci</literal>
121                                             file, this function is registered in the
122                                             <literal>lib</literal> file.
123                                             <para/>
124                                         </listitem>
125                                         <listitem>
126                                             Otherwise, no function from the <literal>.sci</literal>
127                                             file is registered: Its whole content is considered as
128                                             dead code.
129                                         </listitem>
130                                     </itemizedlist>
131                                 </para>
132                                 <para>
133                                     <warning>
134                                         If a <literal>test.sci</literal> file defines the
135                                         <literal>test()</literal> function AND other functions like
136                                         sub(), sub() functions are then considered as private to
137                                         test(). For instance,
138                                         <table>
139                                             <tr>
140                                                 <td>
141                                                     <screen>
142 function r = sub(a)
143     r = 2*a
144 endfunction
145
146 function test()
147     disp("A test")
148 endfunction
149
150 function r = other(b)
151     r = 2^b
152 endfunction
153 </screen>
154                                                 </td>
155                                                 <td>
156                                                     is equivalent to
157                                                 </td>
158                                                 <td>
159                                                     <screen>
160 function test()
161     function r = sub(a)
162         r = 2*a
163     endfunction
164     function r = other(b)
165         r = 2^b
166     endfunction
167
168     disp("A test")
169 endfunction
170 </screen>
171                                                 </td>
172                                             </tr>
173                                         </table>
174                                         Hence, sub() and other() won't exist out of test(), and
175                                         won't be registered in the library.
176                                     </warning>
177                                 </para>
178                             </listitem>
179                             <listitem>
180                                 Otherwise, no <literal>.bin</literal> file is generated: The whole
181                                 content of the <literal>.sci</literal> file is considered as dead code.
182                             </listitem>
183                         </itemizedlist>
184                     </para>
185                 </listitem>
186                 <listitem>
187                     Otherwise: If the file's content has not changed and has already a function
188                     entry in the <literal>lib</literal> file, this entry is kept.
189                 </listitem>
190             </itemizedlist>
191         </para>
192         <para>
193             Finally, <literal>genlib(..)</literal> loads the created or updated library and sets
194             its identifier to a variable named <varname>lib_name</varname>, in the current scope.
195             If the variable <varname>lib_name</varname> already exists and is protected,
196             an error occurs: The library has been created but can't be loaded
197             (<link linkend="predef">predef all</link> can be used to unprotect the variable
198             named <varname>lib_name</varname> before running <literal>genlib(..)</literal>).
199         </para>
200         <para>
201             If the option <literal>force=%t</literal> is used, all <literal>.sci</literal> files
202             are compiled, even if their content has not changed.
203         </para>
204         <para>
205             When in the directory of a library some former .sci files have been removed while
206             all remaining .sci files are unchanged, rebuilding the library without the
207             <literal>force=%t</literal> will anyway update the list of library's members.
208         </para>
209         <para>
210             If the option <literal>verbose</literal> is true, more information is displayed during
211             the build process.
212         </para>
213     </refsection>
214     <refsection role="see also">
215         <title>See also</title>
216         <simplelist type="inline">
217             <member>
218                 <link linkend="library">library</link>
219             </member>
220             <member>
221                 <link linkend="load">load</link>
222             </member>
223             <member>
224                 <link linkend="getd">getd</link>
225             </member>
226             <member>
227                 <link linkend="lib">lib</link>
228             </member>
229         </simplelist>
230     </refsection>
231     <refsection role="history">
232         <title>History</title>
233         <revhistory>
234             <revision>
235                 <revnumber>6.0.0</revnumber>
236                 <revdescription>
237                     <itemizedlist>
238                         <listitem>
239                             The file <literal>names</literal> is no longer required.
240                             The <literal>Names</literal> option is removed.
241                         </listitem>
242                         <listitem>
243                             When a .sci file contains functions not named accordingly with the
244                             file name, they are no longer public: They are visible and callable only
245                             from the main function.
246                         </listitem>
247                         <listitem>
248                             When a library named <varname>lib_name</varname> is already loaded, the
249                             default <varname>dir_name</varname> directory is no longer its
250                             directory (update mode), but always the current working one.
251                         </listitem>
252                         <listitem>
253                             The generated <literal>lib</literal> file is now a human-readable XML
254                             file, instead of a binary.
255                         </listitem>
256                         <listitem>
257                             genlib() can no longer register any variable as full member of a library.
258                         </listitem>
259                         <listitem>
260                             By default, any .sci file is now recompiled if its content has
261                             changed, no longer if its modification date is newer than the .bin's one.
262                         </listitem>
263                         <listitem>
264                             The generated <literal>.bin</literal> files can no longer be loaded
265                             independently with load().
266                         </listitem>
267                     </itemizedlist>
268                 </revdescription>
269             </revision>
270         </revhistory>
271     </refsection>
272 </refentry>