45deba54848770d86a14347ec5f6c5f74029b115
[scilab.git] / 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>