scilab/modules/modules_manager/help/en_US/sections_builders/tbx_builder_macros.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  * Copyright (C) 2016 - Scilab Enterprises - Pierre-Aime AGNEL
   6  * Copyright (C) 2016 - Samuel GOUGEON
   7  *
   8  * Copyright (C) 2012 - 2016 - Scilab Enterprises
   9  *
  10  * This file is hereby licensed under the terms of the GNU GPL v2.0,
  11  * pursuant to article 5.3.4 of the CeCILL v.2.1.
  12  * This file was originally licensed under the terms of the CeCILL v2.1,
  13  * and continues to be available under such terms.
  14  * For more information, see the COPYING file which you should have received
  15  * along with this program.
  16  *
  17  -->
  18 <refentry xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink"
  19           xmlns:svg="http://www.w3.org/2000/svg" xmlns:ns5="http://www.w3.org/1999/xhtml"
  20           xmlns:mml="http://www.w3.org/1998/Math/MathML" xmlns:db="http://docbook.org/ns/docbook"
  21           xmlns:scilab="http://www.scilab.org" xml:id="tbx_builder_macros" xml:lang="en">
  22     <refnamediv>
  23         <refname>tbx_builder_macros</refname>
  24         <refpurpose>Create library(es) of a toolbox for its functions in Scilab language</refpurpose>
  25     </refnamediv>
  26
  27     <refsynopsisdiv>
  28         <title>Syntax</title>
  29         <synopsis>
  30             tbx_builder_macros(toolbox_path)
  31         </synopsis>
  32     </refsynopsisdiv>
  33
  34     <refsection role="parameters">
  35         <title>Arguments</title>
  36         <variablelist>
  37             <varlistentry>
  38                 <term>toolbox_path</term>
  39                 <listitem>
  40                     <para>
  41                       Root directory of the toolbox. build script will be searched in
  42                       the <varname>toolbox_path</varname><literal>/macros</literal> subdirectory.
  43                     </para>
  44                 </listitem>
  45             </varlistentry>
  46         </variablelist>
  47     </refsection>
  48
  49     <refsection role="description">
  50         <title>Description</title>
  51         <para>
  52             This function is usually called by <literal>tbx_make(..)</literal> or called from
  53             <literal>builder.sce</literal> scripts, when creating or updating a toolbox.
  54         </para>
  55         <warning>
  56           The short name (id) <literal>tbx_name</literal> of the toolbox is retrieved as the basename
  57           of the file <literal>toolbox_path/etc/*.start</literal>. This file must exists,
  58           even if it is empty.
  59        </warning>
  60         <para>
  61             <function>tbx_builder_macros</function> scans the <literal>toolbox_path</literal>
  62             directory for a <literal>macros</literal> subdirectory.
  63             <itemizedlist>
  64               <listitem>
  65                 If <literal>macros</literal> is found, <function>tbx_builder_macros</function>
  66                 looks for a script <literal>*.sce</literal> whose name starts with <literal>build</literal>:
  67                 <itemizedlist>
  68                   <listitem>
  69                      If a <literal>toolbox/macros/build*.sce</literal> file is found,
  70                      <function>tbx_builder_macros</function> executes it, and that's it.
  71                   </listitem>
  72                   <listitem>
  73                     Otherwise,
  74                     <function>tbx_builder_macros</function> compiles each <literal>thisfile.sci</literal>
  75                     file found in the <literal>toolbox_path/macros/</literal> subdirectory, and yields
  76                     every related <literal>thisfile.bin</literal> binary files.
  77                     All these <literal>*.bin</literal> are then bundled into a library of macros recorded
  78                     in the file <literal>toolbox_path/macros/lib</literal>.
  79                   </listitem>
  80               </itemizedlist>
  81               </listitem>
  82               <listitem>
  83                  Otherwise, <function>tbx_builder_macros</function> exits silently.
  84               </listitem>
  85             </itemizedlist>
  86         </para>
  87         <para>
  88            When a library is actually built, its default name is set to <literal>tbx_namelib</literal>,
  89           in the <literal>toolbox_path/macros/lib</literal> file.
  90         </para>
  91     </refsection>
  92
  93     <refsection role="examples">
  94         <title>Examples</title>
  95         <programlisting role="no-scilab-exec"><![CDATA[
  96 // Recommended usage, from a builder.sce script
  97 tbx_builder_macros(get_absolute_file_path('builder.sce'))
  98  ]]></programlisting>
  99     </refsection>
 100
 101     <refsection role="see also">
 102         <title>See Also</title>
 103         <simplelist type="inline">
 104             <member>
 105                 <link linkend="tbx_make">tbx_make</link>
 106             </member>
 107         </simplelist>
 108     </refsection>
 109
 110     <refsection role="history">
 111         <title>History</title>
 112         <revhistory>
 113             <revision>
 114                 <revnumber>6.0.0</revnumber>
 115                 <revremark>
 116                     <para>
 117                         A default behaviour generating a lib from all macros inside the
 118                         <literal>macros</literal> directory is now implemented.
 119                         An explicit builder script is no longer mandatory.
 120                     </para>
 121                     <para>
 122                         No longer restricts the build scripts to buildmacros.sce.
 123                         Now any scripts called buildmacros*.sce or builder*.sce are valid
 124                         for macros generation.
 125                     </para>
 126                 </revremark>
 127             </revision>
 128         </revhistory>
 129     </refsection>
 130
 131 </refentry>