/[svn]/jsampler/trunk/manual/docbook/jsampler.xml
ViewVC logotype

Annotation of /jsampler/trunk/manual/docbook/jsampler.xml

Parent Directory Parent Directory | Revision Log Revision Log


Revision 1204 - (hide annotations) (download) (as text)
Thu May 24 21:43:45 2007 UTC (16 years, 10 months ago) by iliev
File MIME type: text/xml
File size: 13630 byte(s)
upgrading to version 0.5a

1 iliev 1144 <?xml version="1.0" encoding="UTF-8"?>
2     <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
3     "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
4     <book>
5     <title>JSampler Manual</title>
6    
7     <bookinfo>
8     <author>
9     <firstname>by Grigor</firstname>
10    
11     <surname>Iliev</surname>
12     </author>
13    
14     <copyright>
15     <year>2007</year>
16    
17     <holder>Grigor Iliev &lt;grigor@grigoriliev.com&gt;</holder>
18     </copyright>
19    
20     <legalnotice>
21     <para>This document is released under the terms of the <ulink
22     url="gfdl.html">GNU Free Documentation License</ulink>.</para>
23     </legalnotice>
24    
25 iliev 1204 <pubdate>Updated: Thu, 17 May 2007</pubdate>
26 iliev 1144 </bookinfo>
27    
28     <chapter>
29     <title>Introduction</title>
30    
31     <section>
32     <title>What is JSampler?</title>
33    
34     <para>JSampler is an opensource, platform-independent, GUI front-end for
35     <ulink url="http://www.linuxsampler.org">LinuxSampler</ulink>, written
36     entirely in <ulink url="http://java.sun.com">Java</ulink>. The main goal
37     of the JSampler's design is to be extensible and more flexible regarding
38     the integration of different GUI implementations. JSampler consists of
39     two parts:</para>
40    
41     <para><itemizedlist>
42     <listitem>
43     <para>JSampler core - handles the LSCP command processing and
44     event notifications, sent by LinuxSampler, and provides convenient
45     data models and controllers to be used instead. The core also
46     provides the necessary interfaces that should be implemented by
47     all JSamler views.</para>
48     </listitem>
49    
50     <listitem>
51     <para>JSampler view - an extension to the JSampler core, which
52     provides the user interface part of JSampler.</para>
53     </listitem>
54     </itemizedlist>The main reason for that is the TCP/IP based
55     communication between the LinuxSampler and its front-ends, enabling the
56     sampler to be controlled from another computer or device, which may have
57     different display requirements and limitations.</para>
58     </section>
59    
60     <section>
61     <title>What is a JSampler distribution?</title>
62    
63     <para>A JSampler distribution consist of the JSampler core and at least
64     one view, providing the GUI implementation. Each distribution has its
65     own name, which is based on the integrated view extension. Currently,
66     there are two distributions:</para>
67    
68     <para><itemizedlist>
69     <listitem>
70     <para>JS Classic - A distribution with a standard GUI, capable of
71     controlling all features available in LinuxSampler at the time of
72     this writing. JS Classic also provides some additional features to
73     facilitate the every day work with the sampler and to automate the
74     most frequently used configurations.</para>
75     </listitem>
76    
77     <listitem>
78     <para>Fantasia - A distribution with a skin based view, which is
79     in early development stage and is only partially implemented
80     (graphic design by Olivier Boyer).</para>
81     </listitem>
82     </itemizedlist></para>
83     </section>
84     </chapter>
85    
86     <chapter>
87     <title>Screenshots</title>
88    
89     <para>JS Classic with left pane, LS console, statusbar and
90     toolbars<graphic fileref="images/js-classic1.png" /></para>
91    
92     <para>JS Classic without left pane, LS console, statusbar and
93     toolbars<graphic fileref="images/js-classic2.png" /></para>
94    
95     <para>Fantasia<graphic fileref="images/fantasia.png" /></para>
96     </chapter>
97    
98     <chapter>
99     <title>Installation</title>
100    
101     <para></para>
102    
103     <section>
104     <title id="download">What to download?</title>
105    
106     <para>Currently, there are two distributions available for download - JS
107     Classic and Fantasia. However, for now the preferred choice is JS
108     Classic, because Fantasia is only partially implemented. The latest
109     version of JS Classic is available for download from <ulink
110 iliev 1204 url="http://downloads.sourceforge.net/jsampler/JS_Classic-0.5a.jar">here</ulink>.</para>
111 iliev 1144
112     <para>The source code is available in the <ulink
113 iliev 1204 url="http://downloads.sourceforge.net/jsampler/JSampler-0.5a.tar.bz2">JSampler
114 iliev 1144 package</ulink>, which also contains this manual and startup scripts
115     that can be used to run a particular JSampler distribution.</para>
116    
117     <para>The latest source code can be obtained from cvs with the following
118     command:</para>
119    
120     <para><command>cvs -z3
121     -d:pserver:anonymous@cvs.linuxsampler.org:/var/cvs/linuxsampler co
122     jsampler</command></para>
123     </section>
124    
125     <section>
126     <title id="requirements">Requirements</title>
127    
128 iliev 1204 <para>To run JSampler you need Java Runtime Environment (JRE) version 6
129 iliev 1144 or higher. The latest version can be downloaded from <ulink
130     url="http://java.sun.com/javase/downloads/">here</ulink>.</para>
131    
132     <para>To build JSampler distribution from source you need JDK version
133 iliev 1204 6.0 or higher and the <ulink url="http://ant.apache.org/">Ant
134 iliev 1144 tool</ulink>.</para>
135     </section>
136    
137     <section>
138     <title id="running-js-dist">Running a JSampler distribution</title>
139    
140     <para>Let's assume that you want to run from the command line
141 iliev 1204 <code>JS_Classic-0.5a.jar</code>, which is located in
142 iliev 1144 <code>/home/me/soft</code> directory. First you should check whether the
143     <code>java</code> command is in your path and the version requirements
144     are met. This can be done by issuing the following command:</para>
145    
146     <para><command>java -version</command></para>
147    
148 iliev 1204 <para>If the version is 1.6.0 or higher you can run JS Classic by
149 iliev 1144 issuing the following command:</para>
150    
151     <para><command>java -jar
152 iliev 1204 /home/me/soft/JS_Classic-0.5a.jar</command></para>
153 iliev 1144
154     <para>Otherwise, if the shell response is something like</para>
155    
156     <para><command>bash: java: command not found</command></para>
157    
158     <para>or the version requirements are not met, make sure that you have
159     installed JRE (or JDK) with the proper version and find its
160     location:</para>
161    
162     <para><literallayout><command>updatedb
163     locate bin/java</command></literallayout></para>
164    
165     <para>The shell should return something like:</para>
166    
167     <para><literallayout><command>/opt/jdk1.6.0/bin/java
168     /opt/jdk1.6.0/bin/javac
169     /opt/jdk1.6.0/bin/javadoc
170     /opt/jdk1.6.0/bin/javah
171     /opt/jdk1.6.0/bin/javap
172     /opt/jdk1.6.0/jre/bin/java
173     /usr/bin/java</command></literallayout></para>
174    
175     <para>Now, we know that we have a JDK with a proper version installed
176     and its location is <code>/opt/jdk1.6.0</code>. In that case, to run JS
177     Classic issue the following command:</para>
178    
179     <para><command>/opt/jdk1.6.0/bin/java -jar
180 iliev 1204 /home/me/soft/JS_Classic-0.5a.jar</command></para>
181 iliev 1144
182     <para><note>
183     <para>On some systems double clicking on the jar file will be
184     enough.</para>
185     </note></para>
186     </section>
187    
188     <section>
189     <title>Using a script to run a JSampler distribution</title>
190    
191     <para>There are scripts In the <code>scripts</code> directory of the
192     <ulink
193 iliev 1204 url="http://downloads.sourceforge.net/jsampler/JSampler-0.5a.tar.bz2">JSampler
194 iliev 1144 package</ulink> that, with a little adjustments (if needed), can be used
195     to run a JSampler distribution. Copy them to a desired location and edit
196     with your preferred editor.</para>
197     </section>
198    
199     <section>
200     <title>Telling Gnome how to handle jar files</title>
201    
202     <para>This configuration is optional, but necessary if you want to run
203     jar files by (double) clicking on them. In Gnome, by default jar files
204     are opened with the Archive Manager. To change that, run a file browser,
205     right click on an arbitrary jar file and choose
206     <guimenu>Properties</guimenu>, than go to the <guilabel>Open
207     With</guilabel> tab and click the <guibutton>Add</guibutton>
208     button.</para>
209    
210     <para><graphic fileref="images/file-properties.png" /></para>
211    
212     <para>In the <guilabel>Add Application</guilabel> dialog click onto
213     <guilabel>Use a custom command</guilabel> label and a text field will
214     appear below. If the location of your JRE is <code>/opt/jre1.6.0</code>,
215     then enter the following command in the text box:</para>
216    
217     <para><command>/opt/jre1.6.0/bin/java -jar</command></para>
218    
219     <para>And then click the <guibutton>Add</guibutton> button.</para>
220    
221     <para><graphic fileref="images/add-application.png" /></para>
222     </section>
223    
224     <section>
225     <title>Adding an application launcher to a Gnome panel</title>
226    
227     <para>To add an application launcher to a Gnome panel, right click on
228     the panel and choose <guimenu>Add to Panel</guimenu>.</para>
229    
230     <para><graphic fileref="images/add-to-panel.png" /></para>
231    
232     <para>Then select <guilabel>Custom Application Launcher</guilabel> and
233     click the <guibutton>Add</guibutton> button. In the
234     <guilabel>Command</guilabel> field, of the <guilabel>Create
235     Launcher</guilabel> dialog, fill in the exact command that you use to
236     run the JSampler. For more information on how to run a JSampler
237     distribution from the command line <link linkend="running-js-dist">click
238     here</link>.</para>
239    
240     <para><graphic
241     fileref="images/add-to-panel-create-launcher.png" /></para>
242     </section>
243    
244     <section>
245     <title>Running JSampler on Windows</title>
246    
247     <para>To run JSampler distribution on Windows, put a shortcut on the
248     Desktop or Quick Launch, right click on the shortcut and choose
249     <guimenu>Properties</guimenu>. In the <guilabel>Target</guilabel> field
250     insert the command <code>javaw -jar</code> in the beginning.</para>
251    
252     <para><graphic fileref="images/win-shortcut.png" /></para>
253     </section>
254     </chapter>
255    
256     <chapter>
257     <title>Building from source</title>
258    
259     <para>If you want to build a JSampler distribution from source, first make
260     sure that all <link linkend="requirements">requirements</link> are
261     met.</para>
262    
263     <section>
264     <title>Building from CVS</title>
265    
266     <para>When building from CVS, there are some additional steps that
267     should be done. JSampler uses two additional libraries, that should be
268     downloaded and placed in the <code>lib/required</code> directory:</para>
269    
270     <para><itemizedlist>
271     <listitem>
272     <para><ulink
273     url="http://sourceforge.net/projects/jlscp/">jlscp</ulink> - A
274     java LinuxSampler control protocol API</para>
275     </listitem>
276    
277     <listitem>
278     <para><ulink
279     url="http://sourceforge.net/projects/juife/">juife</ulink> - Java
280     User Interface Framework Extensions</para>
281     </listitem>
282     </itemizedlist>Download these libraries, create a
283     <code>lib/required</code> directory in the JSampler root and copy the
284     <code>jlscp.jar</code> and <code>juife.jar</code> files in that
285     directory:</para>
286    
287     <para><literallayout><command>cd /home/me/soft
288 iliev 1204 wget -c http://downloads.sourceforge.net/jlscp/jlscp-0.5a.tar.bz2
289     tar -xjf jlscp-0.5a.tar.bz2
290 iliev 1144 wget -c http://downloads.sourceforge.net/juife/juife-0.4a.tar.bz2
291     tar -xjf juife-0.4a.tar.bz2
292     cvs -z3 -d:pserver:anonymous@cvs.linuxsampler.org:/var/cvs/linuxsampler co jsampler
293     cd jsampler
294     mkdirhier lib/required
295 iliev 1204 cp ../jlscp-0.5a/lib/jlscp.jar lib/required/jlscp.jar
296 iliev 1144 cp ../juife-0.4a/lib/juife.jar lib/required/juife.jar</command></literallayout></para>
297    
298     <para>Then follow the steps in the next section.</para>
299     </section>
300    
301     <section>
302     <title>Compilation</title>
303    
304     <para>To build a JSampler distribution, first set the
305     <code>JAVA_HOME</code> environment variable to point to your JDK
306     directory. If the JDK is installed in /opt/jdk1.6.0 directory, this can
307     be done by issuing the following command:</para>
308    
309     <para><command>export JAVA_HOME=/opt/jdk1.6.0</command></para>
310    
311     <para>Windows users should do something like:</para>
312    
313     <para><command>set JAVA_HOME=c:\jdk1.6.0</command></para>
314    
315     <para>Go to the JSampler root directory and issue the following
316     command:</para>
317    
318     <para><command>ant [target]</command></para>
319    
320     <para>Where <code>target</code> can be one of the following:</para>
321    
322     <para><itemizedlist>
323     <listitem>
324     <para><command>build-jsclassic</command> - Builds a JS Classic
325     distribution.</para>
326     </listitem>
327    
328     <listitem>
329     <para><command>clean-jsclassic</command> - Removes the JS Classic
330     distribution.</para>
331     </listitem>
332    
333     <listitem>
334     <para><command>build-fantasia</command> - Builds a Fantasia
335     distribution.</para>
336     </listitem>
337    
338     <listitem>
339     <para><command>clean-fantasia</command> - Removes the Fantasia
340     distribution.</para>
341     </listitem>
342    
343     <listitem>
344     <para><command>build-coredoc</command> - Generates the API
345     documentation for the JSampler core.</para>
346     </listitem>
347    
348     <listitem>
349     <para><command>clean-coredoc</command> - Removes the API
350     documentation for the JSampler core.</para>
351     </listitem>
352     </itemizedlist></para>
353    
354     <para>So, if you want to build a JS Classic distribution, just issue the
355     following command:</para>
356    
357     <para><command>ant build-jsclassic</command></para>
358    
359     <para>Then copy the jar file from the <code>dist</code> directory to the
360     desired location.</para>
361     </section>
362     </chapter>
363     </book>

  ViewVC Help
Powered by ViewVC