<?xml version="1.0" encoding="UTF-8"?>
<!--
 * Scilab ( http://www.scilab.org/ ) - This file is part of Scilab
 * Copyright (C) INRIA
 * Copyright (C) 2012 - 2016 - Scilab Enterprises
 * Copyright (C) 2018 - 2019 - Samuel GOUGEON
 *
 * This file is hereby licensed under the terms of the GNU GPL v2.0,
 * pursuant to article 5.3.4 of the CeCILL v.2.1.
 * This file was originally licensed under the terms of the CeCILL v2.1,
 * and continues to be available under such terms.
 * For more information, see the COPYING file which you should have received
 * along with this program.
 *
 -->
<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">
    <refnamediv>
        <refname>scilab</refname>
            <refpurpose>runs Scilab in interactive or batch mode with command line options
        </refpurpose>
    </refnamediv>
    <refsynopsisdiv>
        <title>Syntax</title>
        <synopsis>
scilab &lt;Options&gt;
        </synopsis>
    </refsynopsisdiv>
    <refsection role="arguments">
        <title>Options</title>
        <para>
            The list of Scilab launching options -- including options for developers --
            can be displayed in the OS terminal through the <literal>--help</literal> option.
        </para>
        <programlisting><![CDATA[
            unix_w(SCI+"/bin/scilab --help 2>&1")
     ]]></programlisting>
        <screen><![CDATA[
--> unix_w(SCI+"/bin/scilab --help 2>&1")
Usage: Scilab <options>
      -args arg1 arg2..: Send directly some arg1 arg2 .. data to the session.
                         arg1 arg2 .. values can then be read through sciargs().
      -e Instruction   : Execute the scilab instruction given in Instruction argument.
                         -e and -f arguments are mutually exclusive.
      -f File          : Execute the scilab script given in File argument.
                         -e and -f arguments are mutually exclusive.
      -quit            : force scilab exit after execution of script from -e or -f argument.
                         Flag ignored if it is not used with -e or -f argument.
      -l lang          : Change the language of scilab (default : en_US).
      -nw              : Enable console mode.
      -nwni            : Enable terminal mode.
      -ns              : Do not execute etc/scilab.start.
      -nouserstartup   : Do not execute user startup files (SCIHOME/scilab.ini|.scilab).
      -noatomsautoload : Do not autoload eligible ATOMS modules.
      -nb              : Do not display the banner (no banner).
      -scihome <dir>   : Force SCIHOME to <dir>.
      -texmacs         : Option to use Scilab from documents through http://texmacs.org.
      -version         : Display the Scilab version (no session opened).
      -display Display : Set the display to the X server Display (XWindow systems only).
                         unix:0.0 is the default.
      --help           : Display this help.

Developer Trace arguments:
      --parse-trace    : Display bison state machine evolution.
      --AST-trace      : Display ASCII-art AST to be human readable.
      --pretty-print   : Display pretty-printed code, standard Scilab syntax.

Developer Timer arguments:
      --AST-timed      : Time each AST node.
      --timed          : Time global execution.

Developer Debug arguments:
      --no-exec        : Only do Lexing/parsing do not execute instructions.
      --context-dump   : Display context status.
      --exec-verbose   : Display command before running it.
      --timeout delay  : Kill the Scilab process after a delay.
]]></screen>
        <para>
            They are described below.
        </para>
        <variablelist>
            <varlistentry>
                <term>-args arg#1 arg#2 ..</term>
                <listitem>
                    <para>
                        This option allows to send some data to the Scilab session:
                        <itemizedlist>
                            <listitem>Consecutive data are separated by one or several spaces.
                            </listitem>
                            <listitem>An expression between double-quotes is a single data.
                            </listitem>
                            <listitem>To include a double-quote in a data, write <literal>\"</literal> instead of <literal>"</literal>.
                            </listitem>
                            <listitem>The single quote <literal>'</literal> is a regular character. It has no special meaning.
                            </listitem>
                        </itemizedlist>
                    </para>
                    <para>
                      Inside the opened session, these data can be retrieved as separated strings with <link linkend="sciargs">sciargs()</link>.
                     </para>
                     <para>
                      Example:
                        <screen><![CDATA[C:\Users\Me> C:\SCIdir\bin\scilab -nw -nb -noatomsautoload -args "Hello %USERNAME%" 1.2345 \"%cd%\"]]></screen>
                        <programlisting><![CDATA[
// Inside the opened session:
a = sciargs()
i = find(a=="-args")
a(i+1)
evstr(a(i+2))*2
"This session has been launched from " + a(i+3)
                     ]]></programlisting>
                        <screen><![CDATA[
--> // Inside the opened session:
--> a = sciargs()
 a  =
! c:\SCIdir\bin\WScilex-cli.exe !
! -nb                           !
! -noatomsautoload              !
! -args                         !
! Hello John                    !
! 1.2345                        !
! "C:\Users\Me"                 !

--> i = find(a=="-args")
 i  =
    5.

--> a(i+1)
 ans  =
 Hello John

--> evstr(a(i+2))*2
 ans  =
    2.469

--> "This session has been launched from " + a(i+3)
 ans  =
 This session has been launched from "C:\Users\Me"
]]></screen>
                    </para>
                    <para>
                      Note here that <literal>>scilab -nw</literal> has been translated into
                      <literal>Wscilex-cli.exe</literal> by the <literal>scilab</literal> batch file,
                      in such a way that the "-nw" option is not returned by <literal>sciargs()</literal>
                      (see further below).
                    </para>
                    <para>
                        <note>
                           Using <literal>-args</literal> as the <emphasis role="italic">last</emphasis>
                           command line option is safer.
                        </note>
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>-display Display</term>
                <listitem>
                    <para>
                        For use under Xwindow systems only to set a specific X server
                        display. Default display is unix:0.0.
                    </para>
                    <para>
                        <literal>-display</literal> can be abbreviated by <literal>-d</literal>.
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>-e Instructions</term>
                <listitem>
                    <para>
                        At the end of the whole session startup, this option
                        <itemizedlist>
                            <listitem>
                                <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,
                                </para>
                            </listitem>
                            <listitem>
                                <para>executes Scilab <literal>Instructions</literal> provided
                                in a string. Example:
                                    <screen><![CDATA[OS> scilab -nw -e  "disp(\"Hello\"); a=%pi+%i; disp(exp(a)); exit;" -nb]]></screen>
                                </para>
                            </listitem>
                        </itemizedlist>
                    </para>
                    <warning>
                        <literal>-e</literal> and <literal>-f</literal> options can't be used together.
                    </warning>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>-f file</term>
                <listitem>
                    <para>
                        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 --,
                        <itemizedlist>
                            <listitem>
                                <para>
                                    the current Scilab working directory is set to the shell
                                    directory from which Scilab has been launched. For instance,
                                    <screen><![CDATA[ D:\users\me\scilab\dev> C:\SCIdir\bin\scilab -f ..\test.sce]]></screen>
                                    will do a <literal>cd("D:\users\me\scilab\dev")</literal>.
                                </para>
                            </listitem>
                            <listitem>
                                <para>
                                    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.
                                </para>
                            </listitem>
                        </itemizedlist>
                    </para>
                    <para>
                        A file with .xcos extension will be opened by Xcos.
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>-quit</term>
                <listitem>
                    <para>
                        This option forces scilab to always exit after the instruction(s) passed
                        with the <literal>-e</literal> option, or the script referred to by the
                        <literal>-f</literal> option, have been executed, even in case of a runtime
                        error. This option should always be used in batch mode.
                        It is ignored if neither <literal>-e</literal> nor <literal>-f</literal>
                        options are present.
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>-l lang</term>
                <listitem>
                    <para>If this option is present, it sets the user language.
                        <emphasis>lang</emphasis> can be: <emphasis>ca_ES de_DE en_US es_ES
                            fr_FR ja_JP pt_BR ru_RU zh_CN zh_TW
                        </emphasis>.
                    </para>
                    <para>
                        For compatibility reasons, other possible <literal>lang</literal> values
                        are <literal>'fr'</literal> for french, <literal>'en'</literal> for
                        English, or <literal>'pt'</literal> for Brasilian Portuguese.
                        The default language is English.
                    </para>
                    <note>
                        On Windows, in "-nw" or "-nwni" modes, the selected font of the terminal
                        must be a TrueType one to support UTF-8 characters, like
                        <emphasis>Monospaced</emphasis> (best choice if available) or
                        <emphasis>Consolas</emphasis> or <emphasis>Lucida Console</emphasis>..
                    </note>
                    <para>
                        On some systems, locales must be compiled to render correctly
                        UTF-8 fonts.
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>-nb</term>
                <listitem>
                    <para>"no banner": Cancels the display of the Scilab's loading message.
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>-ns</term>
                <listitem>
                    <para>"No Startup files": Cancels the execution of the main startup file
                        <literal>SCI/etc/scilab.start</literal> and of the user startup files
                        <literal>SCIHOME/.scilab</literal>,
                        <literal>SCIHOME/scilab.ini</literal>.
                    </para>
                    <para>This option will disable many features in Scilab. Please use it only if
                        you know what you are doing.
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>-nouserstartup</term>
                <listitem>
                    <para>Cancels the execution of the user startup files
                        <literal>SCIHOME/.scilab</literal> and
                        <literal>SCIHOME/scilab.ini</literal>.
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>-noatomsautoload</term>
                <listitem>
                    <para>
                        Cancels the autoloading of installed ATOMS modules at startup.
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>-nw</term>
                <listitem>
                    <para>If this option is present, Scilab is started as command line
                        with advanced features still available (graphics, export, xcos, scinotes, help browser, ...).
                    </para>
                    <para>
                        pipes are enabled for all operating systems. See the examples for
                        further details.
                    </para>
                    <para>
                        The actual Scilab binary file executed when using the "-nw" option is
                        <itemizedlist>
                            <listitem>
                                on Windows: <literal>WScilex-cli.exe</literal>.
                            </listitem>
                            <listitem>
                                on Linux and MacOS: <literal>scilab-adv-cli</literal>
                                (Scilab Advanced Command Line Interpreter).
                            </listitem>
                        </itemizedlist>
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>-nwni / -nogui</term>
                <listitem>
                    <important>
                        This mode prevents loading the Java Virtual Machine.
                        It starts faster and uses less memory. But then...
                    </important>
                    <warning>
                        Scilab is started as command line interpreter without any advanced features
                        requiring the JVM: graphics, export, xcos, scinotes, help browser, other
                        java interfaces, the Java module,... are not available.
                    </warning>
                    <para>
                        Anyway, pipes are enabled for all operating systems.
                        See the examples for further details.
                    </para>
                    <para>
                        Dedicated executable files performing the <literal>-nwni</literal> mode are
                        provided:
                        <itemizedlist>
                            <listitem>
                                Windows: <literal>Scilex.exe</literal>.
                            </listitem>
                            <listitem>
                                Others: <literal>scilab-cli</literal> (Scilab Command Line Interpreter).
                            </listitem>
                        </itemizedlist>
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>-scihome dir</term>
                <listitem>
                    <para>
                        Forces SCIHOME to the <literal>dir</literal> directory. If the path
                        includes some white space, it must be specified between
                        double-quotes (no single quotes!).
                        if <literal>dir</literal> is a relative path, <literal>dir</literal>
                        is added to the parent standard SCIHOME folder.
                        <table>
                            <tr><td>On Windows: </td>
                                <td>%USERPROFILE%\AppData\Roaming\Scilab\<literal>dir</literal></td>
                            </tr>
                            <tr><td>On Linux/MacOS:</td>
                                <td>~/.Scilab/<literal>dir</literal></td>
                            </tr>
                        </table>
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>--texmacs</term>
                <listitem>
                    <para>
                        This option is used when Scilab is used as computational interface
                        within the <ulink url="http://texmacs.org">TeXmacs</ulink> scientific editor,
                        using the <ulink url="https://atoms.scilab.org/toolboxes/texmacs">TeXmacs</ulink>
                        ATOMS module.
                        This one can be priorly installed in Scilab with <code>atomsInstall('texmacs')</code>.
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>-version</term>
                <listitem>
                    <para>
                        Only displays the Scilab's version in the OS terminal,
                        without launching any Scilab session.
                    </para>
                </listitem>
            </varlistentry>
        </variablelist>
    </refsection>
    <refsection role="arguments">
        <title>Additional options for Unix/Linux and Mac OS X</title>
        <para>Advice: use theses options on a Scilab source tree.</para>
        <variablelist>
            <varlistentry>
                <term>-debug</term>
                <listitem>
                    <para>Start Scilab under the debugger gdb.</para>
                    <para>
                        The variable <literal>SCILAB_GDB_OPT</literal> may be set to add custom options to gdb.
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>-debug-rr</term>
                <listitem>
                    <para>Start Scilab under <ulink url="https://rr-project.org/">rr</ulink>.</para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>-debug-kdbg</term>
                <listitem>
                    <para>Start Scilab under kdbg.</para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>-profiling</term>
                <listitem>
                    <para>Start Scilab under valgrind.</para>
                    <para>The variable SCILAB_VALGRIND_OPT may be set to add custom options
                        to valgrind (and override the existing valgrind options).
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>-profiling-visu</term>
                <listitem>
                    <para>Start Scilab under callgrind.</para>
                    <para>The variable SCILAB_VALGRIND_OPT may be set to add custom options
                        to callgrind (and override the existing callgrind options).
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>-electric-fence</term>
                <listitem>
                    <para>Start Scilab with the Electric Fence.</para>
                </listitem>
            </varlistentry>
        </variablelist>
    </refsection>
    <refsection role="description">
        <title>Environment variables</title>
        <variablelist>
            <varlistentry>
                <term>SCIVERBOSE</term>
                <listitem>
                    <para>
                        If this variable is present, Scilab startup script will show a startup debug information.
                        Mainly used for bug report and debugging purposes.
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>JAVA_HOME</term>
                <listitem>
                    <para>
                        Specify which Java to use. For example,
                        <literal>JAVA_HOME=/usr/lib/jvm/java-7-openjdk/ scilab</literal> will start Scilab with Java 7.
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>SCI_DISABLE_TK</term>
                <listitem>
                    <para>Disable Tk (but not Tcl) features.</para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>SCI_JAVA_ENABLE_HEADLESS</term>
                <listitem>
                    <para>
                        Enable Java Headless VM (i.e. without GUI features).
                    </para>
                </listitem>
            </varlistentry>
        </variablelist>
    </refsection>
    <refsection role="description">
        <title>Java Virtual Machine options</title>
        <warning>
            The options described here-below are useless and are cancelled if the option <literal>-nwni</literal> is used.
        </warning>
        <para>Starting from Scilab 5.0, the graphical user interface (GUI) and the
            build documentation are based on Java features. In some cases, it can be
            important to edit the JVM options (Java Virtual Machine).
        </para>
        <para>
            These options are available in the <emphasis>SCI/etc/jvm_options.xml</emphasis> file.
            <emphasis>
                The three following options are easily accessible in this file:
            </emphasis>
        </para>
        <variablelist>
            <varlistentry>
                <term>-XmxXXXm</term>
                <listitem>
                    <para>This option set the amount of memory available by the Java
                        Virtual Machine. By default, 256M are allocated. If you change this
                        value, check that the value does not exceed the memory available on
                        the system.
                    </para>
                    <para>
                        This value can be changed in the preferences menu.
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>-Djava.compiler=JIT</term>
                <listitem>
                    <para>
                        This option with the argument <emphasis>JIT</emphasis> enables
                        the Java Just In Time compiler. It is activated by default.
                        <emphasis>NONE</emphasis> disables the JIT and decreases
                        dramatically performances.
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>-verbose:jni / -Xcheck:jni</term>
                <listitem>
                    <para>These options enable more checks and output from the JNI
                        calls. These options are useful in case of debugging and are
                        disabled by default since they decreases performances.
                    </para>
                </listitem>
            </varlistentry>
        </variablelist>
        <para>Many more options are available. They can improve the performances,
            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>.
        </para>
    </refsection>
    <refsection role="examples">
        <title>Examples</title>
        <screen><![CDATA[
# Let's start Scilab in profiling mode without attaching a gdb once a SIGSEGV is met.
# We are under Bash shell
export SCILAB_VALGRIND_OPT="--db-attach=no --log-file=myfile.txt"
scilab -profiling

# Let's start Scilab in debug mode without stopping after each SIGSEGV
# First, we write a small command file
echo "handle SIGSEGV nostop" > debug.txt
# Now set the custom option
# We are under Bash shell
export SCILAB_GDB_OPT="--command=debug.txt"
# Start Scilab in debug mode
scilab -debug ]]></screen>
        <para></para>
        <screen><![CDATA[
# Under GNU/Linux, Mac OS X or Unix:
$ echo "disp(%pi)" | scilab-cli
or
$ echo "disp(%pi)" | scilab -nwni

# Only open the Scilab help window:
$ scilab-adv-cli -e "help()"
or
$ scilab -nw -e "help()"


# Scilab can be used for scripting aspects:
echo "if 1&lt;>2 then exit(99) end"|scilab-cli
echo $? ]]></screen>
    </refsection>
    <refsection role="see also">
        <title>See also</title>
        <simplelist type="inline">
            <member>
                <link linkend="startup">startup</link>
            </member>
            <member>
                <link linkend="sciargs">sciargs</link>
            </member>
            <member>
                <link linkend="getpid">getpid</link>
            </member>
            <member>
                <link linkend="getenv">getenv</link>
            </member>
            <member>
                <link linkend="getversion">getversion</link>
            </member>
            <member>
                <link linkend="getscilabmode">getscilabmode</link>
            </member>
            <member>
                <link linkend="consolebox">consolebox</link>
            </member>
            <member>
                <link linkend="exit">exit</link>
            </member>
            <member>
                <link linkend="preferences">preferences</link>
            </member>
            <member>
                <ulink url="http://texmacs.org/">TeXmacs</ulink>
            </member>
        </simplelist>
    </refsection>
    <refsection role="history">
        <title>History</title>
        <revhistory>
            <revision>
                <revnumber>5.2.0</revnumber>
                <revremark>Piping is enabled. Option -l lang added</revremark>
            </revision>
            <revision>
                <revnumber>5.4.0</revnumber>
                <revremark>
                    -noatomsautoload added. The Java Heap memory can be set through the preferences.
                </revremark>
            </revision>
            <revision>
                <revnumber>5.4.1</revnumber>
                <revremark>scinotes and xcos individual scripts introduced. See SEP #87.</revremark>
            </revision>
            <revision>
                <revnumber>6.0.0</revnumber>
                <revremark>
                    <itemizedlist>
                        <listitem>
                            User options:
                            <itemizedlist>
                                <listitem>
                                    Added: <literal>--help</literal>, <literal>-quit</literal>
                                </listitem>
                                <listitem>
                                    Removed: <literal>-mem</literal>
                                </listitem>
                            </itemizedlist>
                        </listitem>
                        <listitem>
                            Developer options added:
                            <itemizedlist>
                                <listitem>
                                    <literal>--parse-trace</literal>, <literal>--AST-trace</literal>,
                                    <literal>--pretty-print</literal>
                                </listitem>
                                <listitem>
                                    <literal>--AST-timed</literal>, <literal>--timed</literal>
                                </listitem>
                                <listitem>
                                    <literal>--no-exec</literal>, <literal>--exec-verbose</literal>,
                                    <literal>--timeout delay</literal>, <literal>--context-dump</literal>.
                                </listitem>
                            </itemizedlist>
                        </listitem>
                    </itemizedlist>
                </revremark>
            </revision>
            <revision>
                <revnumber>6.0.1</revnumber>
                <revremark>
                  <para><literal>-scihome</literal> option added.</para>
                  <para>On Windows, a new <literal>scilab.bat</literal> file becomes the main
                    executable script managing all launching options. There are now 3 binaries
                    Wscilex.exe, Wscilex-cli.exe, and Scilex.exe corresponding to each Scilab
                    running mode (STD, NW, NWNI).
                  </para>
                </revremark>
            </revision>
        </revhistory>
    </refsection>
    <!--add some kewywords -->
    <refnamediv xml:id="wscilex"></refnamediv>
    <refnamediv xml:id="wscilex-cli"></refnamediv>
    <refnamediv xml:id="scilex"></refnamediv>
    <refnamediv xml:id="scilab-cli"></refnamediv>
    <refnamediv xml:id="scilab-adv-cli"></refnamediv>
</refentry>
