4bf76a53044ec2a93e97970a0ee7479c48c3f797
[scilab.git] / scilab / modules / core / help / en_US / scilab.xml
1 <?xml version="1.0" encoding="UTF-8"?>
2 <refentry xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:svg="http://www.w3.org/2000/svg" xmlns:ns4="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="scilab" xml:lang="en">
3     <refnamediv>
4         <refname>scilab</refname>
5         <refpurpose>Main script to start Scilab and miscellaneous
6             tools (GNU/Linux, Unix and Mac OS X)
7         </refpurpose>
8     </refnamediv>
9     <refsynopsisdiv>
10         <title>Syntax</title>
11         <synopsis>scilab &lt;Options&gt;
12             scilab-adv-cli &lt;Options&gt;
13             scilab-cli &lt;Options&gt;
14         </synopsis>
15     </refsynopsisdiv>
16     <refsection role="arguments">
17         <title>Arguments</title>
18         <variablelist>
19             <varlistentry>
20                 <term>-args Arguments</term>
21                 <listitem>
22                     <para>If this option is present, arguments are passed to Scilab.
23                         They can then be got by <link linkend="sciargs">sciargs</link>
24                         function. For multi arguments passing use a quoted, blank separated
25                         sequence of words like: <literal>scilab -args 'foo1
26                             foo2'
27                         </literal>
28                         .Without this option, unknown arguments will not
29                         be accepted.
30                     </para>
31                 </listitem>
32             </varlistentry>
33             <varlistentry>
34                 <term>-display Display</term>
35                 <listitem>
36                     <para>
37                         For use under Xwindow systems only to set a specific X server
38                         display. Default display is unix:0.0.
39                     </para>
40                     <para>
41                         <literal>-display</literal> can be abbreviated by
42                         <literal>-d</literal>.
43                     </para>
44                 </listitem>
45             </varlistentry>
46             <varlistentry>
47                 <term>-debug</term>
48                 <listitem>
49                     <para>Start Scilab under the debugger gdb (Unix/Linux/Mac OS X only).</para>
50                     <para>
51                         Define the variable <literal>SCILAB_GDB_OPT</literal> to add custom options to
52                         gdb.
53                     </para>
54                     <para>Advice: use this option on a Scilab source tree.</para>
55                 </listitem>
56             </varlistentry>
57             <varlistentry>
58                 <term>-debug-kdbg</term>
59                 <listitem>
60                     <para>Start Scilab under kdbg (Unix/Linux/Mac OS X only).</para>
61                     <para>Advice: use this option on a Scilab source tree.</para>
62                 </listitem>
63             </varlistentry>
64             <varlistentry>
65                 <term>-profiling</term>
66                 <listitem>
67                     <para>Start Scilab under valgrind (Unix/Linux/Mac OS X only).</para>
68                     <para>Define the variable SCILAB_VALGRIND_OPT to add custom options
69                         to valgrind (and override the existing valgrind options).
70                     </para>
71                     <para>Advice: use this option on a Scilab source tree.</para>
72                 </listitem>
73             </varlistentry>
74             <varlistentry>
75                 <term>-profiling-visu</term>
76                 <listitem>
77                     <para>Start Scilab under callgrind (Unix/Linux/Mac OS X only).</para>
78                     <para>Define the variable SCILAB_VALGRIND_OPT to add custom options
79                         to callgrind (and override the existing callgrind options).
80                     </para>
81                     <para>Advice: use this option on a Scilab source tree.</para>
82                 </listitem>
83             </varlistentry>
84             <varlistentry>
85                 <term>-electric-fence</term>
86                 <listitem>
87                     <para>Start Scilab with the Electric Fence (Unix/Linux/Mac OS X only).</para>
88                     <para>Advice: use this option on a Scilab source tree.</para>
89                 </listitem>
90             </varlistentry>
91             <varlistentry>
92                 <term>-e Instruction</term>
93                 <listitem>
94                     <para>If this option is present then Scilab instruction
95                         <literal>Instruction</literal> is executed first (just after startup
96                         file execution) into Scilab. <literal>-e</literal> and
97                         <literal>-f</literal> options are mutually exclusive.
98                     </para>
99                     <para>
100                         Note that several instructions can be used in with <literal>-e</literal>.
101                     </para>
102                     <programlisting role="no-scilab-exec">scilab-cli -e  "a=1+%i; aPlusPi=a+%pi; disp(aPlusPi);exit;" -nb</programlisting>
103                 </listitem>
104             </varlistentry>
105             <varlistentry>
106                 <term>-f file</term>
107                 <listitem>
108                     <para>If this option is present then Scilab script
109                         <literal>file</literal> is executed first (just after startup file
110                         execution) into Scilab. <literal>-e</literal> and
111                         <literal>-f</literal> options are mutually exclusive.
112                     </para>
113                     <para>A file with .xcos extension will be opened by Xcos.</para>
114                 </listitem>
115             </varlistentry>
116             <varlistentry>
117                 <term>-quit</term>
118                 <listitem>
119                     <para>
120                         This option forces scilab to always exit after the instruction(s) passed with the <literal>-e</literal>
121                         option, or the script referred to by the <literal>-f</literal> option, have been executed,
122                         even in case of a runtime error. This option should always be used in batch mode.
123                         It is ignored if neither <literal>-e</literal> nor <literal>-f</literal> options are present.
124                     </para>
125                 </listitem>
126             </varlistentry>
127             <varlistentry>
128                 <term>-l lang</term>
129                 <listitem>
130                     <para>If this option is present it fixes the user language.
131                         <emphasis>lang</emphasis> can be: <emphasis>ca_ES de_DE en_US es_ES
132                             fr_FR ja_JP pt_BR ru_RU zh_CN zh_TW
133                         </emphasis>
134                         (from Scilab
135                         5.2).
136                     </para>
137                     <para>
138                         Other possible <literal>lang</literal> values are
139                         <literal>'fr'</literal> for french and <literal>'en'</literal> for
140                         English for compatibility reasons. The default language is English.
141                         This default value is fixed the <literal>scilab.start</literal>
142                         file.
143                     </para>
144                     <para>On some systems, locales must be compiled to render correctly
145                         UTF-8 fonts.
146                     </para>
147                     <para>Scilab can be also called the following way:</para>
148                     <programlisting role="no-scilab-exec">LANG=ja_JP scilab
149                         # equivalent to
150                         scilab -l ja_JP
151                     </programlisting>
152                 </listitem>
153             </varlistentry>
154             <varlistentry>
155                 <term>-nb</term>
156                 <listitem>
157                     <para>If this option is present then the Scilab loading message not displayed.
158                     </para>
159                 </listitem>
160             </varlistentry>
161             <varlistentry>
162                 <term>-ns</term>
163                 <listitem>
164                     <para>If this option is present the startup file
165                         <literal>SCI/etc/scilab.start</literal> and the user startup files
166                         <literal>SCIHOME/.scilab</literal>,
167                         <literal>SCIHOME/scilab.ini</literal> are not executed.
168                     </para>
169                     <para>This option will disable many features in Scilab (Only use if
170                         you know what you are doing).
171                     </para>
172                 </listitem>
173             </varlistentry>
174             <varlistentry>
175                 <term>-nouserstartup</term>
176                 <listitem>
177                     <para>If this option is present the user startup files
178                         <literal>SCIHOME/.scilab</literal>,
179                         <literal>SCIHOME/scilab.ini</literal> are not executed.
180                     </para>
181                 </listitem>
182             </varlistentry>
183             <varlistentry>
184                 <term>-noatomsautoload</term>
185                 <listitem>
186                     <para>If this option is present the ATOMS modules previously installed are not loaded for this session.</para>
187                 </listitem>
188             </varlistentry>
189             <varlistentry>
190                 <term>-nw</term>
191                 <listitem>
192                     <para>If this option is present, Scilab is started as command line
193                         with advanced features still available (graphics, export, xcos, scinotes, help browser, ...).
194                     </para>
195                     <para>
196                         This option may be used with <literal>-f</literal> or <literal>-e</literal> options.
197                     </para>
198                     <para>From Scilab 5.2:</para>
199                     <itemizedlist>
200                         <listitem>
201                             <para>Scilab distribution also provides a dedicated binary which
202                                 is doing the same as <literal>-nw</literal>: <literal>scilab-adv-cli</literal> (Scilab Advanced
203                                 Command Line Interpreter).
204                             </para>
205                         </listitem>
206                         <listitem>
207                             <para>pipes are enabled for all operating systems (see the
208                                 examples for further details).
209                             </para>
210                         </listitem>
211                     </itemizedlist>
212                 </listitem>
213             </varlistentry>
214             <varlistentry>
215                 <term>-nwni / -nogui</term>
216                 <listitem>
217                     <para>If this option is present, Scilab is started as command line
218                         without advanced features (graphics, export, xcos, scinotes, help browser, ...).
219                     </para>
220                     <para>
221                         This option may be used with <literal>-f</literal> or <literal>-e</literal> options.
222                     </para>
223                     <para>From Scilab 5.2:</para>
224                     <itemizedlist>
225                         <listitem>
226                             <para>Scilab distribution also provides a dedicated binary which
227                                 is doing the same as <literal>-nwni</literal>: <literal>scilab-cli</literal> (Scilab Command Line Interpreter).
228                             </para>
229                         </listitem>
230                     </itemizedlist>
231                     <itemizedlist>
232                         <listitem>
233                             <para>pipes are enabled for all operating systems (see the
234                                 examples for further details).
235                             </para>
236                         </listitem>
237                     </itemizedlist>
238                     <para>This mode does not load the Java Virtual Machine (faster to
239                         start and uses less memory).
240                     </para>
241                 </listitem>
242             </varlistentry>
243             <varlistentry>
244                 <term>--texmacs</term>
245                 <listitem>
246                     <para>This option is reserved for TeXMacs.</para>
247                     <para>
248                         Please install ATOMS module: <programlisting role="">atomsInstall('texmacs')</programlisting>
249                     </para>
250                 </listitem>
251             </varlistentry>
252             <varlistentry>
253                 <term>-version</term>
254                 <listitem>
255                     <para>This option prints product version and exits.</para>
256                 </listitem>
257             </varlistentry>
258         </variablelist>
259     </refsection>
260     <refsection role="description">
261         <title>Description of environment variables</title>
262         <variablelist>
263             <varlistentry>
264                 <term>SCIVERBOSE</term>
265                 <listitem>
266                     <para>
267                         If this variable is present, Scilab startup script will show a startup debug information.
268                         Mainly used for bug report and debugging purposes.
269                     </para>
270                 </listitem>
271             </varlistentry>
272             <varlistentry>
273                 <term>JAVA_HOME</term>
274                 <listitem>
275                     <para>
276                         Specify which Java to use. For example,
277                         <literal>JAVA_HOME=/usr/lib/jvm/java-7-openjdk/ scilab</literal> will start Scilab with Java 7.
278                     </para>
279                 </listitem>
280             </varlistentry>
281             <varlistentry>
282                 <term>SCI_DISABLE_TK</term>
283                 <listitem>
284                     <para>Disable Tk (but not Tcl) features.</para>
285                 </listitem>
286             </varlistentry>
287             <varlistentry>
288                 <term>SCI_JAVA_ENABLE_HEADLESS</term>
289                 <listitem>
290                     <para>
291                         Enable Java Headless VM (i.e. without GUI features).
292                     </para>
293                 </listitem>
294             </varlistentry>
295         </variablelist>
296     </refsection>
297     <refsection role="description">
298         <title>Java Virtual Machine options</title>
299         <para>Starting from Scilab 5.0, the graphical user interface (GUI) and the
300             build documentation are based on Java features. In some cases, it can be
301             important to edit the JVM options (Java Virtual Machine).
302         </para>
303         <para>These options are available in the
304             <emphasis>jvm_options.xml</emphasis> file.
305         </para>
306         <para>In version 5.0.X and 5.1.X, this file is stored as
307             <emphasis>SCI/modules/jvm/etc/jvm_options.xml</emphasis>.
308         </para>
309         <para>In version &gt;= 5.2.0, the file is available in
310             <emphasis>etc/jvm_options.xml</emphasis>.
311         </para>
312         <para>
313             <emphasis>
314                 By default, the three following options are
315                 easily accessible in the configuration file:
316             </emphasis>
317         </para>
318         <variablelist>
319             <varlistentry>
320                 <term>-XmxXXXm</term>
321                 <listitem>
322                     <para>This option set the amount of memory available by the Java
323                         Virtual Machine. By default, 256M are allocated. If you change this
324                         value, check that the value does not exceed the memory available on
325                         the system.
326                     </para>
327                     <para>Since Scilab 5.4.0, this value can be changed in the preferences menu.</para>
328                 </listitem>
329             </varlistentry>
330             <varlistentry>
331                 <term>-Djava.compiler=JIT</term>
332                 <listitem>
333                     <para>
334                         This option with the argument <emphasis>JIT</emphasis> enables
335                         the Java Just In Time compiler. It is activated by default.
336                         <emphasis>NONE</emphasis> disables the JIT and decreases
337                         dramatically performances.
338                     </para>
339                 </listitem>
340             </varlistentry>
341             <varlistentry>
342                 <term>-verbose:jni / -Xcheck:jni</term>
343                 <listitem>
344                     <para>These options enable more checks and output from the JNI
345                         calls. These options are useful in case of debugging and are
346                         disabled by default since they decreases performances.
347                     </para>
348                 </listitem>
349             </varlistentry>
350         </variablelist>
351         <para>Many more options are available. They can improve the performances,
352             change look and feel, change memory managements... See: <ulink url="http://www.oracle.com/technetwork/java/javase/tech/vmoptions-jsp-140102.html">http://www.oracle.com/technetwork/java/javase/tech/vmoptions-jsp-140102.html</ulink>.
353         </para>
354     </refsection>
355     <refsection role="examples">
356         <title>Examples</title>
357         <programlisting role="no-scilab-exec"><![CDATA[
358 # Let's start Scilab in profiling mode without attaching a gdb once a SIGSEGV is met.
359 # We are under Bash shell
360 export SCILAB_VALGRIND_OPT="--db-attach=no --log-file=myfile.txt"
361 scilab -profiling
362
363 # Let's start Scilab in debug mode without stopping after each SIGSEGV
364 # First, we write a small command file
365 echo "handle SIGSEGV nostop" &> debug.txt
366 # Now set the custom option
367 # We are under Bash shell
368 export SCILAB_GDB_OPT="--command=debug.txt"
369 # Start Scilab in debug mode
370 scilab -debug]]></programlisting>
371         <programlisting role="no-scilab-exec"><![CDATA[
372 # Under GNU/Linux, Mac OS X or Unix:
373 $ echo "disp(%pi)"|scilab-cli
374 or
375 $ echo "disp(%pi)"|scilab -nwni
376
377 # Only open the Scilab help window:
378 $ scilab-adv-cli -e "help()"
379 or
380 $ scilab -nw -e "help()"
381
382
383 # Scilab can be used for scripting aspects:
384 echo "if 1<>2 then exit(99) end"|scilab-cli
385 echo $? ]]></programlisting>
386     </refsection>
387     <refsection role="see also">
388         <title>See also</title>
389         <simplelist type="inline">
390             <member>
391                 <link linkend="exit">exit</link>
392             </member>
393             <member>
394                 <link linkend="startup">startup</link>
395             </member>
396         </simplelist>
397     </refsection>
398     <refsection role="history">
399         <title>History</title>
400         <revhistory>
401             <revision>
402                 <revnumber>5.4.0</revnumber>
403                 <revremark>-noatomsautoload added.</revremark>
404             </revision>
405             <revision>
406                 <revnumber>5.4.1</revnumber>
407                 <revremark>scinotes and xcos individual scripts introduced. See SEP #87.</revremark>
408             </revision>
409             <revision>
410                 <revnumber>6.0.0</revnumber>
411                 <revremark>
412                     <literal>-quit</literal> option added. <literal>-mem</literal> option removed.
413                 </revremark>
414             </revision>
415         </revhistory>
416     </refsection>
417 </refentry>