<p>
<strong>Running Jalview from the command line</strong>
</p>
- <p>Jalview is most easily run from the command line if you have
- built it from source, or via the 'Jalview' executable created from
- the InstallAnywhere Jalview installation. Both of these mechanisms
- allow true command line execution of Jalview - allowing you to
- provide additional options.</p>
- <p>The Java Webstart version of Jalview can be executed from the
- command line using something like :
- <pre>javaws http://www.jalview.org/webstart/jalview.jnlp -open
- <em>yourFileName</em>
- </pre>
- But, this is not guaranteed to work on all versions of webstart on all
- operating systems, and doesn't let you execute Jalview with any
- additional parameters.
<p>
- <strong>Running Jalview from the InstallAnywhere
- installation</strong>
+ Jalview can be run from the command line, and provides a <a
+ href="clarguments.html">range of arguments</a>. These arguments
+ can also be passed via <strong>.JVL</strong> files, which are opened
+ automatically by the Jalview application when double-clicked in a
+ file browser on Windows and OSX.
</p>
+ The way that you launch Jalview from the command line depends on the
+ platform you are on, and how it has been installed.
+
+ <ul>
+ <li>Standard installation on Linux/Unix:<pre>
+ /PATH_TO_JALVIEW/Jalview -open http://www.jalview.org/examples/jpred_msa.fasta -annotations http://www.jalview.org/examples/jpred_msa.seq.concise -colour Clustal</pre>
+ </li>
+ <li>Standard installation on Windows:<pre>
+ \PATH_TO_JALVIEW\Jalview.exe -open %HOMEPATH%\myalignment.fa</pre>
+ </li>
+ <li>OSX Application:<pre>
+open /Applications/Jalview.app --args -open ~/myalignment.fa</pre><em>(put
+ all the Jalview arguments <em>after</em> the --args parameter)
+ </em><br />
+ <br /></li>
+ <li>Jalview standalone executable Jar<pre>
+ <Path to Java home>/bin/java -jar %lt;Path to Jalview Jar>/jalview-all-1.8.jar -open myalignment.fa</pre></li>
+ </ul>
<p>
- If you install with InstallAnywhere you can use several more
- commands. However, if you call the application with the link
- provided by InstallAnywhere any output from the application will be
- sent to output.txt, not standard out.<br> The Jalview
- application also requires a number of additional libraries on the
- class path. The command line below adds all the jar files in the
- Jalview installation's 'lib' directory to the classpath, as well as
- the Jalview application jar file:
+ If you have installed Jalview via <em>conda</em> or another package
+ manager then you most likely have a 'jalview' command available in
+ your terminal shell's default path. Alternately, if you have built
+ Jalview from source, then take a look at the doc/building.md file
+ included in the source distribution.
</p>
- <pre>java -classpath "$INSTALL_DIR$/lib/*:$INSTALL_DIR$/jalview.jar" jalview.bin.Jalview -open [FILE] </pre>
<p>
Use '-help' to get more information on the <a
- href="clarguments.html">command line arguments</a> that
- Jalview accepts.
+ href="clarguments.html">command line arguments</a> that Jalview
+ accepts.
+ </p>
+ <p>
+ <strong>Passing JVM Arguments to Jalview</strong><br /> If you need
+ to modify parameters for Jalview's Java Virtual Machine, then take a
+ look at the instructions for how to <a href="../memory.html#jvm">setting
+ the JVM's maximum memory</a>.
</p>
<p> </p>
<p> </p>
<strong>Memory Usage Settings for Jalview</strong>
</center>
</h2>
+ <p>When launched as an Application, Jalview will automatically
+ configure the amount of memory allocated to the program to be 90% of
+ physical memory. You may wish to change this behaviour -
+ particularly if you are working on a machine that runs other memory
+ intensive processes.
<p>
- When launched as an Application, Jalview automatically tries to
- maximise the amount of memory allocated to it (default settings are
- to try and use up to 90% of physical memory available to it).
- Sometimes it may require more memory, or if you are working in a
- shared memory environment you may want to limit the maximum amount
- of memory that it might use.
- This has to be set at the time Jalview is launched because of the way
- that Java runs on a computer - what is actually run is a program called
- a Java virtual machine (a JVM) which executes the java program instructions.
- The JVM has limits on the memory that can be allocated to the java program - and
- you might need to increase them if you are working with particularly
- large datasets.<br> If Jalview has not explicitly told you that
- it has run out of memory, then a common sign is that a function that
- normally works seems to have no effect when working with a larger
- set of sequences (this might include open dialog boxes for saving
- PNG files, or when interpreting the result of a web service
- calculation).
+ <em>Signs that Jalview is Running out of Memory</em><br /> If
+ Jalview has not explicitly told you that it has run out of memory,
+ then a common sign is that a function that normally works seems to
+ have no effect when working with a larger set of sequences (this
+ might include open dialog boxes for saving PNG files, or when
+ interpreting the result of a web service calculation).
</p>
<p>
<em>Jalview Memory Usage Monitor</em>: If you are concerned about
window's background.
</p>
<p>
- <em>Increasing the memory available to Jalview</em><br/>
- Since Jalview 2.11, the program automatically configures the JVM memory settings to set the maximum memory available to Jalview to be 90% of physical memory.
- This default setting can be altered in a number of different ways, depending on how you prefer to launch Jalview and how specific you want to be with the maximum memory setting.
+ <em>Increasing the memory available to Jalview</em><br /> The
+ amount of memory allocated is defined wheb Jalview is launched
+ because of the way that Java runs on a computer - what is actually
+ run is a program called a Java virtual machine (a JVM) which
+ executes the java program instructions. The JVM has limits on the
+ memory that can be allocated to the java program - and it is often
+ necessary to adjust them if you are working with particularly large
+ datasets, or need to make room for other processes on the machine.<br />
+ <br />Jalview 2.11 includes a launcher that automatically
+ configures the proportion of memory allocated to Jalview's JVM, and
+ its behaviour can be altered in a number of different ways:
</p>
<ul>
- <li><em><font size="3">JVL file</font></em>
- <p>
- The easiest way to launch Jalview with a different percentage of physical memory available is to
- create a text file with extension <em>.jvl</em> and with content that contains the line
- <pre>
- jalview.jvmmempc=50
- </pre>
- Replace the value with the percentage of memory you wish to allocate to Jalview.
- </p>
- <p>
- In Windows and in macOS you can then launch Jalview by double clicking on this file, and your memory setting will be used instead of the default value of 90.
- </p>
- <p>
- In Linux or other unix variants you can launch Jalview on the command line and provide your JVL file as an argument with
- <pre>
- /PATH_TO_JALVIEW/Jalview /path/to/file/mymemorysetting.jvl
- </pre>
-
- </p>
- <p>
- If you want to use a memory setting like this and open a file you can use both the jvl and alignment files as command line arguments, but you must put the <em>jvl</em> file first, e.g.
- <pre>
- /PATH_TO_JALVIEW/Jalview /path/to/file/mymemorysetting.jvl /path/to/alignments/myalignment.fa
- </pre>
- alternatively, you can use the standard Jalview command line arguments with or without the jvl file (first), e.g.
- <pre>
- /PATH_TO_JALVIEW/Jalview /path/to/file/mymemorysetting.jvl -open http://www.jalview.org/examples/jpred_msa.fasta -annotations http://www.jalview.org/examples/jpred_msa.seq.concise -colour Clustal
- </pre>
- </p>
-
- <p>
- You can use command line arguments to control memory settings in Windows and macOS too:
- <br/>
- In Windows you must use, e.g.
- <pre>
- \PATH_TO_JALVIEW\Jalview.exe %HOMEPATH%\mymemorysetting.jvl -open %HOMEPATH%\myalignment.fa
- </pre>
- and in macOS you can use the macOS <em>open</em> command like this:
- <pre>
- open /Applications/Jalview.app --args ~/mymemorysetting.jvl -open ~/myalignment.fa
- </pre>
- (put all the Jalview arguments <em>after</em> the --args parameter).
-
- </p>
- </li>
-
-
- <li><em><font size="3">Directly opening Jalview with a JVM</font></em>
- <p>
- Launching Jalview directly with a JVM is entirely possible, but is not recommended as automatic updates and some other default settings will not operate.
- </p>
- <p>
- However by launching Jalview in this way you have full access to the Java command line arguments.
- In particular you can set the maximum allowed memory with the <em>-Xmx...</em> JVM argument.
- <br/>
- <em>-Xmx</em> should be immediately followed (no space or equals) by the maximum amount of memory that you might want to launch Jalview with. This can be specified in bytes as just a number,
- or in kilobytes, megabytes or gigabytes by following the number with a "k", "m" or "g" respectively. e.g.
- <pre>
- -Xmx8g
- </pre>
- </p>
- <p>
- Jalview binaries for Windows and macOS are distributed with their own JVM which you will find in
+ <li><em><font size="3">JVL file</font></em> <br /> The easiest
+ way to launch Jalview with a different percentage of physical
+ memory available is to create a text file with extension <em>.jvl</em>
+ and a single line to specify the percentage of memory you wish
+ Jalview to request: <pre>
+ jalview.jvmmempc=50</pre> In Windows and in macOS you can then launch Jalview by
+ double clicking on this file, and your memory setting will be used
+ instead of the default value. <br /> <br /> In Linux or other
+ unix variants you can launch Jalview on the command line and
+ provide your JVL file as an argument with <pre>
+ /PATH_TO_JALVIEW/Jalview /path/to/file/mymemorysetting.jvl</pre> If you want to use a memory setting like this and open a
+ file you can use both the jvl and alignment files as command line
+ arguments, but you must put the <em>jvl</em> file first, e.g. <pre>
+ /PATH_TO_JALVIEW/Jalview /path/to/file/mymemorysetting.jvl /path/to/alignments/myalignment.fa</pre> Alternatively, you can use the standard Jalview command line
+ arguments with or without the jvl file (first), e.g. <pre>
+ /PATH_TO_JALVIEW/Jalview /path/to/file/mymemorysetting.jvl -open http://www.jalview.org/examples/jpred_msa.fasta -annotations http://www.jalview.org/examples/jpred_msa.seq.concise -colour Clustal</pre> You can use command line arguments to control memory
+ settings in Windows and macOS too: <br /> In Windows you must
+ use, e.g. <pre>
+ \PATH_TO_JALVIEW\Jalview.exe %HOMEPATH%\mymemorysetting.jvl -open %HOMEPATH%\myalignment.fa</pre> In macOS you can use the macOS <em>open</em> command like this: <pre>
+ open /Applications/Jalview.app --args ~/mymemorysetting.jvl -open ~/myalignment.fa</pre><em>(put all the Jalview arguments <em>after</em> the --args
+ parameter)
+ </em><br/><br/></li>
+ <li><em><font size="3"><a name="jvm"/>Directly opening Jalview
+ with a JVM</font></em> <br /> Launching Jalview directly with a JVM is
+ entirely possible, but is not recommended for regular interactive
+ use because it bypasses Jalview's launcher which also handles
+ automatic updates and configuration of other aspects of Jalview
+ operation. <br /> However by launching Jalview in this way you
+ have full access to the Java command line arguments. In particular
+ you can set the maximum allowed memory with the <em>-Xmx...</em>
+ JVM argument. <br /> <em>-Xmx</em> should be immediately followed
+ (no space or equals) by the maximum amount of memory specified in
+ bytes, or in kilobytes, megabytes or gigabytes by following the
+ number with a "k", "m" or "g" respectively. <br />For example: <pre>
+ -Xmx8g</pre>Jalview binaries for Windows and macOS are distributed
+ with their own JVM which you will find in
+ <ul>
+ <li><em>Windows:</em> .../Jalview/jre/bin/java.exe</li>
+ <li><em>macOS:</em>
+ .../Jalview.app/Contents/Resources/app/jre/Contents/Home/bin/java</li>
+ </ul> For linux and other unixes you will have to install a Java 1.8
+ JRE (we recommend the ones found at <a
+ href="https://adoptopenjdk.net">https://adoptopenjdk.net/</a>) <br />
+ <br /> You will also need to reference the "appdir" release
+ folder with all of the Jalview jar files.
<ul>
- <li><em>Windows:</em> .../Jalview/jre/bin/java.exe</li>
- <li><em>macOS:</em> .../Jalview.app/Contents/Resources/app/jre/Contents/Home/bin/java</li>
- </ul>
- For linux and other unixes you will have to install a Java 1.8 JRE (we recommend the ones found at <a href="https://adoptopenjdk.net">https://adoptopenjdk.net/</a>)
- </p>
- <p>
- You will also need to reference the "appdir" release folder with all of the Jalview jar files.
- <br/>
- On Windows this will be
- <pre>\PATH_TO_JALVIEW\release</pre>
- whereas on macOS it will be
- <pre>/Applications/Jalview.app/Contents/Resources/app/release</pre>
- and on linux or unix
- <pre>/PATH_TO_JALVIEW/release</pre>
- </p>
- <p>
- Assuming the <em>java</em> (or <em>java.exe</em> on Windows) commands are available to you, you can run, e.g.
- <pre>
+ <li>On Windows this will be <pre>\PATH_TO_JALVIEW\release</pre>
+ </li>
+ <li>On macOS it will be <pre>/Applications/Jalview.app/Contents/Resources/app/release</pre>
+ and on linux or unix <pre>/PATH_TO_JALVIEW/release</pre>
+ </li>
+ </ul> Assuming the <em>java</em> (or <em>java.exe</em> on Windows)
+ commands are available to you, you can run, e.g. <pre>
java -Xmx1500m -cp "/PATH_TO_RELEASE_DIR/*" jalview.bin.Jalview
- </pre>
- or on Windows
- <pre>
+ </pre> Or on Windows <pre>
java.exe -Xmx1500m -cp "\PATH_TO_RELEASE_DIR\*" jalview.bin.Jalview
- </pre>
- <em>Note</em> that the classpath argument wildcard must be simply a '*' and not '*.jar'. This is a limitation of Java.
- </p>
- <p>
- You can also add other Jalview command line arguments as above after the <em>jalview.bin.Jalview</em> class name (you cannot use <em>jvl</em> files if launching Jalview in this way).
- </li>
-
-
+ </pre> <em>Note:</em> for this to work the classpath argument wildcard <strong>must</strong> be simply
+ a '*' and not '*.jar'. <br /> <br />
+ You can also add other <a href="features/commandline.html">Jalview
+ command line arguments</a> as above after the <em>jalview.bin.Jalview</em>
+ class name, but <strong>you cannot use <em>jvl</em> files
+ </strong> if launching Jalview in this way.</li>
</ul>
-
</body>
</html>
git://source.jalview.org / jalview.git / commitdiff