* Bug 14098 [doc]: genlib() and library pages updated for Scilab 6
[scilab.git] / scilab / modules / functions / help / en_US / libraries / genlib.xml
index 8ce385b..bb6e0ee 100644 (file)
@@ -2,8 +2,8 @@
 <!--
  * Scilab ( http://www.scilab.org/ ) - This file is part of Scilab
  * Copyright (C) ????-2008 - INRIA
- *
  * Copyright (C) 2012 - 2016 - Scilab Enterprises
+ * Copyright (C) 2021 - Samuel GOUGEON
  *
  * This file is hereby licensed under the terms of the GNU GPL v2.0,
  * pursuant to article 5.3.4 of the CeCILL v.2.1.
  * For more information, see the COPYING file which you should have received
  * along with this program.
  *
- -->
-<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" xmlns:scilab="http://www.scilab.org" xml:lang="en" xml:id="genlib">
+-->
+<refentry xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink"
+          xmlns:svg="http://www.w3.org/2000/svg" xmlns:db="http://docbook.org/ns/docbook"
+          xmlns:scilab="http://www.scilab.org" xml:lang="en" xml:id="genlib">
     <refnamediv>
         <refname>genlib</refname>
-        <refpurpose>build library from functions in given directory</refpurpose>
+        <refpurpose>
+            builds a library from a set of *.sci files defining functions in a given directory
+        </refpurpose>
     </refnamediv>
     <refsynopsisdiv>
         <title>Syntax</title>
-        <synopsis>genlib(lib_name [[,dir_name, [ Force [,verb [,Names]]]])
-            genlib(lib_name [,path=dir_name] [,verbose=verb] [,force=Force] [,names=Names])
+        <synopsis>
+            genlib(lib_name)
+            genlib(lib_name, dir_name)
+            genlib(lib_name, dir_name, Force)
+            genlib(lib_name, dir_name, Force, verb)
+            genlib(lib_name [,path=dir_name] [,verbose=verb] [,force=Force])
         </synopsis>
     </refsynopsisdiv>
     <refsection>
         <title>Arguments</title>
         <variablelist>
             <varlistentry>
-                <term>lib_name:  </term>
+                <term>lib_name</term>
                 <listitem>
-                    <para>Scilab string.  The variable name of the library to (re)create.</para>
+                    Scilab string:  The identifying name ascribed to the library to build.
+                    <para/>
                 </listitem>
             </varlistentry>
             <varlistentry>
-                <term>dir_name:  </term>
+                <term>dir_name</term>
                 <listitem>
-                    <para>Scilab string.  The name of the directory to look for
-                        <literal>.sci</literal>-files.
-                    </para>
+                    Scilab string:  The pathname of the directory containing
+                    <literal>.sci</literal> functions files, and where the <literal>lib</literal>
+                    file generated and defining the library will be stored.
+                    By default, the current working directory is considered.
+                    <warning>
+                        The <varname>dir_name</varname> directory and its <literal>lib</literal>
+                        and <literal>.bin</literal> files must be writable.
+                    </warning>
+                    <para/>
                 </listitem>
             </varlistentry>
             <varlistentry>
                 <term>Force</term>
                 <listitem>
-                    <para>
-                        boolean value (default value is <literal>%f</literal>). Set it to
-                        <literal>%t</literal> to force the sci-files recompilation.
-                    </para>
+                    boolean value (default value is <literal>%f</literal>). Set it to
+                    <literal>%t</literal> to force the sci-files recompilation.
+                    <para/>
                 </listitem>
             </varlistentry>
             <varlistentry>
                 <term>verb</term>
                 <listitem>
-                    <para>
-                        boolean values (default value is <literal>%f</literal>). Set it to
-                        <literal>%t</literal> to get information.
-                    </para>
-                </listitem>
-            </varlistentry>
-            <varlistentry>
-                <term>Names</term>
-                <listitem>
-                    <para>a vector of strings, the names of function to include in the
-                        library. By default all the sci-files are taken into account
-                    </para>
+                    boolean value (default value is <literal>%f</literal>). Set it to
+                    <literal>%t</literal> to display more information during the build.
+                    <para/>
                 </listitem>
             </varlistentry>
         </variablelist>
     <refsection>
         <title>Description</title>
         <para>
-            For each <literal>.sci</literal> file in <literal>dir_name</literal> (or only those
-            specified by the <literal>Names</literal> argument), <literal>genlib</literal> executes a
-            <literal>exec</literal> and saves the functions to the corresponding <literal>.bin</literal>
-            file.  The <literal>.sci</literal> file must not contain anything but Scilab
-            functions.  If a <literal>.bin</literal> file is newer than the associated
-            <literal>.sci</literal> file, <literal>genlib</literal> does not translate and save the file.
+            <literal>genlib(..)</literal> selects all files belonging to the
+            <varname>dir_name</varname> directory and with the <literal>.sci</literal> extension.
+            If any, subdirectories are never considered. If it is required, they must be compiled
+            apart into independent libraries.
+        </para>
+        <para>
+            Then, an XML editable file named <literal>lib</literal> is created in the
+            <varname>dir_name</varname> directory. The name <varname>lib_name</varname>
+            of the library is recorded into it.
         </para>
         <para>
-            This default behaviour can be changed if <literal>force</literal> is given and
-            set to <literal>%t</literal>. In this latter case the recompilation is always
-            performed for each <literal>.sci</literal> file.
+            Then, for each <literal>.sci</literal> file:
+            <itemizedlist>
+                <listitem>
+                    If
+                    <itemizedlist>
+                        <listitem>
+                            there is no related <literal>.bin</literal> file in <varname>dir_name</varname>
+                            with the same basename (as for the initial build of the library), or
+                        </listitem>
+                        <listitem>
+                            the content of the <literal>.sci</literal> file has changed since
+                            the previous build,
+                        </listitem>
+                    </itemizedlist>
+                    <para/>
+                    <para>
+                        the <literal>.sci</literal> file is compiled (<emphasis>almost</emphasis>
+                        as it would be with <literal>exec(..)</literal>):
+                        <itemizedlist>
+                            <listitem>
+                                <para>
+                                    If it contains at least one <literal>function .. endfunction</literal>
+                                    block, a <literal>.bin</literal> binary file with the same basename
+                                    is generated and stored in <varname>dir_name</varname>.
+                                    It contains the binary code of ALL functions defined in the
+                                    <literal>.sci</literal> source file.
+                                    <itemizedlist>
+                                        <listitem>
+                                            If the name of one of the function(s) defined in the
+                                            file is the basename of the <literal>.sci</literal>
+                                            file, this function is registered in the
+                                            <literal>lib</literal> file.
+                                            <para/>
+                                        </listitem>
+                                        <listitem>
+                                            Otherwise, no function from the <literal>.sci</literal>
+                                            file is registered: Its whole content is considered as
+                                            dead code.
+                                        </listitem>
+                                    </itemizedlist>
+                                </para>
+                                <para>
+                                    <warning>
+                                        If a <literal>test.sci</literal> file defines the
+                                        <literal>test()</literal> function AND other functions like
+                                        sub(), sub() functions are then considered as private to
+                                        test(). For instance,
+                                        <table>
+                                            <tr>
+                                                <td>
+                                                    <screen>
+function r = sub(a)
+    r = 2*a
+endfunction
+
+function test()
+    disp("A test")
+endfunction
+
+function r = other(b)
+    r = 2^b
+endfunction
+</screen>
+                                                </td>
+                                                <td>
+                                                    is equivalent to
+                                                </td>
+                                                <td>
+                                                    <screen>
+function test()
+    function r = sub(a)
+        r = 2*a
+    endfunction
+    function r = other(b)
+        r = 2^b
+    endfunction
+
+    disp("A test")
+endfunction
+</screen>
+                                                </td>
+                                            </tr>
+                                        </table>
+                                        Hence, sub() and other() won't exist out of test(), and
+                                        won't be registered in the library.
+                                    </warning>
+                                </para>
+                            </listitem>
+                            <listitem>
+                                Otherwise, no <literal>.bin</literal> file is generated: The whole
+                                content of the <literal>.sci</literal> file is considered as dead code.
+                            </listitem>
+                        </itemizedlist>
+                    </para>
+                </listitem>
+                <listitem>
+                    Otherwise: If the file's content has not changed and has already a function
+                    entry in the <literal>lib</literal> file, this entry is kept.
+                </listitem>
+            </itemizedlist>
         </para>
         <para>
-            When all <literal>.sci</literal> files have been processed, <literal>genlib</literal> creates a
-            library variable named <literal>lib_name</literal> and saves it in the file
-            <literal>lib</literal> in <literal>dir_name</literal>. If the Scilab variable
-            <literal>lib_name</literal> is not protected (see <link linkend="predef">predef</link>) this
-            variable is updated.
+            Finally, <literal>genlib(..)</literal> loads the created or updated library and sets
+            its identifier to a variable named <varname>lib_name</varname>, in the current scope.
+            If the variable <varname>lib_name</varname> already exists and is protected,
+            an error occurs: The library has been created but can't be loaded
+            (<link linkend="predef">predef all</link> can be used to unprotect the variable
+            named <varname>lib_name</varname> before running <literal>genlib(..)</literal>).
         </para>
         <para>
-            If <literal>verbose</literal> is et to <literal>%t</literal> information are displayed during
-            the build process.
+            If the option <literal>force=%t</literal> is used, all <literal>.sci</literal> files
+            are compiled, even if their content has not changed.
         </para>
         <para>
-            If <literal>dir_name</literal> argument is not given and if <literal>lib_name</literal>
-            Scilab variable  exists and it is a library dir_name is taken equal to the
-            <literal>lib_name</literal> library path (update mode).
+            When in the directory of a library some former .sci files have been removed while
+            all remaining .sci files are unchanged, rebuilding the library without the
+            <literal>force=%t</literal> will anyway update the list of library's members.
         </para>
-    </refsection>
-    <refsection>
-        <title>Restrictions</title>
         <para>
-            Scilab tacitly assumes that file <literal>foo.sci</literal> defines at least a
-            function named <literal>foo</literal>. If subsidiary functions are included,
-            they are made known to Scilab only after the function <literal>foo</literal>
-            had been referenced.
+            If the option <literal>verbose</literal> is true, more information is displayed during
+            the build process.
         </para>
     </refsection>
     <refsection role="see also">
         <title>See also</title>
         <simplelist type="inline">
             <member>
-                <link linkend="getd">getd</link>
+                <link linkend="library">library</link>
             </member>
             <member>
-                <link linkend="exec">exec</link>
+                <link linkend="load">load</link>
             </member>
             <member>
-                <link linkend="save">save</link>
+                <link linkend="getd">getd</link>
             </member>
             <member>
                 <link linkend="lib">lib</link>
             </member>
         </simplelist>
     </refsection>
+    <refsection role="history">
+        <title>History</title>
+        <revhistory>
+            <revision>
+                <revnumber>6.0.0</revnumber>
+                <revdescription>
+                    <itemizedlist>
+                        <listitem>
+                            The file <literal>names</literal> is no longer required.
+                            The <literal>Names</literal> option is removed.
+                        </listitem>
+                        <listitem>
+                            When a .sci file contains functions not named accordingly with the
+                            file name, they are no longer public: They are visible and callable only
+                            from the main function.
+                        </listitem>
+                        <listitem>
+                            When a library named <varname>lib_name</varname> is already loaded, the
+                            default <varname>dir_name</varname> directory is no longer its
+                            directory (update mode), but always the current working one.
+                        </listitem>
+                        <listitem>
+                            The generated <literal>lib</literal> file is now a human-readable XML
+                            file, instead of a binary.
+                        </listitem>
+                        <listitem>
+                            genlib() can no longer register any variable as full member of a library.
+                        </listitem>
+                        <listitem>
+                            By default, any .sci file is now recompiled if its content has
+                            changed, no longer if its modification date is newer than the .bin's one.
+                        </listitem>
+                        <listitem>
+                            The generated <literal>.bin</literal> files can no longer be loaded
+                            independently with load().
+                        </listitem>
+                    </itemizedlist>
+                </revdescription>
+            </revision>
+        </revhistory>
+    </refsection>
 </refentry>