1 <?xml version="1.0" encoding="UTF-8"?>
2 <refentry xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink"
3 xmlns:svg="http://www.w3.org/2000/svg" xmlns:ns4="http://www.w3.org/1999/xhtml"
4 xmlns:mml="http://www.w3.org/1998/Math/MathML" xmlns:db="http://docbook.org/ns/docbook"
5 xmlns:scilab="http://www.scilab.org" xml:id="scilab" xml:lang="en">
6 <refnamediv xml:id="wscilex">
8 <refnamediv xml:id="scilex">
11 <refname>scilex | scilab</refname>
12 <refpurpose>runs Scilab in interactive or batch mode with command line options
18 # MS Windows | # Linux / Unix / Mac OS X
19 wscilex <Options> | scilab <Options>
20 wscilex -nw <Options> | scilab-adv-cli <Options>
21 scilex <Options> | scilab-cli <Options>
24 <refsection role="arguments">
25 <title>Options</title>
28 <term>-args arg#1 arg#2 ..</term>
31 This option allows to send some data to the Scilab session:
33 <listitem>Consecutive data are separated by one or several spaces.
35 <listitem>An expression between double-quotes is a single data.
37 <listitem>To include a double-quote in a data, write <literal>\"</literal> instead of <literal>"</literal>.
39 <listitem>The single quote <literal>'</literal> is a regular character. It has no special meaning.
44 Inside the opened session, these data can be retrieved as separated strings with <link linkend="sciargs">sciargs()</link>.
48 <screen><![CDATA[C:\Users\Me> scilex -nb -args "Hello \"%USERNAME%\"" 1.2345 \"%cd%\"]]></screen>
49 <programlisting><![CDATA[
50 // Inside the opened session:
55 "This session has been launched from " + a(i+3)
59 --> // Inside the opened session:
62 !c:\SCIdir\bin\scilex -nw -nb -noatomsautoload -args Hello "John" 1.2345 "C:\Users\Me" !
64 --> i = find(a=="-args")
76 --> "This session has been launched from " + a(i+3)
78 This session has been launched from "C:\Users\Me"
84 <note>Using <literal>-args</literal> as the <emphasis role="italic">last</emphasis> command line option is safer.
90 <term>-display Display</term>
93 For use under Xwindow systems only to set a specific X server
94 display. Default display is unix:0.0.
97 <literal>-display</literal> can be abbreviated by
98 <literal>-d</literal>.
103 <term>-e Instructions</term>
106 At the end of the whole session startup, this option
109 <para>sets the current working directory to the shell directory from which Scilab has been launched. Please see the example given here-below for the <literal>-f</literal> option. Then,
113 <para>executes Scilab <literal>Instructions</literal> provided in a string. Example:
114 <screen><![CDATA[ scilab-cli -e "disp(\"Hello\"); a=%pi+%i; disp(exp(a)); exit;" -nb]]></screen>
120 <literal>-e</literal> and <literal>-f</literal> options can't be used together.
128 If this option is used, then at the beginning of the Scilab session, after the execution of the scilab and user startup files, and after the setting of user Preferences -- including the working directory ones --,
132 the current Scilab working directory is set to the shell directory from which Scilab has been launched. For instance,
133 <screen><![CDATA[ D:\users\me\scilab\dev> C:\scilab-5.5.2\bin\scilex -f ..\test.sce]]></screen>
134 will do a <literal>cd("D:\users\me\scilab\dev")</literal>.
139 the Scilab script <literal>file</literal> is executed. If a relative path is used (default <literal>.\</literal>, or like <literal>..\</literal> in the sample here-above), it refers to the new Scilab working directory.
145 A file with .xcos extension will be opened by Xcos.
153 This option forces scilab to always exit after the instruction(s) passed with the <literal>-e</literal>
154 option, or the script referred to by the <literal>-f</literal> option, have been executed,
155 even in case of a runtime error. This option should always be used in batch mode.
156 It is ignored if neither <literal>-e</literal> nor <literal>-f</literal> options are present.
163 <para>If this option is present it fixes the user language.
164 <emphasis>lang</emphasis> can be: <emphasis>ca_ES de_DE en_US es_ES
165 fr_FR ja_JP pt_BR ru_RU zh_CN zh_TW
166 </emphasis> (from Scilab 5.2).
169 Other possible <literal>lang</literal> values are
170 <literal>'fr'</literal> for french and <literal>'en'</literal> for
171 English for compatibility reasons. The default language is English.
172 This default value is fixed the <literal>scilab.start</literal> file.
174 <para>On some systems, locales must be compiled to render correctly
177 <para>Scilab can be also called the following way:</para>
178 <screen><![CDATA[ LANG=ja_JP scilab
187 <para>"no banner": Cancels the display of the Scilab's loading message.
194 <para>"No Startup files": Cancels the execution of the main startup file
195 <literal>SCI/etc/scilab.start</literal> and of the user startup files
196 <literal>SCIHOME/.scilab</literal>,
197 <literal>SCIHOME/scilab.ini</literal>.
199 <para>This option will disable many features in Scilab (Only use if
200 you know what you are doing).
205 <term>-nouserstartup</term>
207 <para>Cancels the execution of the user startup files
208 <literal>SCIHOME/.scilab</literal> and
209 <literal>SCIHOME/scilab.ini</literal>.
214 <term>-noatomsautoload</term>
216 <para>Cancels the autoloading of installed ATOMS modules at startup.</para>
222 <para>If this option is present, Scilab is started as command line
223 with advanced features still available (graphics, export, xcos, scinotes, help browser, ...).
225 <para>From Scilab 5.2:</para>
228 <para>pipes are enabled for all operating systems (see the
229 examples for further details).
233 <para>Scilab distribution also provides a dedicated binary which
234 is doing the same as <literal>-nw</literal>:
235 <literal>scilab-adv-cli</literal> (Scilab Advanced Command Line Interpreter).
242 <term>-nwni / -nogui</term>
245 This mode prevents loading the Java Virtual Machine.
246 It starts faster and uses less memory.
248 <para>If this option is present, Scilab is started as command line
249 without advanced features (graphics, export, xcos, scinotes,
250 help browser, Java module,...).
252 <para>Since Scilab 5.2:</para>
255 <para>pipes are enabled for all operating systems (see the
256 examples for further details).
262 <para>Scilab distribution also provides a dedicated binary which
263 is doing the same as <literal>-nwni</literal>:
264 <literal>scilab-cli</literal> (Scilab Command Line Interpreter).
271 <term>--texmacs</term>
273 <para>This option is reserved for the external TeXMacs module.
274 This one can be priorly installed with <code>atomsInstall('texmacs')</code>.
279 <term>-version</term>
281 <para>displays the Scilab's version (before the main Scilab's startup).</para>
286 <refsection role="arguments">
287 <title>Additional options for Unix/Linux and Mac OS X</title>
288 <para>Advice: use theses options on a Scilab source tree.</para>
293 <para>Start Scilab under the debugger gdb.</para>
295 The variable <literal>SCILAB_GDB_OPT</literal> may be set to add custom options to gdb.
300 <term>-debug-kdbg</term>
302 <para>Start Scilab under kdbg.</para>
306 <term>-profiling</term>
308 <para>Start Scilab under valgrind.</para>
309 <para>The variable SCILAB_VALGRIND_OPT may be set to add custom options
310 to valgrind (and override the existing valgrind options).
315 <term>-profiling-visu</term>
317 <para>Start Scilab under callgrind.</para>
318 <para>The variable SCILAB_VALGRIND_OPT may be set to add custom options
319 to callgrind (and override the existing callgrind options).
324 <term>-electric-fence</term>
326 <para>Start Scilab with the Electric Fence.</para>
331 <refsection role="description">
332 <title>Environment variables</title>
335 <term>SCIVERBOSE</term>
338 If this variable is present, Scilab startup script will show a startup debug information.
339 Mainly used for bug report and debugging purposes.
344 <term>JAVA_HOME</term>
347 Specify which Java to use. For example,
348 <literal>JAVA_HOME=/usr/lib/jvm/java-7-openjdk/ scilab</literal> will start Scilab with Java 7.
353 <term>SCI_DISABLE_TK</term>
355 <para>Disable Tk (but not Tcl) features.</para>
359 <term>SCI_JAVA_ENABLE_HEADLESS</term>
362 Enable Java Headless VM (i.e. without GUI features).
368 <refsection role="description">
369 <title>Java Virtual Machine options</title>
371 The options described here-below are useless and are cancelled if the option <literal>-nwni</literal> is used.
373 <para>Starting from Scilab 5.0, the graphical user interface (GUI) and the
374 build documentation are based on Java features. In some cases, it can be
375 important to edit the JVM options (Java Virtual Machine).
377 <para>These options are available in the
378 <emphasis>jvm_options.xml</emphasis> file.
380 <para>In version 5.0.X and 5.1.X, this file is stored as
381 <emphasis>SCI/modules/jvm/etc/jvm_options.xml</emphasis>.
383 <para>In version >= 5.2.0, the file is available in
384 <emphasis>etc/jvm_options.xml</emphasis>.
388 By default, the three following options are
389 easily accessible in the configuration file:
394 <term>-XmxXXXm</term>
396 <para>This option set the amount of memory available by the Java
397 Virtual Machine. By default, 256M are allocated. If you change this
398 value, check that the value does not exceed the memory available on
401 <para>Since Scilab 5.4.0, this value can be changed in the preferences menu.</para>
405 <term>-Djava.compiler=JIT</term>
408 This option with the argument <emphasis>JIT</emphasis> enables
409 the Java Just In Time compiler. It is activated by default.
410 <emphasis>NONE</emphasis> disables the JIT and decreases
411 dramatically performances.
416 <term>-verbose:jni / -Xcheck:jni</term>
418 <para>These options enable more checks and output from the JNI
419 calls. These options are useful in case of debugging and are
420 disabled by default since they decreases performances.
425 <para>Many more options are available. They can improve the performances,
426 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>.
429 <refsection role="examples">
430 <title>Examples</title>
432 # Let's start Scilab in profiling mode without attaching a gdb once a SIGSEGV is met.
433 # We are under Bash shell
434 export SCILAB_VALGRIND_OPT="--db-attach=no --log-file=myfile.txt"
437 # Let's start Scilab in debug mode without stopping after each SIGSEGV
438 # First, we write a small command file
439 echo "handle SIGSEGV nostop" &> debug.txt
440 # Now set the custom option
441 # We are under Bash shell
442 export SCILAB_GDB_OPT="--command=debug.txt"
443 # Start Scilab in debug mode
444 scilab -debug ]]></screen>
447 # Under GNU/Linux, Mac OS X or Unix:
448 $ echo "disp(%pi)"|scilab-cli
450 $ echo "disp(%pi)"|scilab -nwni
452 # Only open the Scilab help window:
453 $ scilab-adv-cli -e "help()"
455 $ scilab -nw -e "help()"
458 # Scilab can be used for scripting aspects:
459 echo "if 1<>2 then exit(99) end"|scilab-cli
462 <refsection role="see also">
463 <title>See also</title>
464 <simplelist type="inline">
466 <link linkend="startup">startup</link>
469 <link linkend="sciargs">sciargs</link>
472 <link linkend="getpid">getpid</link>
475 <link linkend="getenv">getenv</link>
478 <link linkend="getenv">getversion</link>
481 <link linkend="consolebox">consolebox</link>
484 <link linkend="exit">exit</link>
488 <refsection role="history">
489 <title>History</title>
492 <revnumber>5.4.0</revnumber>
493 <revremark>-noatomsautoload added.</revremark>
496 <revnumber>5.4.1</revnumber>
497 <revremark>scinotes and xcos individual scripts introduced. See SEP #87.</revremark>
500 <revnumber>6.0.0</revnumber>
502 <literal>-quit</literal> option added. <literal>-mem</literal> option removed.