<?xml version="1.0" encoding="UTF-8"?>
<!--
 * Scilab ( http://www.scilab.org/ ) - This file is part of Scilab
 * Copyright (C) 2008 - INRIA - Allan CORNET
 *
 * Copyright (C) 2012 - 2016 - Scilab Enterprises
 *
 * 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:ns5="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="compile_and_run_call_scilab" xml:lang="en">
    <refnamediv>
        <refname>Compile and run with Call Scilab</refname>
        <refpurpose>How to compile a native application based on or using
            Scilab
        </refpurpose>
    </refnamediv>
    <refsection>
        <title>Compilation</title>
        <para>To compile a native code based on Call Scilab, it is necessary to
            define some arguments, variables and paths.
        </para>
        <itemizedlist>
            <listitem>
                <para>CFLAGS. Call Scilab needs to have access to the headers of
                    Scilab core and call Scilab module.
                </para>
                <itemizedlist>
                    <listitem>
                        <para>Linux/Unix/MacOSX:</para>
                        <itemizedlist>
                            <listitem>
                                <para>In the binary version of Scilab, CFLAGS must be set to
                                    /path/to/scilab/include/scilab/core/ and
                                    /path/to/scilab/include/scilab/call_scilab/
                                </para>
                            </listitem>
                            <listitem>
                                <para>In the source tree of Scilab, CFLAGS must be set to
                                    /path/to/scilab/modules/core/includes/ and
                                    /path/to/scilab/modules/call_scilab/includes/
                                </para>
                            </listitem>
                        </itemizedlist>
                    </listitem>
                    <listitem>
                        <para>Windows</para>
                    </listitem>
                </itemizedlist>
            </listitem>
            <listitem>
                <para>LD_LIBRARY_PATH - Paths to libscilab.so and libjavasci.so (or
                    .dll, .jnilib...)
                </para>
                <itemizedlist>
                    <listitem>
                        <para>Linux/Unix/MacOSX:</para>
                        <itemizedlist>
                            <listitem>
                                <para>In the binary version of Scilab, SCI will point to
                                    /path/to/scilab/lib/scilab/
                                </para>
                            </listitem>
                            <listitem>
                                <para>In the source tree of Scilab, SCI will point to the root
                                    of the source tree /path/to/scilab/modules/call_scilab/.libs/
                                    and /path/to/scilab/.libs/
                                </para>
                            </listitem>
                        </itemizedlist>
                    </listitem>
                </itemizedlist>
            </listitem>
            <listitem>
                <para>LDFLAGS - The name of the library to link against</para>
                <itemizedlist>
                    <listitem>
                        <para>Linux/Unix/MacOSX: It is only mandatory to link against
                            scilab. This should include the other libraries.
                        </para>
                    </listitem>
                </itemizedlist>
            </listitem>
        </itemizedlist>
        <para>The following example is a Makefile to build against Scilab binary</para>
        <programlisting role="example"><![CDATA[
# A sample Makefile building a C code using Call Scilab using Scilab binary
PATH_SCILAB = /path/to/scilab/
# Note that PATH_SCILAB can be /usr/ is using a packaged version of Scilab.
SCILAB_CFLAGS = -I$(PATH_SCILAB)/include/scilab/
SCILAB_LDFLAGS = -lscilab
PATH_TO_LIB_SCILAB = $(PATH_SCILAB)/lib/scilab/
PATH_TO_LIB_CALL_SCILAB = $(PATH_SCILAB)/lib/scilab/

all: simple_call_scilab.c
	export LD_LIBRARY_PATH=$(PATH_TO_LIB_SCILAB):$(PATH_TO_LIB_CALL_SCILAB)
	gcc -o myExample $(SCILAB_LDFLAGS) -L$(PATH_TO_LIB_SCILAB) -L$(PATH_TO_LIB_CALL_SCILAB) $(SCILAB_CFLAGS) simple_call_scilab.c
 ]]></programlisting>
        <para>The following example is a Makefile to build against Scilab source tree</para>
        <programlisting role="example"><![CDATA[
# A sample Makefile building a C code using Call Scilab using Scilab built in it source tree.
PATH_SCILAB = /path/to/scilab/sources/
SCILAB_CFLAGS = -I$(PATH_SCILAB)/modules/core/includes/ -I$(PATH_SCILAB)/modules/call_scilab/includes/
SCILAB_LDFLAGS = -lscilab
PATH_TO_LIB_SCILAB = $(PATH_SCILAB)/modules/.libs/
PATH_TO_LIB_CALL_SCILAB = $(PATH_SCILAB)/modules/call_scilab/.libs/

all: simple_call_scilab.c
	export LD_LIBRARY_PATH=$(PATH_TO_LIB_SCILAB):$(PATH_TO_LIB_CALL_SCILAB)
	gcc -o myExample $(SCILAB_LDFLAGS) -L$(PATH_TO_LIB_SCILAB) -L$(PATH_TO_LIB_CALL_SCILAB) $(SCILAB_CFLAGS) simple_call_scilab.c
 ]]></programlisting>
    </refsection>
    <refsection>
        <title>Running</title>
        <para>To run an application based on Call Scilab, there are a few other
            things to set up.
        </para>
        <para>Some global variables must me set:</para>
        <itemizedlist>
            <listitem>
                <para>SCI - Path to Scilab files</para>
                <itemizedlist>
                    <listitem>
                        <para>Linux/Unix/MacOSX:</para>
                        <itemizedlist>
                            <listitem>
                                <para>In the binary version of Scilab, SCI will point to
                                    /path/to/scilab/share/scilab/
                                </para>
                            </listitem>
                            <listitem>
                                <para>In the source tree of Scilab, SCI will point to the root
                                    of the source tree /path/to/scilab/source/tree/
                                </para>
                            </listitem>
                        </itemizedlist>
                    </listitem>
                    <listitem>
                        <para>Windows:</para>
                    </listitem>
                </itemizedlist>
            </listitem>
            <listitem>
                <para>LD_LIBRARY_PATH - Paths to libscilab.so and libjavasci.so (or
                    .dll, .jnilib...)
                </para>
                <itemizedlist>
                    <listitem>
                        <para>Linux/Unix/MacOSX:</para>
                        <itemizedlist>
                            <listitem>
                                <para>In the binary version of Scilab, SCI will point to
                                    /path/to/scilab/lib/scilab/
                                </para>
                            </listitem>
                            <listitem>
                                <para>In the source tree of Scilab, SCI will point to the root
                                    of the source tree /path/to/scilab/modules/javasci/.libs/ and
                                    /path/to/scilab/.libs/
                                </para>
                            </listitem>
                        </itemizedlist>
                    </listitem>
                </itemizedlist>
            </listitem>
            <listitem>
                <para>LD_LIBRARY_PATH (Java) - Paths to Java native libraries
                    (libjava.so, libjvm.so, libhpi.so)... It is usually provided by the
                    operating system or by Scilab distribution. Please note that won't be
                    necessary in Scilab 5.2
                </para>
                <itemizedlist>
                    <listitem>
                        <para>Linux/Unix:</para>
                        <itemizedlist>
                            <listitem>
                                <para>JAVA_HOME/jre/lib/&lt;arch&gt;/,
                                    JAVA_HOME/jre/lib/&lt;arch&gt;/server,
                                    JAVA_HOME/jre/lib/&lt;arch&gt;/native_threads/ (&lt;arch&gt;
                                    can be i386, etc...)
                                </para>
                            </listitem>
                        </itemizedlist>
                    </listitem>
                    <listitem>
                        <para>Mac OS X:</para>
                    </listitem>
                    <listitem>
                        <para>Windows</para>
                    </listitem>
                </itemizedlist>
            </listitem>
        </itemizedlist>
        <para>Note that two environment variables are taken in account for
            specific needs:
        </para>
        <itemizedlist>
            <listitem>
                <para>
                    <literal>SCI_DISABLE_TK=1</literal> Disables Tk (Tcl's
                    GUI)
                </para>
            </listitem>
            <listitem>
                <para>
                    <literal>SCI_JAVA_ENABLE_HEADLESS=1</literal> Launch Java in
                    headless mode (no AWT/Swing)
                </para>
            </listitem>
        </itemizedlist>
    </refsection>
    <refsection>
        <title>Examples</title>
        <programlisting role="example"><![CDATA[
# Serie of declarations to execute my binary.

# With a Scilab source tree:
$ SCI=<path to Scilab source tree>
$ export LD_LIBRARY_PATH=$SCI/modules/.libs/:$SCI/modules/call_scilab/.libs/:$SCI/modules/api_scilab/.libs

# With a Scilab binary:
$ SCI_PATH=<path to Scilab binary>
$ export LD_LIBRARY_PATH=$SCI_PATH/lib/scilab/

# Set the path to Java Virtual Machine library; This is mandatory for graphics features
# Don't forget to update arch (i386) and paths to whatever is necessary
$ export JAVA_HOME=/usr/lib/jvm/java-6-openjdk/
$ export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:$JAVA_HOME/jre/lib/i386/:$JAVA_HOME/jre/lib/i386/server/
$ export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:$JAVA_HOME/jre/lib/i386/native_threads/
$ export SCI=/path/to/scilab/
$ ./myExample
!sample  for the help  !

  - 42.    42.
 ]]></programlisting>
    </refsection>
    <refsection role="see also">
        <title>See also</title>
        <simplelist type="inline">
            <member>
                <link linkend="call_scilab">call_scilab</link>
            </member>
            <member>
                <link linkend="StartScilab">StartScilab</link>
            </member>
            <member>
                <link linkend="SendScilabJob">SendScilabJob</link>
            </member>
            <member>
                <link linkend="SendScilabJobs">SendScilabJobs</link>
            </member>
            <member>
                <link linkend="DoubleManagement_callscilab">Double Management</link>
            </member>
            <member>
                <link linkend="BooleanManagement_callscilab">Boolean Management</link>
            </member>
            <member>
                <link linkend="ComplexManagement_callscilab">Complex Management</link>
            </member>
            <member>
                <link linkend="StringManagement_callscilab">String Management</link>
            </member>
        </simplelist>
    </refsection>
</refentry>
