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"
   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>
   7         <refname>scilab</refname>
   8             <refpurpose>runs Scilab in interactive or batch mode with command line options
   9         </refpurpose>
  10     </refnamediv>
  11     <refsynopsisdiv>
  12         <title>Syntax</title>
  13         <synopsis>
  14 scilab &lt;Options&gt;
  15         </synopsis>
  16     </refsynopsisdiv>
  17     <refsection role="arguments">
  18         <title>Options</title>
  19         <variablelist>
  20             <varlistentry>
  21                 <term>-args arg#1 arg#2 ..</term>
  22                 <listitem>
  23                     <para>
  24                         This option allows to send some data to the Scilab session:
  25                         <itemizedlist>
  26                             <listitem>Consecutive data are separated by one or several spaces.
  27                             </listitem>
  28                             <listitem>An expression between double-quotes is a single data.
  29                             </listitem>
  30                             <listitem>To include a double-quote in a data, write <literal>\"</literal> instead of <literal>"</literal>.
  31                             </listitem>
  32                             <listitem>The single quote <literal>'</literal> is a regular character. It has no special meaning.
  33                             </listitem>
  34                         </itemizedlist>
  35                     </para>
  36                     <para>
  37                       Inside the opened session, these data can be retrieved as separated strings with <link linkend="sciargs">sciargs()</link>.
  38                      </para>
  39                      <para>
  40                       Example:
  41                         <screen><![CDATA[C:\Users\Me> scilex -nb -noatomsautoload -args "Hello \"%USERNAME%\"" 1.2345 \"%cd%\"]]></screen>
  42                         <programlisting><![CDATA[
  43 // Inside the opened session:
  44 a = sciargs()
  45 i = find(a=="-args")
  46 a(i+1)
  47 evstr(a(i+2))*2
  48 "This session has been launched from " + a(i+3)
  49                         ]]>
  50                         </programlisting>
  51                         <screen><![CDATA[
  52 --> // Inside the opened session:
  53 --> a = sciargs()
  54  a  =
  55 !c:\SCIdir\bin\scilex  -nw  -nb  -noatomsautoload  -args  Hello "John"  1.2345  "C:\Users\Me" !
  56
  57 --> i = find(a=="-args")
  58  i  =
  59     5.
  60
  61 --> a(i+1)
  62  ans  =
  63  Hello "John"
  64
  65 --> evstr(a(i+2))*2
  66  ans  =
  67     2.469
  68
  69 --> "This session has been launched from " + a(i+3)
  70  ans  =
  71  This session has been launched from "C:\Users\Me"
  72 ]]></screen>
  73                      </para>
  74                      <para>
  75                      <note>Using <literal>-args</literal> as the <emphasis role="italic">last</emphasis> command line option is safer.
  76                      </note>
  77                      </para>
  78                 </listitem>
  79             </varlistentry>
  80             <varlistentry>
  81                 <term>-display Display</term>
  82                 <listitem>
  83                     <para>
  84                         For use under Xwindow systems only to set a specific X server
  85                         display. Default display is unix:0.0.
  86                     </para>
  87                     <para>
  88                         <literal>-display</literal> can be abbreviated by
  89                         <literal>-d</literal>.
  90                     </para>
  91                 </listitem>
  92             </varlistentry>
  93             <varlistentry>
  94                 <term>-e Instructions</term>
  95                 <listitem>
  96                     <para>
  97                         At the end of the whole session startup, this option
  98                         <itemizedlist>
  99                             <listitem>
 100                                 <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,
 101                                 </para>
 102                             </listitem>
 103                             <listitem>
 104                                 <para>executes Scilab <literal>Instructions</literal> provided in a string. Example:
 105                                     <screen><![CDATA[ scilab-cli -e  "disp(\"Hello\"); a=%pi+%i; disp(exp(a)); exit;" -nb]]></screen>
 106                                 </para>
 107                             </listitem>
 108                         </itemizedlist>
 109                     </para>
 110                     <warning>
 111                         <literal>-e</literal> and <literal>-f</literal> options can't be used together.
 112                     </warning>
 113                 </listitem>
 114             </varlistentry>
 115             <varlistentry>
 116                 <term>-f file</term>
 117                 <listitem>
 118                     <para>
 119                         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 --,
 120                         <itemizedlist>
 121                             <listitem>
 122                                 <para>
 123                                     the current Scilab working directory is set to the shell directory from which Scilab has been launched. For instance,
 124                                     <screen><![CDATA[ D:\users\me\scilab\dev> C:\scilab-5.5.2\bin\scilex -f ..\test.sce]]></screen>
 125                                     will do a <literal>cd("D:\users\me\scilab\dev")</literal>.
 126                                 </para>
 127                             </listitem>
 128                             <listitem>
 129                                 <para>
 130                                     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.
 131                                 </para>
 132                             </listitem>
 133                         </itemizedlist>
 134                     </para>
 135                     <para>
 136                         A file with .xcos extension will be opened by Xcos.
 137                     </para>
 138                 </listitem>
 139             </varlistentry>
 140             <varlistentry>
 141                 <term>-quit</term>
 142                 <listitem>
 143                     <para>
 144                         This option forces scilab to always exit after the instruction(s) passed with the <literal>-e</literal>
 145                         option, or the script referred to by the <literal>-f</literal> option, have been executed,
 146                         even in case of a runtime error. This option should always be used in batch mode.
 147                         It is ignored if neither <literal>-e</literal> nor <literal>-f</literal> options are present.
 148                     </para>
 149                 </listitem>
 150             </varlistentry>
 151             <varlistentry>
 152                 <term>-l lang</term>
 153                 <listitem>
 154                     <para>If this option is present it fixes the user language.
 155                         <emphasis>lang</emphasis> can be: <emphasis>ca_ES de_DE en_US es_ES
 156                             fr_FR ja_JP pt_BR ru_RU zh_CN zh_TW
 157                         </emphasis> (from Scilab 5.2).
 158                     </para>
 159                     <para>
 160                         Other possible <literal>lang</literal> values are
 161                         <literal>'fr'</literal> for french and <literal>'en'</literal> for
 162                         English for compatibility reasons. The default language is English.
 163                         This default value is fixed the <literal>scilab.start</literal> file.
 164                     </para>
 165                     <para>On some systems, locales must be compiled to render correctly
 166                         UTF-8 fonts.
 167                     </para>
 168                     <para>Scilab can be also called the following way:</para>
 169                     <screen><![CDATA[ LANG=ja_JP scilab
 170  # equivalent to
 171  scilab -l ja_JP
 172 ]]></screen>
 173                 </listitem>
 174             </varlistentry>
 175             <varlistentry>
 176                 <term>-nb</term>
 177                 <listitem>
 178                     <para>"no banner": Cancels the display of the Scilab's loading message.
 179                     </para>
 180                 </listitem>
 181             </varlistentry>
 182             <varlistentry>
 183                 <term>-ns</term>
 184                 <listitem>
 185                     <para>"No Startup files": Cancels the execution of the main startup file
 186                         <literal>SCI/etc/scilab.start</literal> and of the user startup files
 187                         <literal>SCIHOME/.scilab</literal>,
 188                         <literal>SCIHOME/scilab.ini</literal>.
 189                     </para>
 190                     <para>This option will disable many features in Scilab (Only use if
 191                         you know what you are doing).
 192                     </para>
 193                 </listitem>
 194             </varlistentry>
 195             <varlistentry>
 196                 <term>-nouserstartup</term>
 197                 <listitem>
 198                     <para>Cancels the execution of the user startup files
 199                         <literal>SCIHOME/.scilab</literal> and
 200                         <literal>SCIHOME/scilab.ini</literal>.
 201                     </para>
 202                 </listitem>
 203             </varlistentry>
 204             <varlistentry>
 205                 <term>-noatomsautoload</term>
 206                 <listitem>
 207                     <para>Cancels the autoloading of installed ATOMS modules at startup.</para>
 208                 </listitem>
 209             </varlistentry>
 210             <varlistentry>
 211                 <term>-nw</term>
 212                 <listitem>
 213                     <para>If this option is present, Scilab is started as command line
 214                         with advanced features still available (graphics, export, xcos, scinotes, help browser, ...).
 215                     </para>
 216                     <para>
 217                         From Scilab 5.2:
 218                         <itemizedlist>
 219                             <listitem>
 220                                 <para>pipes are enabled for all operating systems (see the
 221                                     examples for further details).
 222                                 </para>
 223                             </listitem>
 224                             <listitem>
 225                                 <para>Scilab distribution also provides a dedicated binary which
 226                                     is doing the same as <literal>-nw</literal>:
 227                                     <itemizedlist>
 228                                         <listitem>
 229                                             Windows: <literal>WScilex-cli.exe</literal>.
 230                                         </listitem>
 231                                         <listitem>
 232                                             <literal>scilab-adv-cli</literal> (Scilab Advanced Command Line Interpreter).
 233                                         </listitem>
 234                                     </itemizedlist>
 235                                 </para>
 236                             </listitem>
 237                         </itemizedlist>
 238                     </para>
 239                 </listitem>
 240             </varlistentry>
 241             <varlistentry>
 242                 <term>-nwni / -nogui</term>
 243                 <listitem>
 244                     <important>
 245                         This mode prevents loading the Java Virtual Machine.
 246                         It starts faster and uses less memory. But then...
 247                     </important>
 248                     <warning>
 249                         Scilab is started as command line interpreter without any advanced features
 250                         requiring the JVM: graphics, export, xcos, scinotes, help browser, other
 251                         java interfaces, the Java module,... are not available.
 252                     </warning>
 253                     <para>
 254                         Since Scilab 5.2:
 255                         <itemizedlist>
 256                             <listitem>
 257                                 <para>pipes are enabled for all operating systems (see the
 258                                     examples for further details).
 259                                 </para>
 260                             </listitem>
 261                         </itemizedlist>
 262                         <itemizedlist>
 263                             <listitem>
 264                                 <para>Scilab distribution also provides a dedicated binary which
 265                                     is doing the same as <literal>-nwni</literal>:
 266                                     <itemizedlist>
 267                                         <listitem>
 268                                             Windows: <literal>Scilex.exe</literal>.
 269                                         </listitem>
 270                                         <listitem>
 271                                             Others: <literal>scilab-cli</literal> (Scilab Command Line Interpreter).
 272                                         </listitem>
 273                                     </itemizedlist>
 274                                 </para>
 275                             </listitem>
 276                         </itemizedlist>
 277                     </para>
 278                 </listitem>
 279             </varlistentry>
 280             <varlistentry>
 281                 <term>-scihome dir</term>
 282                 <listitem>
 283                     <para>Forces SCIHOME to the <literal>dir</literal> directory. If the path
 284                       includes some white space, it must be specified between double-quotes (no
 285                       single quotes!).
 286                       if <literal>dir</literal> is a relative path, <literal>dir</literal> is add to parent standard SCIHOME folder.
 287                       On Windows: %USERPROFILE%\AppData\Roaming\Scilab\<literal>dir</literal>
 288                       On Linux/MacOS: ~/.Scilab/<literal>dir</literal>
 289                     </para>
 290                 </listitem>
 291             </varlistentry>
 292             <varlistentry>
 293                 <term>--texmacs</term>
 294                 <listitem>
 295                     <para>This option is reserved for the external TeXMacs module.
 296                         This one can be priorly installed with <code>atomsInstall('texmacs')</code>.
 297                     </para>
 298                 </listitem>
 299             </varlistentry>
 300             <varlistentry>
 301                 <term>-version</term>
 302                 <listitem>
 303                     <para>displays the Scilab's version (before the main Scilab's startup).</para>
 304                 </listitem>
 305             </varlistentry>
 306         </variablelist>
 307     </refsection>
 308     <refsection role="arguments">
 309         <title>Additional options for Unix/Linux and Mac OS X</title>
 310         <para>Advice: use theses options on a Scilab source tree.</para>
 311         <variablelist>
 312             <varlistentry>
 313                 <term>-debug</term>
 314                 <listitem>
 315                     <para>Start Scilab under the debugger gdb.</para>
 316                     <para>
 317                         The variable <literal>SCILAB_GDB_OPT</literal> may be set to add custom options to gdb.
 318                     </para>
 319                 </listitem>
 320             </varlistentry>
 321             <varlistentry>
 322                 <term>-debug-rr</term>
 323                 <listitem>
 324                     <para>Start Scilab under <ulink url="https://rr-project.org/">rr</ulink>.</para>
 325                 </listitem>
 326             </varlistentry>
 327             <varlistentry>
 328                 <term>-debug-kdbg</term>
 329                 <listitem>
 330                     <para>Start Scilab under kdbg.</para>
 331                 </listitem>
 332             </varlistentry>
 333             <varlistentry>
 334                 <term>-profiling</term>
 335                 <listitem>
 336                     <para>Start Scilab under valgrind.</para>
 337                     <para>The variable SCILAB_VALGRIND_OPT may be set to add custom options
 338                         to valgrind (and override the existing valgrind options).
 339                     </para>
 340                 </listitem>
 341             </varlistentry>
 342             <varlistentry>
 343                 <term>-profiling-visu</term>
 344                 <listitem>
 345                     <para>Start Scilab under callgrind.</para>
 346                     <para>The variable SCILAB_VALGRIND_OPT may be set to add custom options
 347                         to callgrind (and override the existing callgrind options).
 348                     </para>
 349                 </listitem>
 350             </varlistentry>
 351             <varlistentry>
 352                 <term>-electric-fence</term>
 353                 <listitem>
 354                     <para>Start Scilab with the Electric Fence.</para>
 355                 </listitem>
 356             </varlistentry>
 357         </variablelist>
 358     </refsection>
 359     <refsection role="description">
 360         <title>Environment variables</title>
 361         <variablelist>
 362             <varlistentry>
 363                 <term>SCIVERBOSE</term>
 364                 <listitem>
 365                     <para>
 366                         If this variable is present, Scilab startup script will show a startup debug information.
 367                         Mainly used for bug report and debugging purposes.
 368                     </para>
 369                 </listitem>
 370             </varlistentry>
 371             <varlistentry>
 372                 <term>JAVA_HOME</term>
 373                 <listitem>
 374                     <para>
 375                         Specify which Java to use. For example,
 376                         <literal>JAVA_HOME=/usr/lib/jvm/java-7-openjdk/ scilab</literal> will start Scilab with Java 7.
 377                     </para>
 378                 </listitem>
 379             </varlistentry>
 380             <varlistentry>
 381                 <term>SCI_DISABLE_TK</term>
 382                 <listitem>
 383                     <para>Disable Tk (but not Tcl) features.</para>
 384                 </listitem>
 385             </varlistentry>
 386             <varlistentry>
 387                 <term>SCI_JAVA_ENABLE_HEADLESS</term>
 388                 <listitem>
 389                     <para>
 390                         Enable Java Headless VM (i.e. without GUI features).
 391                     </para>
 392                 </listitem>
 393             </varlistentry>
 394         </variablelist>
 395     </refsection>
 396     <refsection role="description">
 397         <title>Java Virtual Machine options</title>
 398         <warning>
 399             The options described here-below are useless and are cancelled if the option <literal>-nwni</literal> is used.
 400         </warning>
 401         <para>Starting from Scilab 5.0, the graphical user interface (GUI) and the
 402             build documentation are based on Java features. In some cases, it can be
 403             important to edit the JVM options (Java Virtual Machine).
 404         </para>
 405         <para>These options are available in the
 406             <emphasis>jvm_options.xml</emphasis> file.
 407         </para>
 408         <para>In version 5.0.X and 5.1.X, this file is stored as
 409             <emphasis>SCI/modules/jvm/etc/jvm_options.xml</emphasis>.
 410         </para>
 411         <para>In version &gt;= 5.2.0, the file is available in
 412             <emphasis>etc/jvm_options.xml</emphasis>.
 413         </para>
 414         <para>
 415             <emphasis>
 416                 By default, the three following options are
 417                 easily accessible in the configuration file:
 418             </emphasis>
 419         </para>
 420         <variablelist>
 421             <varlistentry>
 422                 <term>-XmxXXXm</term>
 423                 <listitem>
 424                     <para>This option set the amount of memory available by the Java
 425                         Virtual Machine. By default, 256M are allocated. If you change this
 426                         value, check that the value does not exceed the memory available on
 427                         the system.
 428                     </para>
 429                     <para>Since Scilab 5.4.0, this value can be changed in the preferences menu.</para>
 430                 </listitem>
 431             </varlistentry>
 432             <varlistentry>
 433                 <term>-Djava.compiler=JIT</term>
 434                 <listitem>
 435                     <para>
 436                         This option with the argument <emphasis>JIT</emphasis> enables
 437                         the Java Just In Time compiler. It is activated by default.
 438                         <emphasis>NONE</emphasis> disables the JIT and decreases
 439                         dramatically performances.
 440                     </para>
 441                 </listitem>
 442             </varlistentry>
 443             <varlistentry>
 444                 <term>-verbose:jni / -Xcheck:jni</term>
 445                 <listitem>
 446                     <para>These options enable more checks and output from the JNI
 447                         calls. These options are useful in case of debugging and are
 448                         disabled by default since they decreases performances.
 449                     </para>
 450                 </listitem>
 451             </varlistentry>
 452         </variablelist>
 453         <para>Many more options are available. They can improve the performances,
 454             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>.
 455         </para>
 456     </refsection>
 457     <refsection role="examples">
 458         <title>Examples</title>
 459         <screen><![CDATA[
 460 # Let's start Scilab in profiling mode without attaching a gdb once a SIGSEGV is met.
 461 # We are under Bash shell
 462 export SCILAB_VALGRIND_OPT="--db-attach=no --log-file=myfile.txt"
 463 scilab -profiling
 464
 465 # Let's start Scilab in debug mode without stopping after each SIGSEGV
 466 # First, we write a small command file
 467 echo "handle SIGSEGV nostop" > debug.txt
 468 # Now set the custom option
 469 # We are under Bash shell
 470 export SCILAB_GDB_OPT="--command=debug.txt"
 471 # Start Scilab in debug mode
 472 scilab -debug ]]></screen>
 473         <para></para>
 474         <screen><![CDATA[
 475 # Under GNU/Linux, Mac OS X or Unix:
 476 $ echo "disp(%pi)"|scilab-cli
 477 or
 478 $ echo "disp(%pi)"|scilab -nwni
 479
 480 # Only open the Scilab help window:
 481 $ scilab-adv-cli -e "help()"
 482 or
 483 $ scilab -nw -e "help()"
 484
 485
 486 # Scilab can be used for scripting aspects:
 487 echo "if 1&lt;>2 then exit(99) end"|scilab-cli
 488 echo $? ]]></screen>
 489     </refsection>
 490     <refsection role="see also">
 491         <title>See also</title>
 492         <simplelist type="inline">
 493             <member>
 494                 <link linkend="startup">startup</link>
 495             </member>
 496             <member>
 497                 <link linkend="sciargs">sciargs</link>
 498             </member>
 499             <member>
 500                 <link linkend="getpid">getpid</link>
 501             </member>
 502             <member>
 503                 <link linkend="getenv">getenv</link>
 504             </member>
 505             <member>
 506                 <link linkend="getversion">getversion</link>
 507             </member>
 508             <member>
 509                 <link linkend="consolebox">consolebox</link>
 510             </member>
 511             <member>
 512                 <link linkend="exit">exit</link>
 513             </member>
 514         </simplelist>
 515     </refsection>
 516     <refsection role="history">
 517         <title>History</title>
 518         <revhistory>
 519             <revision>
 520                 <revnumber>5.4.0</revnumber>
 521                 <revremark>-noatomsautoload added.</revremark>
 522             </revision>
 523             <revision>
 524                 <revnumber>5.4.1</revnumber>
 525                 <revremark>scinotes and xcos individual scripts introduced. See SEP #87.</revremark>
 526             </revision>
 527             <revision>
 528                 <revnumber>6.0.0</revnumber>
 529                 <revremark>
 530                     <literal>-quit</literal> option added. <literal>-mem</literal> option removed.
 531                 </revremark>
 532             </revision>
 533             <revision>
 534                 <revnumber>6.0.1</revnumber>
 535                 <revremark>
 536                   <para><literal>-scihome</literal> option added.</para>
 537                   <para>On Windows, a new <literal>scilab.bat</literal> file becomes the main
 538                     executable script managing all launching options. There are now 3 binaries
 539                     Wscilex.exe, Wscilex-cli.exe, and Scilex.exe corresponding to each Scilab
 540                     running mode (STD, NW, NWNI).
 541                   </para>
 542                 </revremark>
 543             </revision>
 544         </revhistory>
 545     </refsection>
 546     <!--add some kewywords -->
 547     <refnamediv xml:id="wscilex"></refnamediv>
 548     <refnamediv xml:id="wscilex-cli"></refnamediv>
 549     <refnamediv xml:id="scilex"></refnamediv>
 550     <refnamediv xml:id="scilab-cli"></refnamediv>
 551     <refnamediv xml:id="scilab-adv-cli"></refnamediv>
 552 </refentry>