<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>.
</p>
+ <p>There are a few different ways to do this:</p>
+ <ul>
+ <li>Use the <strong>jalview</strong> command that links to a <strong>launch
+ script</strong>. Launch scripts are available if you are running an up to
+ date version of Jalview (at least 2.11.2.0), or have installed
+ Jalview via a package manager (e.g. conda, homebrew, apt).
+ </li>
+ <li>Embed arguments in a <strong>.JVL</strong> file. These
+ files will be opened automatically by the Jalview application when
+ double-clicked in a file browser on Windows and OSX.
+ </li>
+ <li>Execute the Jalview standalone Jar file with an existing
+ Java installation</li>
+ <li>For older versions of Jalview, call the <a href="#olderinstalls">native launch program directly</a>.
+ </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:
+ <strong><a name="script">Jalview's command line launch
+ script</a></strong>
+ <p>Since version 2.11.2, the Jalview native application includes a <strong>launching shell script</strong>. This is the easiest way to
+ launch an installed Jalview application from the command line. </p><p>To run the <strong>launch script</strong>, simply open a Terminal (or Command prompt on Windows), and type:<pre>
+ jalview</pre>
+
+
+ <p>There are some important differences between the using the launching script and launching Jalview from its icon:
+ </p>
+ <ul>
+ <li>The launching script will NOT perform automatic updates.</li>
+ <li>The launching script cannot open or use JVL files.</li>
+ </ul>
+
+ <em><strong>Adding the launch script to your path</strong></em>
+ <p>
+ If typing 'jalview' in the terminal prompt (or windows command line)
+ doesn't work then you will need to add the location of the jalview
+ launch script to your
+ <code>PATH</code>.</p><p>
+ How you do this depends on your operating system.
+ </p>
+
+ <ul>
+
+ <li>
+ <p><em>In <strong>Linux</strong> or <strong>Unix</strong> (<code>jalview.sh</code>)</em></p>
+ <p>Running the Linux installer will give you the option of adding a symbolic link to
+ that script in your <code>$PATH</code>, if it finds a suitable place that your user can add such a
+ link (e.g. <code>~/bin</code>, <code>~/.local/bin</code>, <code>~/local/bin</code>, <code>~/opt/bin</code>). If you chose that option then
+ you should be able to launch Jalview on the command line with the simple command
+ <pre>jalview</pre>
+ If you didn't choose that option during installation (or used an earlier version installer), or wish to make another symbolic link, you can link to the
+ launching shell script with the command
+ <pre>ln -s /PATH_TO_JALVIEW/bin/jalview.sh jalview</pre>
+ or you could add <code>/PATH_TO_JALVIEW/bin</code> to your own <code>$PATH</code> as it already contains a symbolic link <code>jalview</code>.
+ </li>
+
+ <li>
+ <p><em>In <strong>Windows</strong> (<code>jalview.bat</code>, <code>jalview.ps1</code>)</em></p>
+ <p>The Windows installer will give you the option of adding Jalview's script folder to your <code>%PATH%</code> allowing you to launch Jalview
+ in a Command Prompt simply with the command
+ <pre>jalview</pre>
+ If you didn't choose that option during installation (or used an earlier version installer), you can either
+ </p>
+ <ul>
+ <li>
+ add the <code>\PATH_TO_JALVIEW\bin</code> folder to your <code>%PATH%</code>, or
+ </li>
+ <li>
+ run the launcher script on the command line with its full path
+ <pre>\PATH_TO_JALVIEW\bin\jalview.bat</pre>
+ (you can leave off the <code>.bat</code> extension if you want).
+ </li>
+ </ul>
+ The <code>jalview.bat</code> file is a generic wrapper around the
+ PowerShell script <code>jalview.ps1</code> in the same folder. This PowerShell script should work with both
+ PowerShell 5.x (which is installed by default on all modern Windows machines), and also PowerShell 6.0+
+ which might have been installed afterwards.
+ </li>
+
+ <li>
+ <p><em>In <strong>macOS</strong> (<code>jalview</code>)</em></p>
+ <p>
+ We don't currently provide a macOS installer program, so you will need to add the command to you path manually. The script you should use to launch Jalview is linked to as
+ <pre>/Applications/Jalview.app/Contents/MacOS/jalview</pre>
+ so you can run that command with its full path, or make your own symbolic link to there, or add that folder to your <code>$PATH</code>.
+ </p>
+ <p>
+ If you cannot see the
+ <code>jalview</code>
+ command in the MacOS directory, then you probably have an older
+ Jalview installation. In that case, you should make a symbolic
+ link directly to the launch script with the command
+ <pre>ln -s /Applications/Jalview.app/Content/Resources/app/bin/jalview.sh jalview</pre>
+ <em>If this doens't work, check your installation is running
+ Jalview 2.11.2.0 or later.</em>
+ </p>
+ </li>
+ </ul>
+<!-- <p><em>Future</em></p>
+ A future version of Jalview will include a tool to allow adding these "<code>jalview</code>" links to your <code>PATH</code> automatically.
+ </li>
+
+ </ul>
+-->
+ <p><strong><a name="olderinstalls">Older versions of Jalview</a></strong></p>
+
+ <p>
+ If you are using a version of Jalview prior to 2.11.2, you can still launch from the command line, but you will have to
+ use a more platform specific way to launch and use command line arguments.
+
+ <ul>
+ <li>Standard installation on Linux/Unix:
+ <pre>/PATH_TO_JALVIEW/Jalview -open https://www.jalview.org/examples/jpred_msa.fasta -annotations https://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 /FULL/PATH/TO/myalignment.fa</pre>
+ <em>(put all the Jalview arguments <em>after</em> the --args parameter, and note that <strong>all files must be specified with their full paths</strong>)</em>
+ <br />
+ <br /></li>
+ <li>Jalview standalone executable Jar<pre>
+ <Path to Java home>/bin/java -jar <Path to Jalview Jar>/jalview-all-1.8.jar -open myalignment.fa</pre></li>
+ </ul>
+ <p>
+ 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, or
+ configure system properties, then take a look at the instructions
+ for how to <a href="../memory.html#jvm">setting the JVM's
+ maximum memory</a>.<br />
+ <p>
+ <strong>Changing Jalview's 'Look and Feel'</strong> <br />If you
+ are experiencing issues with the font size or layout of Jalview's
+ GUI, you can try changing Jalview's 'Look and feel' by
+ specifying a custom system property 'laf' on startup (see <a
+ href="../memory.html#jvm">setting the JVM's memory</a> for
+ instructions on how to do this for your platform). <br />For the
+ Jalview standalone executable jar, simply provide one of the
+ property settings before the -jar argument
</p>
+ <ul>
+ <li>-Dlaf=system (default look and feel for the OS)</li>
+ <li>-Dlaf=crossplatform (Java's Metal Look and Feel)</li>
+ <li>-Dlaf=nimbus (Java's alternative Nimbus Look and Feel)</li>
+ <li>-Dlaf=mac (only has an effect on OSX)</li>
+ <li>-Dlaf=gtk (only has an effect on Linux)</li>
+ <li>-Dlaf=metal (force Java's Metal Look and Feel, default on linux)</li>
+ <li>-Dlaf=quaqua (macOS only. Force attempt at old macOS theme)</li>
+ <li>-Dlaf=vaqua (macOS only. Force attempt at modern macOS theme)</li>
+ </ul>
+ The currently configured look and feel is logged to Jalview's console.
+ Once the look and feel has been changed, it will be stored in
+ Jalview's .jalview_properties file for future Jalview sessions. This property is <strong>PREFERRED_LAF</strong> and can also be used to set the Look and feel by editing your .jalview_properties file.
+
<p> </p>
<p> </p>
</body>
git://source.jalview.org / jalview.git / blobdiff