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>