* Bug #12564 fixed - Javasci compile & run help page is not clear about needed packages
[scilab.git] / scilab / modules / javasci / help / en_US / compile_and_run_javasci.xml
1 <?xml version="1.0" encoding="UTF-8"?>
2 <!--
3  * Scilab ( http://www.scilab.org/ ) - This file is part of Scilab
4  * Copyright (C) 2008 - INRIA - Allan CORNET
5  *
6  * This file must be used under the terms of the CeCILL.
7  * This source file is licensed as described in the file COPYING, which
8  * you should have received as part of this distribution.  The terms
9  * are also available at
10  * http://www.cecill.info/licences/Licence_CeCILL_V2-en.txt
11  *
12  -->
13 <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_javasci_v2" xml:lang="en">
14     <refnamediv>
15         <refname>Compile and run with javasci v2</refname>
16         <refpurpose>How to compile a Java application using Javasci v2</refpurpose>
17     </refnamediv>
18     <refsection>
19         <title>Linux/Unix/MacOSX</title>
20         <para>On Linux/Unix/MacOSX, Scilab needs the SCI global variable to be set:</para>
21         <itemizedlist>
22             <listitem>
23                 <para>
24                     In the binary version of Scilab, SCI will point to <literal>/path/to/scilab/share/scilab/</literal>
25                 </para>
26             </listitem>
27             <listitem>
28                 <para>
29                     In the source tree of Scilab, SCI will point to the root of the source tree <literal>/path/to/scilab/source/tree/</literal>
30                 </para>
31             </listitem>
32         </itemizedlist>
33         
34         <para>To compile a Java application using Javasci v2, the path to the following libraries may have to be added in the classpath:</para>
35         <itemizedlist>
36             <listitem>
37                 <literal>org.scilab.modules.javasci.jar</literal> (required for all Javasci applications) 
38             </listitem>
39             <listitem>
40                 <literal>org.scilab.modules.types.jar</literal> (if the application uses Javasci types) 
41             </listitem>
42         </itemizedlist>
43         
44         <para>To compile the example code (the code is further in this page), the command line is:</para>
45         
46         <para>
47             <literal>javac -cp $SCI/modules/javasci/jar/org.scilab.modules.javasci.jar:$SCI/modules/types/jar/org.scilab.modules.types.jar:. BasicExample.java</literal>
48         </para>
49         
50         <para>To launch the Java application, the path to the libjavasci native library needs to be provided, either:</para>
51         <itemizedlist>
52             <listitem>
53                 <para>In the LD_LIBRARY_PATH:</para>
54                 <itemizedlist mark="opencircle">
55                     <listitem>
56                         <para>
57                             In the binary version of Scilab, LD_LIBRARY_PATH will point to <literal>/path/to/scilab/lib/scilab/</literal> and <literal>/path/to/scilab/lib/thirdparty/</literal>
58                         </para>
59                     </listitem>
60                     <listitem>
61                         <para>
62                             In the source tree of Scilab, LD_LIBRARY_PATH will point to the root of the source tree <literal>/path/to/scilab/modules/javasci/.libs/</literal>, <literal>/path/to/scilab/modules/types/.libs/</literal> and <literal>/path/to/scilab/.libs/</literal>
63                         </para>
64                     </listitem>
65                 </itemizedlist>
66                 
67                 <para>And the application is run with the command line:</para>
68                 <literal>java -cp $SCI/modules/javasci/jar/org.scilab.modules.javasci.jar:$SCI/modules/types/jar/org.scilab.modules.types.jar:. BasicExample</literal>
69             </listitem>
70             <listitem>
71                 <para>Or as argurment of java, in the command line:</para>
72                 <para>
73                     <literal>java -Djava.library.path=/path/to/libjavasci/:/path/to/scilab/lib/thirdparty/ -cp $SCI/modules/javasci/jar/org.scilab.modules.javasci.jar:$SCI/modules/types/jar/org.scilab.modules.types.jar:. BasicExample</literal>
74                 </para>
75             </listitem>
76         </itemizedlist>
77     </refsection>
78     <refsection>
79         <title>Windows</title>
80         <para>
81             In this paragraph we suppose Scilab is installed in the directory <literal>C:\Program Files\scilab-XXXX</literal> (where XXXX is the version of Scilab, for example "5.4.0").
82         </para>
83         
84         <para>On windows, no specific environment variable needs to be defined.</para>
85         
86         <para>To compile a Java application using Javasci v2, the path to the following libraries may have to be added in the classpath:</para>
87         <itemizedlist>
88             <listitem>
89                 <literal>org.scilab.modules.javasci.jar</literal> (required for all Javasci applications) 
90             </listitem>
91             <listitem>
92                 <literal>org.scilab.modules.types.jar</literal> (if the application uses Javasci types) 
93             </listitem>
94         </itemizedlist>
95         
96         <para>To compile the example code, the command line is:</para>
97         <para>
98             <literal>javac -cp "C:\Program Files\scilab-XXXX\modules\javasci\jar\org.scilab.modules.javasci.jar;C:\Program Files\scilab-XXXX\modules\types\jar\org.scilab.modules.types.jar";. BasicExample.java</literal>
99         </para>
100         
101         <para>For execution, the path to the native library libjavasci.dll and to its dependencies must be added in the PATH environment variable.
102             All the needed libraries are in the "bin" folder, so the command line is:
103         </para>
104         <para>
105             <literal>set PATH="C:\Program Files\scilab-XXXX\bin";%PATH%</literal>
106         </para>
107         
108         <para>To launch the Java application, the command line is quite the same as for Linux:</para>
109         <para>
110             <literal>java -cp "C:\Program Files\scilab-XXXX\modules\javasci\jar\org.scilab.modules.javasci.jar;C:\Program Files\scilab-XXXX\modules\types\jar\org.scilab.modules.types.jar";. BasicExample</literal>
111         </para>
112     </refsection>
113     <refsection>
114         <title>Options</title>
115         <para>
116             Optional options to launch java : <literal>-Djava.compiler=JIT -Xmx256m</literal>
117         </para>
118         <para>(With these arguments, javasci is started with same initial options like the standard scilab).
119         </para>
120         <para>Note that two environnement variables are taken in account for specific needs:
121         </para>
122         <itemizedlist>
123             <listitem>
124                 <para>
125                     <literal>SCI_DISABLE_TK=1</literal> disables Tk (Tcl's GUI)
126                 </para>
127             </listitem>
128             <listitem>
129                 <para>
130                     <literal>SCI_JAVA_ENABLE_HEADLESS=1</literal> launches Java in headless mode (no AWT/Swing)
131                 </para>
132             </listitem>
133         </itemizedlist>
134     </refsection>
135     <refsection>
136         <title>Examples</title>
137         <programlisting role="java"><![CDATA[
138 // A simple Java example
139 // javasci v2
140 // Filename: BasicExample.java
141
142 import org.scilab.modules.javasci.Scilab;
143 import org.scilab.modules.types.ScilabType;
144
145 class BasicExample {
146
147     public static void main(String[] args) {
148         try {
149             Scilab sci = new Scilab();
150             sci.open();
151             sci.exec("a=cos(%pi)*sin(%pi^2);");
152             ScilabType a = sci.get("a");
153             System.out.println("a = " + a);
154         } catch (org.scilab.modules.javasci.JavasciException e) {
155             System.err.println("Could not find variable type: " + e.getLocalizedMessage());
156         }
157    }
158 }
159
160  ]]></programlisting>
161     </refsection>
162     <refsection role="see also">
163         <title>See Also</title>
164         <simplelist type="inline">
165             <member>
166                 Browse <link type="remote" linkend="javasci/javadoc/index.html">the documentation of Javasci v2.</link>
167             </member>
168             <member>
169                 <link linkend="javasci">Javasci</link>
170             </member>
171             <member>
172                 <link linkend="javasci_faq_v2">Javasci FAQ</link>
173             </member>
174         </simplelist>
175     </refsection>
176 </refentry>