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" xmlns:svg="http://www.w3.org/2000/svg" xmlns:ns5="http://www.w3.org/1999/xhtml" xmlns:mml="http://www.w3.org/1998/Math/MathML" xmlns:db="http://docbook.org/ns/docbook" xmlns:scilab="http://www.scilab.org" xml:id="tbx_builder_macros" xml:lang="en">
  19     <refnamediv>
  20         <refname>tbx_builder_macros</refname>
  21         <refpurpose>Create library(es) of a toolbox for its functions in Scilab language</refpurpose>
  22     </refnamediv>
  23
  24     <refsynopsisdiv>
  25         <title>Syntax</title>
  26         <synopsis>
  27             tbx_builder_macros(toolbox_path)
  28         </synopsis>
  29     </refsynopsisdiv>
  30
  31     <refsection role="parameters">
  32         <title>Arguments</title>
  33         <variablelist>
  34             <varlistentry>
  35                 <term>toolbox_path</term>
  36                 <listitem>
  37                     <para>
  38                       Root directory of the toolbox. build script will be searched in
  39                       the <varname>toolbox_path</varname><literal>/macros</literal> subdirectory.
  40                     </para>
  41                 </listitem>
  42             </varlistentry>
  43         </variablelist>
  44     </refsection>
  45
  46     <refsection role="description">
  47         <title>Description</title>
  48         <para>
  49             This function is usually called from <literal>builder.sce</literal> scripts when
  50             creating or updating a toolbox.
  51         </para>
  52         <warning>
  53           The short name (id) <literal>tbx_name</literal> of the toolbox is retrieved as the basename
  54           of the file <literal>toolbox_path/etc/*.start</literal>. This file must exists,
  55           even if it is empty.
  56        </warning>
  57         <para>
  58             <function>tbx_builder_macros</function> scans the <literal>toolbox_path</literal>
  59             directory for a <literal>macros</literal> subdirectory.
  60             <itemizedlist>
  61               <listitem>
  62                 If <literal>macros</literal> is found, <function>tbx_builder_macros</function>
  63                 looks for a script <literal>*.sce</literal> whose name starts with <literal>build</literal>:
  64                 <itemizedlist>
  65                   <listitem>
  66                      If a <literal>toolbox/macros/build*.sce</literal> file is found,
  67                      <function>tbx_builder_macros</function> executes it, and that's it.
  68                   </listitem>
  69                   <listitem>
  70                     Otherwise,
  71                     <function>tbx_builder_macros</function> compiles each <literal>thisfile.sci</literal>
  72                     file found in the <literal>toolbox_path/macros/</literal> subdirectory, and yields
  73                     every related <literal>thisfile.bin</literal> binary files.
  74                     All these <literal>*.bin</literal> are then bundled into a library of macros recorded
  75                     in the file <literal>toolbox_path/macros/lib</literal>.
  76                   </listitem>
  77               </itemizedlist>
  78               </listitem>
  79               <listitem>
  80                  Otherwise, <function>tbx_builder_macros</function> exists silently.
  81               </listitem>
  82             </itemizedlist>
  83         </para>
  84         <para>
  85            When a library is actually built, its default name is set to <literal>tbx_namelib</literal>,
  86           in the <literal>toolbox_path/macros/lib</literal> file.
  87         </para>
  88     </refsection>
  89
  90     <refsection role="examples">
  91         <title>Examples</title>
  92         <programlisting role="no-scilab-exec"><![CDATA[
  93 // Recommended usage, from a builder.sce script
  94 tbx_builder_macros(get_absolute_file_path('builder.sce'))
  95  ]]></programlisting>
  96     </refsection>
  97
  98     <refsection role="history">
  99         <title>History</title>
 100         <revhistory>
 101             <revision>
 102                 <revnumber>6.0.0</revnumber>
 103                 <revremark>
 104                     <para>
 105                         A default behaviour generating a lib from all macros inside the
 106                         <literal>macros</literal> directory is now implemented.
 107                         An explicit builder script is no longer mandatory.
 108                     </para>
 109                     <para>
 110                         No longer restricts the build scripts to buildmacros.sce.
 111                         Now any scripts called buildmacros*.sce or builder*.sce are valid
 112                         for macros generation.
 113                     </para>
 114                 </revremark>
 115             </revision>
 116         </revhistory>
 117     </refsection>
 118
 119 </refentry>