[doc] misc. fix & improvements
[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"
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>