summaryrefslogtreecommitdiffstats
path: root/scilab_doc
diff options
context:
space:
mode:
authorFarid Belahcene <farid.belahcene@inria.fr>2006-08-31 13:54:44 +0000
committerFarid Belahcene <farid.belahcene@inria.fr>2006-08-31 13:54:44 +0000
commit3c6c4a582130aba9bcd87608b98616ce49b4be04 (patch)
tree734946b61caf65338d6c4d660fd51d8404792aa6 /scilab_doc
parente998f98caabd8b705f4078cddc6d7ba66449a5c7 (diff)
downloadscilab-3c6c4a582130aba9bcd87608b98616ce49b4be04.zip
scilab-3c6c4a582130aba9bcd87608b98616ce49b4be04.tar.gz
New modifications
Diffstat (limited to 'scilab_doc')
-rw-r--r--scilab_doc/toolbox_guide/html/toolbox.html303
1 files changed, 165 insertions, 138 deletions
diff --git a/scilab_doc/toolbox_guide/html/toolbox.html b/scilab_doc/toolbox_guide/html/toolbox.html
index dd228ce..3d4e672 100644
--- a/scilab_doc/toolbox_guide/html/toolbox.html
+++ b/scilab_doc/toolbox_guide/html/toolbox.html
@@ -21,13 +21,13 @@
21 </head> 21 </head>
22 22
23 <body> 23 <body>
24 <h1 center>Guide for the toolboxes contribution (general application)<br /><hr></h1> 24 <h1 center>Guide for the toolboxes contributions (general application)<br /><hr></h1>
25 <p> 25 <p>
26 This article describes a standart method to create a Scilab toolbox.<br /> 26 This article describes a standart method to create a Scilab toolbox.<br />
27 The objective is to help the contributors to build a toolbox easily, but also that the users are able to install it with just the execution of a main builder and a main loader script.<br /> 27 The objective is to help the contributors to build a toolbox easily, but also that the users are able to install it with just the execution of a main builder and a main loader script.<br />
28 We show in first time how to structure your toolbox (sub-directories contents, files, ...), in second time how to customize the templates to create the builder(s), the loader(s), and the Scilab help files. To finish we explain how to upload your contribution on the scilab website.<br /> 28 We show in first time how to structure your toolbox (sub-directories contents, files, ...), in second time how to customize the templates to create the builder(s), the loader(s), and the Scilab help files. To finish we explain how to upload your contribution on the scilab website.<br />
29 For this article the reference toolbox name is <b>toolbox_example</b>. 29 For this article the reference toolbox name is <b>mytoolbox</b>.
30 (The above standarisation is not mandatory) 30 (The standarisation below is not mandatory)
31 </p> 31 </p>
32 32
33 <h2>Table of content</h2> 33 <h2>Table of content</h2>
@@ -43,14 +43,15 @@
43 </ul> 43 </ul>
44 <a href="#chap2.2">2.2. the interface and src directories</a><br /> 44 <a href="#chap2.2">2.2. the interface and src directories</a><br />
45 <ul> 45 <ul>
46 <a href="#chap2.2.1">2.2.1. interface examples</a><br /> 46 <a href="#chap2.2.1">2.2.1. Interface C/Scilab</a><br />
47 <a href="#chap2.2.2">2.2.2. Primitives builder</a><br /> 47 <a href="#chap2.2.2">2.2.2. Examples of interfaces programs</a><br />
48 <a href="#chap2.2.3">2.2.3. Primitives builder</a><br />
48 </ul> 49 </ul>
49 <a href="#chap2.3">2.3. The man directory</a><br /> 50 <a href="#chap2.3">2.3. The help directory</a><br />
50 <ul> 51 <ul>
51 <a href="#chap2.3.1">2.3.1. Creation of .xml files</a><br /> 52 <a href="#chap2.3.1">2.3.1. Creation of .xml files</a><br />
52 <a href="#chap2.3.2">2.3.2. The man builder</a><br /> 53 <a href="#chap2.3.2">2.3.2. The help builder</a><br />
53 <a href="#chap2.3.3">2.3.3. The man loader</a><br /> 54 <a href="#chap2.3.3">2.3.3. The help loader</a><br />
54 </ul> 55 </ul>
55 </ul> 56 </ul>
56 <a href="#chap3">3. The main builder and loader</a><br /> 57 <a href="#chap3">3. The main builder and loader</a><br />
@@ -59,38 +60,40 @@
59 60
60 <a name="chap1"></a> 61 <a name="chap1"></a>
61 <h2>1. Toolbox composition</h2> 62 <h2>1. Toolbox composition</h2>
62 <p>The root directory has the generic name of the toolbox (here <b>toolbox_example</b>), it contains 7 sub-directories:</p> 63 <p>The root directory has the generic name of the toolbox (here <b>mytoolbox</b>), it contains 8 sub-directories:</p>
63 64
64 <ul style="list-style-type: disc"> 65 <ul style="list-style-type: disc">
65 <li><b>macros</b>: Scilab macros (all .sci files), the builder and loader scripts</li> 66 <li><b>macros</b>: Scilab macros (i.e the functions written in Scilab code with the extension .sci), buildmacros and loadmacros scripts</li>
66 <li><b>src</b>: code source (all .c and .f files), a builder script</li> 67 <li><b>src</b>: source code (all .c and .f files), a buildsrc script</li>
67 <li><b>interface</b>: interface programs, a builder</li> 68 <li><b>sci_gateway</b>: interfaces programs, a buildsci_gateway</li>
68 <li><b>man</b>: all .xml files, the builder and loader scripts</li> 69 <li><b>help</b>: english and french help sub-directories named respectively <b>eng</b> and <b>fr</b> which contains all the .xml help files, buildhelp and loadhelp scripts</li>
69 <li><b>doc</b>: .html, .pdf, .txt, .jpeg, ...</li> 70 <li><b>etc</b>: .html, .pdf, .txt, .jpeg, ...</li>
70 <li><b>tests</b>: scripts to test your toolbox</li> 71 <li><b>unit tests</b>: .tst files (scripts to test your toolbox)</li>
71 <li><b>demos</b>: different examples to illustrate your toolbox</li> 72 <li><b>demos</b>: different examples to illustrate your toolbox</li>
73 <li><b>includes</b>: .h files</li>
72 </ul> 74 </ul>
73 75
74 and 3 files: 76 and 4 files:
75 77
76 <ul style="list-style-type: disc"> 78 <ul style="list-style-type: disc">
77 <li><b>README</b>: toolbox description and installation</li> 79 <li><b>readme.txt</b>: toolbox description and installation</li>
78 <li><b>builder.sce</b></li> 80 <li><b>builder.sce</b>: the main builder</li>
79 <li><b>loader.sce</b></li> 81 <li><b>loader.sce</b>: the main loader</li>
82 <li><b>license.txt</b></li>
80 </ul> 83 </ul>
81 84
82 <a name="chap2"></a> 85 <a name="chap2"></a>
83 <h2>2. Sub-builders and sub-loaders</h2> 86 <h2>2. Sub-builders and sub-loaders</h2>
84 <p> 87 <p>
85 The main builder and main loader scripts launch respectively the sub-builders and sub-loaders included in the sub-directories (macros, src, man, ...), to generate and to load the necessary libraries and the Scilab help files. 88 The main builder and main loader scripts launch respectively the sub-builders and sub-loaders included in the sub-directories (macros, src, help, ...), to generate and to load the necessary libraries and the Scilab help files.
86 </p> 89 </p>
87 90
88 <a name="chap2.1"></a> 91 <a name="chap2.1"></a>
89 <h3>2.1 The macros directory</h3> 92 <h3>2.1 The macros directory</h3>
90 <p> 93 <p>
91 This directory included macros Scilab functions, a builder and a loader script.<br /> 94 By convention the builder and the loader included in the <b>macros</b> directory are named respectively buildmacros.sce and loadmacros.sce<br \>
92 A macros is a function written in Scilab code (included in .sci file)<br /> 95 A <b>macros</b> is a function written in Scilab code (included in .sci file)<br \>
93 We consider that the macros directory of the toolbox <b>toolbox_example</b> contains just one .sci file: the function <var><strong>foo1</strong></var> (see above script). Given a matrix A, this function returns the positive components of the A diagonal. 96 We consider that the <b>macros</b> directory of the toolbox <b>mytoolbox</b> contains just one .sci file, the function <var><strong>foo1</strong></var> (see above script): Given a matrix A, this function returns the vector X the positive components of the A diagonal.
94 </p> 97 </p>
95 foo1.sci<br /> 98 foo1.sci<br />
96 99
@@ -117,64 +120,71 @@ endfunction</pre>
117 <a name="chap2.1.1"></a> 120 <a name="chap2.1.1"></a>
118 <h4>2.1.1 The macros builder</h4> 121 <h4>2.1.1 The macros builder</h4>
119 <p> 122 <p>
120 The builder (see above script) creates a library variable, (named here: toolbox_examplelib= toolbox name +'lib') 123 The builder (see below script) creates a library variable, (named here: mytoolboxlib= toolbox name +'lib')
121 from functions .sci include in the directory macros, and saves it in the file lib. 124 from functions .sci include in the directory macros, and saves it in the file lib.
122 The builder code is generic, it's done in 2 steps, the first to locate macrosbuilder.sce script 125 The builder code is generic, it's done in 2 steps, the first to locate buildmacros.sce script
123 (see help <var><strong>get_absolute_file_path</strong></var> function), and the second to generate the library 126 (see help <var><strong>get_absolute_file_path</strong></var> function), and the second to generate the library
124 (see help <strong><var>genlib</strong></var> function). 127 (see help <strong><var>genlib</strong></var> function).
125 </p> 128 </p>
126 builder.sce 129 buildmacros.sce
127 <pre class="entete"> 130 <pre class="entete">
128mode(-1) 131mode(-1)
129toolboxname='toolbox_example' 132toolboxname='mytoolbox'
130pathB=get_absolute_file_path('builder.sce') 133pathB=get_absolute_file_path('buildmacros.sce')
131disp('Building macros in ' +pathB) 134disp('Building macros in ' +pathB)
132genlib(toolboxname+'lib',pathB,%t) 135genlib(toolboxname+'lib',pathB,%t)
133clear pathB genlib toolboxname</pre> 136clear pathB genlib toolboxname</pre>
134 137
135 <br /> 138 <br />
136 To customize this template, replace the characters string 'toolbox_example' by the name of your toolbox. 139 To customize this template, replace the characters string 'mytoolbox' by the name of your toolbox.
137 140
138 <a name="chap2.1.2"></a> 141 <a name="chap2.1.2"></a>
139 <h4>2.1.2 The macros loader</h4> 142 <h4>2.1.2 The macros loader</h4>
140 <p> 143 <p>
141 The loader (see above script) loads the library lib included in the directory macros. Like the builder, the code is generic, the first step to locate macrosloader.sce script, and the second to load the library (see help <strong><var>load</strong></var> function) 144 The loader (see below script) loads the library lib included in the directory <b>macros</b>. Like the builder, the code is generic, the first step to locate loadmacros.sce script, and the second to load the library (see help <strong><var>load</strong></var> function)
142 </p> 145 </p>
143 146
144 loader.sce 147 loadmacros.sce
145 <pre class="entete"> 148 <pre class="entete">
146mode(-1) 149mode(-1)
147pathL=get_absolute_file_path('loader.sce') 150pathL=get_absolute_file_path('loadmacros.sce')
148disp('Loading macros in ' +pathL) 151disp('Loading macros in ' +pathL)
149load(pathL+'/lib') 152load(pathL+'/lib')
150clear pathL</pre> 153clear pathL</pre>
151 154
152 <a name="chap2.2"></a> 155 <a name="chap2.2"></a>
153 <h3>2.2 Interface and src directories</h3> 156 <h3>2.2 scr and sci_gateway directories</h3>
154 <p> 157 A <b>primitive</b> is a Scilab function which calls a function written in C or fortran code ,using an interface program. So for each Scilab primitive we must to create the corresponding interface program included in the <b>sci_gateway</b> directory.
155 A Scilab primitive is a Scilab function which calls a function written in C or fortran code (using an interface program)<br /> 158
156 Before to write the builder, its necessary to create for each primitives the corresponding interface programs which are included in the directory: interface. When a Scilab primitive is called, the interface program checks that the number, the type and the size of inputs/outputs arguments is correct (using CheckRhs and CheckLhs functions), and get the adress of the rhs arguments which are in Scilab internal stack to give this information at the interfaced function. So in the first part we explain, thanks to template, how to implement some interfaces programs (written in C code). In this article we don't describe all the possibilities of the interface programs, for more explanations see the directory SCI/examples. 159 <a name="chap2.2.1"></a>
157 All interface programs are included in the directory: interface<br /> 160 <h4>2.2.1 Interface C/Scilab</h4>
161 <p>
162 When a Scilab primitive is called, the interface program checks that the number, the type and the size of inputs/outputs arguments is correct (using <b>CheckRhs</b> and <b>CheckLhs</b> functions), and gets the rhs arguments address which are in Scilab internal stack to give this information at the interfaced function.<br \><br \>
163
164 In this article, the interfaces programs examples(written in C code) are described step by step, they enable to write many interfaces, so it's important to understand them, and to know how to customize them for your toolboxes.<br \><br \>
165
166 We don't describe all the possibilities of the interface programs, for more explanations see the directory <b>SCI/examples</b>.<br \>
158 </p> 167 </p>
159 168
160 <a name="chap2.2.1"></a> 169 <a name="chap2.2.2"></a>
161 <h4>2.2.1 Examples of interfaces programs</h4> 170 <h4>2.2.2 Examples of interfaces programs</h4>
162 <p> 171 <p>
163 Here two examples which enable to write many interfaces, so it's important to understand it, and know how to customize it for your toolbox. 172 These examples(written in C code) are described step by step, they enable to write many interfaces, so it's important to understand them, and to know how to customize them for your toolboxes.
164 </p> 173 </p>
165 174
166 <p> 175 <p>
167 <EM>Example a</EM>: <br /> 176 <EM>Example a</EM>: <br />
168 We consider an C routine <var><strong>sumab</strong></var> which returns the sum of two vectors. I suppose that the name of the corresponding primitive is 177 We consider an C routine <b>vectsum</b> which returns the sum of two vectors. I suppose that the name of the corresponding primitive is <b>sumab</b> and the associated interface program name is <b>sci_sumab</b>.
169 <var><strong>scisum</strong></var>. We can keep the same name that the C routine (sumab) or try an other name.<br /> 178
170 The both following scripts represent the C code of <var><strong>sumab</strong></var> and its associated interface program when 179 By convention all the interfaces programs names begin by the "sci_" character strings.
171 we call the primitive <var><strong>scisum </strong></var>in a Scilab window as follows:<br /> 180
172 <var><strong>--> Y=scisum(A,B )</strong></var> <br /><br /> 181 The both following scripts represent the C code of <b>vectsum</b> and <b>sci_sumab</b> when we call the primitive <b>sumab</b> in a Scilab window as follows:<br /><br />
182 <var><strong>--> Y=sumab(A,B )</strong></var> <br /><br />
173 </p> 183 </p>
174 184
175 sumab.c 185 vectsum.c
176 <pre class="entete"> 186 <pre class="entete">
177void sumab(int n, double * a, double * b, double * y) 187void vectsum(int n, double * a, double * b, double * y)
178{ 188{
179 int k; 189 int k;
180 for (k = 0; k < n; ++k) 190 for (k = 0; k < n; ++k)
@@ -182,12 +192,12 @@ void sumab(int n, double * a, double * b, double * y)
182}</pre> 192}</pre>
183 193
184 <br /> 194 <br />
185 intsumab.c<br /> 195 sci_sumab.c<br />
186 <pre class="entete"> 196 <pre class="entete">
187#include "stack-c.h" 197#include "stack-c.h"
188extern int sumab(int n, double * a, double * b, double * y); 198extern int vectsum(int n, double * a, double * b, double * y);
189 199
190void intsumab(char *fname){ 200void sci_sumab(char *fname){
191int l1, m1, n1, l2, m2, n2, l3, n; 201int l1, m1, n1, l2, m2, n2, l3, n;
192 202
193/* 1 - Check the number of inputs/outputs arguments */ 203/* 1 - Check the number of inputs/outputs arguments */
@@ -195,12 +205,12 @@ int minlhs=1, maxlhs=1, minrhs=2, maxrhs=2;
195CheckRhs(minrhs,maxrhs) ; 205CheckRhs(minrhs,maxrhs) ;
196CheckLhs(minlhs,maxlhs) ; 206CheckLhs(minlhs,maxlhs) ;
197 207
198/* 2 - Check inputs arguments type, and get the size and the adress in the Scilab stack of the inputs arguments */ 208/* 2 - Check inputs arguments type, and get the size and the address in the Scilab stack of the inputs arguments */
199GetRhsVar(1, "d", &m1, &n1, &l1); 209GetRhsVar(1, "d", &m1, &n1, &l1);
200GetRhsVar(2, "d", &m2, &n2, &l2); 210GetRhsVar(2, "d", &m2, &n2, &l2);
201 211
202/* 3 - Check that the inputs arguments have the same size */ 212/* 3 - Check that the inputs arguments have the same size */
203/* it's possible to use the chekdims and getscalar functions to do these checks*/ 213/* it's possible to use the chekdims and getscalar functions to make these checks*/
204n=m2*n2; 214n=m2*n2;
205if( n1!=n2 || m1!=m2) 215if( n1!=n2 || m1!=m2)
206{ 216{
@@ -215,23 +225,25 @@ if(n1!=0 && m1!=0)
215 } 225 }
216 226
217 227
218/* 4 - Create the output argument */ 228/* 4 - Create a new variable corresponding to the output argument */
219CreateVar(3,"d",&m2,&n2,&l3); 229CreateVar(3,"d",&m2,&n2,&l3);
220sumab(n,stk(l1),stk(l2),stk(l3)); 230
231/* 5 -call vectsum routine: returns in stk(l3) the sum of a and b*/
232vectsum(n,stk(l1),stk(l2),stk(l3));
221 233
222/* 5 - Specif the ouput argument */ 234/* 6 - Specif ouput argument */
223LhsVar(1) = 3; 235LhsVar(1) = 3;
224return 0; 236return 0;
225}</pre> 237}</pre>
226 238
227 <br /> 239 <br />
228 <p> 240 <p>
229 <EM>In Step 1</EM>: call the instructions <var><strong>CheckRhsVar(minrhs,maxrhs)</strong></var> and <var><strong> 241 <EM>Step 1</EM>: call <var><strong>CheckRhsVar(minrhs,maxrhs)</strong></var> and <var> <strong>
230 CheckLhsVar(minlhs,maxlhs)</strong></var><br /> 242 CheckLhsVar(minlhs,maxlhs)</strong></var> instructions<br />
231 <var><strong>CheckRhsVar</strong></var> function uses the arguments <strong><var>minrhs</strong></var> 243 <var><strong>CheckRhsVar</strong></var> function uses the arguments <strong><var>minrhs</strong></var>
232 and <var><strong>maxrhs</strong></var> to check that:<br /> 244 and <var><strong>maxrhs</strong></var> to check that:<br />
233 <var><strong>minrhs <= number of input arguments <= maxrhs</strong></var><br /> 245 <var><strong>minrhs <= number of input arguments <= maxrhs</strong></var><br />
234 In this example the numbers of input (=2) and output (=1) arguments are constant, but for certains functions (see example2) 246 The number of inputs and outputs arguments (respectively 2 and 1) of <b>vectsum</b> are constant, so minrhs=maxrhs=2 and minlhs=maxlhs=1, but for certains functions (see example2)
235 they can be variable, in this case the variables <var><strong>minrhs/minlhs</strong></var> and <var><strong>maxrhs/maxlhs</strong> 247 they can be variable, in this case the variables <var><strong>minrhs/minlhs</strong></var> and <var><strong>maxrhs/maxlhs</strong>
236 </var> are different.<br /> We can use directly the defined variables <var><strong>Rhs</strong></var>(=number of inputs) and 248 </var> are different.<br /> We can use directly the defined variables <var><strong>Rhs</strong></var>(=number of inputs) and
237 <var><strong>Lhs</strong></var>(=number of outputs) instead of the functions <var><strong>CheckRhsVar</strong></var> and 249 <var><strong>Lhs</strong></var>(=number of outputs) instead of the functions <var><strong>CheckRhsVar</strong></var> and
@@ -239,49 +251,61 @@ return 0;
239 251
240 <br /> 252 <br />
241 253
242 <EM>In Step 2</EM>: call the instruction <b><i>GetRhsVar(1,"d",&m1,&n1,&l1)</b></i><br /> 254 <EM>Step 2</EM>: call <b><i>GetRhsVar(1,"d",&m1,&n1,&l1)</b></i> instruction<br />
243 <b><i>GetRhsVar</b></i> function checks that the type of inputs argument is correct, and gets their size and their adress in the Scilab stack.<br /> 255 <b><i>GetRhsVar</b></i> function checks that the type of inputs arguments of <b>sumab</b> are correct, and gets their size and their address in the Scilab stack.<br />
244 We describe above all arguments of <b><i>GetRhsVar</b></i> function:<br /> 256 We describe below all arguments of <b><i>GetRhsVar</b></i> function:<br />
245 <b><i>1</b></i> : corresponds to the position of the first input argument of scisum(A,B ), i.e A, (2 corresponds to B,...)<br /> 257
246 <b><i>m1 </b></i>: gets the rows number of A (m2 for B)<br /> 258 <ul style="list-style-type: disc">
247 <b><i>n1 </b></i>: gets the columns number of A (n2 for B)<br /> 259 <li><b><i>1</b></i> : corresponds to the position of the first input argument of sumab, i.e A, (2 corresponds to B,...)</li>
248 <b><i>l1 </b></i>: gets the adress of A in the Scilab stack (l2 for B)<br /> 260 <li><b><i>m1 </b></i>: gets the rows number of A (m2 for B)</li>
249 261 <li><b><i>n1 </b></i>: gets the columns number of A (n2 for B)</li>
262 <li><b><i>l1 </b></i>: gets the address of A in the Scilab stack (l2 for B)</li>
263 </ul>
250 <br /> 264 <br />
251 265
252 <EM>In Step 3</EM>: instruction <b><i>CreateVar(3,"d",&m2,&n2,&l3)</b></i><br /> 266 <EM>Step 4</EM>: call <b><i>CreateVar(3,"d",&m2,&n2,&l3)</b></i> instruction<br />
253 <b><i>CreateVar</b></i> function creates the ouput argument (here Y) at the 3th position<br /> 267 <b><i>CreateVar</b></i> function creates in the Stack at the 3th position a variable which corresponds to the output argument of <b>vectsum</b> (here Y)<br />
254 <b><i>3 </b></i>: corresponds to the position of the first output argument Y. We should take the number which follows 268 <ul style="list-style-type: disc">
255 immediatly the last position of the input arguments (which is 2)<br /> 269 <li><b><i>3 </b></i>: position of the created variable in the stack. This position (here 3) must follows the position of the last input argument (here2) of <b>vectsum</b> </li>
256 <b><i>"d"</b></i>: sets the type of the output argument, a double <br /> 270 <li><b><i>"d"</b></i>: sets the type of the created variable, here double </li>
257 <b><i>m2</b></i>: sets the rows number of the output argument (here equal to the rows number of the second input argument B: m2)<br /> 271 <li><b><i>m2</b></i>: sets the rows number of the created variable(here equal to the rows number of the second input argument B: m2)</li>
258 <b><i>n2</b></i>: sets the columns number of the first output argument (here equal to the columns number of the second input argument B: n2)<br /> 272 <li><b><i>n2</b></i>: sets the columns number of the first created variable (here equal to the columns number of the second input argument B: n2)</li>
259 <b><i>l3</b></i>: gets the adress of the lhs in the Scilab stack <br /> 273 <li><b><i>l3</b></i>: gets the address of the created variable in the Scilab stack </li>
274 </ul>
260 275
261 <br /> 276 <br />
262 277
263 <EM>In Step 4</EM>: instruction <b><i>LhsVar(1) = 3</b></i><br /> 278 <EM>Step 5</EM>: call <b>vectsum(n,stk(l1),stk(l2),stk(l3))</b> instruction<br />
264 The instruction <b><i>LhsVar(1) = 3</b></i> means the first output argument takes the value of the variable placed in the 3th position (i.e Y)<br /> 279 The C function <b>vectsum</b> returns in stk(l3) the sum of stk(l1) and stk(l2) (i.e a and b)<br />
265 280
281
282 <EM>Step 6</EM>: call <b><i>LhsVar(1) = 3</b></i> instruction<br />
283 The first output argument (here Y) of sumab takes the value of the variable placed in the 3th position (i.e stk(l3))<br />
266 <br /> 284 <br />
267 <br /> 285 <br />
268 286
269 <EM>Example b</EM>:<br /> 287 <EM>Example b</EM>:<br />
270 In the second example we describe the interface program (see above script) of the primitive <b><i>scifun1</b></i> which uses the C functions <b><i>fun1</b></i> and <b><i>fun2</b></i> (see above script). This primitive has two syntaxes:<br /> 288 In the second example we describe the interface program named <b>sci_fun</b> of the Scilab primitive named <b><i>fun</b></i>.<br />
271 289 This function call the C routines <b>fun1</b> and <b>fun2</b> and has 2 syntaxes which are:
290 <br />
272 <br /> 291 <br />
273 the first syntax is:</b></i><br /> 292 the first syntax is:</b></i><br />
274 <b><i>--> [X, Y ]=scifun1(A);</b></i><br /> 293 <b><i>--> [X, Y ]=fun(A);</b></i><br />
275 Given a vector <b><i>A</b></i>, this function returns the positive components of <b><i>A</b></i> in a vector <b><i>X</b></i> and the sum of its positive components in a scalar <b><i>Y</b></i>. In this case the number of output arguments (=Lhs) is 2.<br /> 294 Given a vector <b><i>A</b></i>, this function returns the positive components of <b><i>A</b></i> in a vector <b><i>X</b></i> and the sum of its positives components in a scalar <b><i>Y</b></i>.<br />
276 295
277 <br /> 296 <br />
278 the second syntax is:<br /> 297 the second syntax is:<br />
279 <b><i>--> [X ]=scifun1(A);</b></i><br /> 298 <b><i>--> [X ]=fun(A);</b></i><br />
280 Given a vector <b><i>A</b></i>, this function returns the positive components of <b><i>A</b></i> in a vector <b><i>X</b></i>. In this case <b><i>Lhs=1</b></i>.<br /> 299 Given a vector <b><i>A</b></i>, this function returns the positives components of <b><i>A</b></i> in a vector <b><i>X</b></i>.<br />
300 </p>
301 <p>
302 The number of outputs arguments (i.e Lhs value) is variable: for the first syntax Lhs=1, for the second syntax Lhs=2. The number of intputs arguments (i.e Rhs value) is constant: Rhs=1 (first and second syntax).<br />
303 So the interface program must check that: <b>1<=Lhs<=2</b> (set <b>minlhs=1</b>, <b>maxlhs=2</b>) and <b>Rhs=1</b> (set <b>minrhs=maxrhs=1</b>)<br />
281 </p> 304 </p>
282 305
306
283 <br /> 307 <br />
284 fun1.c (the C function <b><i>fun1</b></i> creates the vector <b><i>X</b></i> and the scalar <b><i>Y</b></i>, it calls the C function <b><i>fun2</b></i> to get the needed size of <b><i>X</b></i> in order to allocate the memory place) 308 fun1.c (the C function <b><i>fun1</b></i> creates the vector <b><i>X</b></i> and the scalar <b><i>Y</b></i>. It calls the C function <b><i>fun2</b></i> to get the needed size of <b><i>X</b></i> in order to allocate the corresponding memory place)
285 <pre class="entete"> 309 <pre class="entete">
286extern void fun2(double *, int, int *); 310extern void fun2(double *, int, int *);
287 311
@@ -291,7 +315,7 @@ void fun1(double * a, int na, int * nx, double ** x , double * y){
291 fun2(a, na, nx); 315 fun2(a, na, nx);
292 *x=(double *)malloc((*nx)*sizeof(double)); 316 *x=(double *)malloc((*nx)*sizeof(double));
293 *y=0; 317 *y=0;
294 for(i=0;i<na;i++) 318 for(i=0;i&lt;na;i++)
295 if(a[i]>0) { 319 if(a[i]>0) {
296 *(*x+k1)=a[i]; 320 *(*x+k1)=a[i];
297 *y += a[i]; 321 *y += a[i];
@@ -307,20 +331,20 @@ void fun2(double * a, int na, int * nx)
307{ 331{
308 int i; 332 int i;
309 *nx=0; 333 *nx=0;
310 for(i=0;i<na;i++) 334 for(i=0;i&lt;na;i++)
311 if (a[i]>0) 335 if (a[i]>0)
312 (*nx)++; 336 (*nx)++;
313}</pre> 337}</pre>
314 338
315 <br /> 339 <br />
316 340
317 intfun1.c 341 sci_fun.c
318 <pre class="entete"> 342 <pre class="entete">
319#include "stack-c.h" 343#include "stack-c.h"
320 344
321extern void fun1(double * , int, int *, double **, double *); 345extern void fun1(double * , int, int *, double **, double *);
322 346
323int intfun1(char *fname) 347int sci_fun(char *fname)
324{ 348{
325 int la, ma, na, m=1, nx, i, lx, ls; 349 int la, ma, na, m=1, nx, i, lx, ls;
326 double * x, s; 350 double * x, s;
@@ -331,7 +355,7 @@ int intfun1(char *fname)
331 CheckRhs(minrhs,maxrhs) ; 355 CheckRhs(minrhs,maxrhs) ;
332 CheckLhs(minlhs,maxlhs) ; 356 CheckLhs(minlhs,maxlhs) ;
333 357
334 /* 2 - Check the rhs type, get the rows number (ma) and the columns number (na) of rhs, and its adress (la) in the Scilab stack (first position) */ 358 /* 2 - Check the rhs type, get the rows number (ma) and the columns number (na) of rhs, and its address (la) in the Scilab stack (first position) */
335 GetRhsVar(1, "d", &ma, &na, &la); 359 GetRhsVar(1, "d", &ma, &na, &la);
336 360
337 /* 3 - Check rhs is a vector */ 361 /* 3 - Check rhs is a vector */
@@ -346,10 +370,10 @@ int intfun1(char *fname)
346 370
347 fun1(stk(la), na*ma, &nx, &x, &s); 371 fun1(stk(la), na*ma, &nx, &x, &s);
348 372
349 /* 4 - Create the place for the first output argument x ( a vector of doubles, size: 1*nx ) to the adress lx in the Scilab stack (second position) */ 373 /* 4 - Create the place for the first output argument x ( a vector of doubles, size: 1*nx ) to the address lx in the Scilab stack (second position) */
350 CreateVar(2, "d", &m, &nx, &lx); 374 CreateVar(2, "d", &m, &nx, &lx);
351 375
352 /* if there are two outputs variables then: Create the place for the second output s ( a double, size 1*1) to the adress ls in the Scilab stack (third position) */ 376 /* if there are two outputs variables then: Create the place for the second output s ( a double, size 1*1) to the address ls in the Scilab stack (third position) */
353 /* get the value of s, and put it in the Scilab stack */ 377 /* get the value of s, and put it in the Scilab stack */
354 if(Lhs==2) 378 if(Lhs==2)
355 { 379 {
@@ -358,7 +382,7 @@ int intfun1(char *fname)
358 } 382 }
359 383
360 /* get the components of x, and put them in the Scilab stack */ 384 /* get the components of x, and put them in the Scilab stack */
361 for(i=0;i&gt;nx;i++) 385 for(i=0;i&lt;nx;i++)
362 stk(lx)[i]=x[i]; 386 stk(lx)[i]=x[i];
363 387
364 /* free memory */ 388 /* free memory */
@@ -373,46 +397,49 @@ int intfun1(char *fname)
373 397
374 <br /> 398 <br />
375 399
376 <a name="chap2.2.2"></a> 400 <a name="chap2.2.3"></a>
377 <h4>2.2.2 Primitives builder</h4> 401 <h4>2.2.3 Primitives builder</h4>
378 <p>Now the src and the interface directories contain all the necessary files (<b><i>fun1.c</b></i>, <b><i>fun2.c</b></i>, <b><i>intfun1.c</b></i>, <b><i>sumab.c</b></i>, <b><i>intsumab.c</b></i>) to create the builder (see above template) for the primitives <i><b>scifun1</i></b> and <i><b>scisum</i></b>. 402 <p>Now the <b>src</b> and the <b>sci_gateway</b> directories contain all the necessary files (<b><i>fun1.c</b></i>, <b><i>fun2.c</b></i>, <b><i>sci_fun.c</b></i>, <b><i>vectsum.c</b></i>, <b><i>sci_sumab.c</b></i>) to create the builder (see below template) for the primitives <i><b>fun</i></b> and <i><b>sumab</i></b>.
379 <br /> 403 <br />
380 We need to write two builders:<br /> One the hand, in the src directory, this builder creates a shared libraries (see help <i><b>ilib_for_link</b></i> function) corresponding to the C functions.And the other hand, in the interface directory, this builder creates the new shared libraries to link the compiled C or Fortran new Scilab interface routines (thanks to src libraries), and generates a loader (see help <i><b>ilib_build</b></i> function). 404 We need to write two builders:<br />
381 This loader file calls the addinter function to dynamically load the shared library (see help <i><b>addinter</b></i> function)</p> 405 One the hand, in the <b>src</b> directory, this builder (named <b>buildersrc</b>) creates a shared libraries (see help <i><b>ilib_for_link</b></i> function) corresponding to the C functions.<br />
406 And the other hand, in the <b>interface</b> directory, this builder (named <b>buildsci_gateway</b>) creates the new shared libraries to link the compiled C or Fortran new Scilab interface routines (thanks to src libraries), and generates a loader (see help <i><b>ilib_build</b></i> function).
407 This loader file calls the addinter function to load dynamically the shared library (see help <i><b>addinter</b></i> function)</p>
382 408
383 the src builder 409 buildsrc.sce
384 <pre class="entete"> 410 <pre class="entete">
385ilib_for_link('toolbox_examplesrc',['fun1.o' 'fun2.o','sumab.o'],[],"c")</pre> 411ilib_for_link('mytoolboxsrc',['fun1.o' 'fun2.o','vectsum.o'],[],"c")</pre>
386 412
387 <br /> 413 <br />
388 the interface builder<br /> 414 buildsci_gateway.sce<br />
389 415
390 <pre class="entete"> 416 <pre class="entete">
391// must be run from this directory 417 // must be run from this directory
392ilib_name = 'libtoolbox_example' // interface library name 418 ilib_name = 'libmytoolbox' // interface library name
393files = ['intfun1.o', 'intsumab.o']; // objects files 419 files = ['sci_fun.o', 'sci_sumab.o']; // objects files
394libs = ["../src/libtoolbox_examplesrc"] // other libs needed for linking 420 libs = ["../src/libmytoolboxsrc"] // other libs needed for linking
395table = [ 'scifun1', 'intfun1'; 421 table = [ 'fun', 'sci_fun';
396 'scisum','intsumab']; // table of (scilab_name,interface-name) 422 'sumab','sci_sumab']; // table of (scilab_name,interface-name)
397// do not modify below 423 // do not modify below
398ilib_build(ilib_name,table,files,libs)</pre> 424 ilib_build(ilib_name,table,files,libs)</pre>
399 425
400 <br /> 426 <br />
401 The <i><b>ilib_name</b></i> value is the interface library name, the vector <i><b>files</b></i> contains all the object interface files, 427 The <i><b>ilib_name</b></i> value is the interface library name, the vector <i><b>files</b></i> contains all the object interface files,
402 the vector <i><b>libs</b></i> contains the libraries needed for linking (here the library included in the src directory), 428 the vector <i><b>libs</b></i> contains the libraries needed for linking (here the library included in the src directory),
403 the variable <i><b>table</b></i> contains the primitives names (first column) and the corresponding interface program names (second column) 429 the variable <i><b>table</b></i> contains the primitives names (first column) and the corresponding interfaces programs names (second column)
404 430
405 <a name="chap2.3"></a> 431 <a name="chap2.3"></a>
406 <h3>2.3 The man directory</h3> 432 <h3>2.3 The help directory</h3>
407 <p>This directory included .xml files, a manbuilder and a manloader scripts 433 <p>This directory included <b>.xml</b> files, a <b>buildhelp</b> and a <b>loadhelp</b> scripts.<br />
408 On Unix/Linux systems: to create the manual pages you need 'sabcmd', an XML parser which is part of the Sablotron package.<br /> 434 On Unix/Linux systems: to create the manual pages you need 'sabcmd', an XML parser which is part of the Sablotron package.<br />
409 (see the link to download it:<A href="http://www.scilab.org/download/index_download.php?page=related_tool.html"> http://www.scilab.org/download/index_download.php?page=related_tool.html</A>)<br /> 435 here the link to download it:<br />
436 <A href="http://www.scilab.org/download/index_download.php?page=related_tool.html"> http://www.scilab.org/download/index_download.php?page=related_tool.html</A><br />
410 </p> 437 </p>
411 438
412 <a name="chap2.3.1"></a> 439 <a name="chap2.3.1"></a>
413 <h4>2.3.1 Creation of .xml files</h4> 440 <h4>2.3.1 Creation of .xml files</h4>
414 <p> 441 <p>
415 Here a template which shows you how to write the .xml help files. You should just fill the different items(Langage, title, type, date, short description, ...) for the .xml files of your functions (here <b><i>scifun1.xml</i></b>, <b><i>scisum.xml</i></b>) and put them in the man directory. 442 Here a template which shows you how to write the .xml help files. You should just fill the different items(Langage, title, type, date, short description, ...) for the .xml files of your functions (here <b><i>foo1.xml</i></b>, <b><i>fun.xml</i></b>, <b><i>sumab.xml</i></b>) and put them in the <b>help</b> directory.
416 </p> 443 </p>
417 444
418 <pre class="entete"> 445 <pre class="entete">
@@ -420,7 +447,7 @@ ilib_build(ilib_name,table,files,libs)</pre>
420&lt;!DOCTYPE MAN SYSTEM &quot;/home/scilab/scilab-3.0/man/manrev.dtd&quot;&gt; 447&lt;!DOCTYPE MAN SYSTEM &quot;/home/scilab/scilab-3.0/man/manrev.dtd&quot;&gt;
421&lt;MAN&gt; 448&lt;MAN&gt;
422&lt;LANGUAGE&gt;eng&lt;/LANGUAGE&gt; 449&lt;LANGUAGE&gt;eng&lt;/LANGUAGE&gt;
423&lt;TITLE&gt;scisum&lt;/TITLE&gt; 450&lt;TITLE&gt;sumab&lt;/TITLE&gt;
424&lt;TYPE&gt;Scilab Function &lt;/TYPE&gt; 451&lt;TYPE&gt;Scilab Function &lt;/TYPE&gt;
425&lt;DATE&gt;20-Mar-2006&lt;/DATE&gt; 452&lt;DATE&gt;20-Mar-2006&lt;/DATE&gt;
426&lt;SHORT_DESCRIPTION name=&quot;add function name&quot;&gt; add short decription here&lt;/SHORT_DESCRIPTION&gt; 453&lt;SHORT_DESCRIPTION name=&quot;add function name&quot;&gt; add short decription here&lt;/SHORT_DESCRIPTION&gt;
@@ -490,30 +517,30 @@ Add here the used function name and references
490&lt;/MAN&gt;</pre> 517&lt;/MAN&gt;</pre>
491 518
492 <a name="chap2.3.2"></a> 519 <a name="chap2.3.2"></a>
493 <h4>2.3.2 The man builder</h4> 520 <h4>2.3.2 The help builder</h4>
494 <p>The manbuilder (see above) creates a whatis.htm file which is a short description of the functions, and translates the xml files to html (see help <b><i>xmltohtml</b></i> function) 521 <p>The builder (named buildhelp) creates a <b>whatis.htm</b> file which is a short description of the functions, and translates the xml files to html (see help <b><i>xmltohtml</b></i> function)
495 </p> 522 </p>
496 523
497 <br /> 524 <br />
498 525
499 builder.sce 526 buildhelp.sce
500 <pre class="entete"> 527 <pre class="entete">
501mode(-1) //force silent execution 528mode(-1) //force silent execution
502path=get_absolute_file_path('builder.sce');//get the absolute path of this file 529path=get_absolute_file_path('builhelp.sce');//get the absolute path of this file
503add_help_chapter("Title1",path);//add help chapter 530add_help_chapter("Title1",path);//add help chapter
504xmltohtml(path,"Title1") 531xmltohtml(path,"Title1")
505//clear the variable stack 532//clear the variable stack
506clear path add_help_chapter get_absolute_file_path </pre> 533clear path add_help_chapter get_absolute_file_path </pre>
507 534
508 <a name="chap2.3.3"></a> 535 <a name="chap2.3.3"></a>
509 <h4>2.3.3 The man loader</h4> 536 <h4>2.3.3 The help loader</h4>
510 <p>The loader(see above script) add your help functions files in the help Scilab browser 537 <p>The loader (named loadhelp) adds your help functions files in the help Scilab browser
511 </p> 538 </p>
512 539
513 loader.sce 540 loadhelp.sce
514 <pre class="entete"> 541 <pre class="entete">
515mode(-1) //force silent execution 542mode(-1) //force silent execution
516path=get_absolute_file_path('loader.sce');//get the absolute path of this file 543path=get_absolute_file_path('loadhelp.sce');//get the absolute path of this file
517add_help_chapter("Title1",path);//add help chapter 544add_help_chapter("Title1",path);//add help chapter
518clear path add_help_chapter get_absolute_file_</pre> 545clear path add_help_chapter get_absolute_file_</pre>
519 546
@@ -528,22 +555,22 @@ mainpathB=get_absolute_file_path('builder.sce');
528chdir(mainpathB); 555chdir(mainpathB);
529if isdir('src') then 556if isdir('src') then
530chdir('src'); 557chdir('src');
531exec('builder.sce'); 558exec('buildsrc.sce');
532chdir('..'); 559chdir('..');
533end 560end
534if isdir('interface') then 561if isdir('sci_gateway') then
535chdir('interface'); 562chdir('sci_gateway');
536exec('builder.sce'); 563exec('buildsci_gateway.sce');
537chdir('..'); 564chdir('..');
538end 565end
539if isdir('macros') then 566if isdir('macros') then
540chdir('macros'); 567chdir('macros');
541exec('builder.sce'); 568exec('buildmacros.sce');
542chdir('..'); 569chdir('..');
543end 570end
544if isdir('man') then 571if isdir('help') then
545chdir('man'); 572chdir('help');
546exec('builder.sce'); 573exec('buildhelp.sce');
547chdir('..'); 574chdir('..');
548end 575end
549clear mainpathB</pre> 576clear mainpathB</pre>
@@ -555,19 +582,19 @@ clear mainpathB</pre>
555mode(-1); 582mode(-1);
556mainpathL=get_absolute_file_path('loader.sce'); 583mainpathL=get_absolute_file_path('loader.sce');
557chdir(mainpathL); 584chdir(mainpathL);
558if isdir('interface') then 585if isdir('sci_gateway') then
559chdir('interface'); 586chdir('sci_gateway');
560exec('loader.sce'); 587exec('loader.sce');
561chdir('..'); 588chdir('..');
562end 589end
563if isdir('macros') then 590if isdir('macros') then
564chdir('macros'); 591chdir('macros');
565exec('loader.sce'); 592exec('loadmacros.sce');
566chdir('..'); 593chdir('..');
567end 594end
568if isdir('man') then 595if isdir('help') then
569chdir('man'); 596chdir('help');
570exec('loader.sce'); 597exec('loadhelp.sce');
571chdir('..'); 598chdir('..');
572end 599end
573clear mainpathL</pre> 600clear mainpathL</pre>
@@ -578,7 +605,7 @@ clear mainpathL</pre>
578 <li>Read the instructions about how to contribute , see the link: 605 <li>Read the instructions about how to contribute , see the link:
579 <A href="http://www.scilab.org/contrib/index_contrib.php?page=howto.html">http://www.scilab.org/contrib/index_contrib.php?page=howto.html </A></li> 606 <A href="http://www.scilab.org/contrib/index_contrib.php?page=howto.html">http://www.scilab.org/contrib/index_contrib.php?page=howto.html </A></li>
580 <li>Archive and Compress your toolbox: </li> 607 <li>Archive and Compress your toolbox: </li>
581 <li>Complete the submission form document and add your package (here <b>toolbox_example.tar.gz</b> and <b>toolbox_example.zip</b>), 608 <li>Complete the submission form document and add your package (here <b>mytoolbox.tar.gz</b> and <b>mytoolbox.zip</b>),
582 see the link: <A href="http://www.scilab.org/contrib/index_contrib.php?page=upload.html">http://www.scilab.fr/contrib/index_contrib.php?page=upload.html </A></li> 609 see the link: <A href="http://www.scilab.org/contrib/index_contrib.php?page=upload.html">http://www.scilab.fr/contrib/index_contrib.php?page=upload.html </A></li>
583 </ul> 610 </ul>
584 </body> 611 </body>