help/help/html/features/commandline.html

   1 <html>
   2 <!--
   3  * Jalview - A Sequence Alignment Editor and Viewer ($$Version-Rel$$)
   4  * Copyright (C) $$Year-Rel$$ The Jalview Authors
   5  *
   6  * This file is part of Jalview.
   7  *
   8  * Jalview is free software: you can redistribute it and/or
   9  * modify it under the terms of the GNU General Public License
  10  * as published by the Free Software Foundation, either version 3
  11  * of the License, or (at your option) any later version.
  12  *
  13  * Jalview is distributed in the hope that it will be useful, but
  14  * WITHOUT ANY WARRANTY; without even the implied warranty
  15  * of MERCHANTABILITY or FITNESS FOR A PARTICULAR
  16  * PURPOSE.  See the GNU General Public License for more details.
  17  *
  18  * You should have received a copy of the GNU General Public License
  19  * along with Jalview.  If not, see <http://www.gnu.org/licenses/>.
  20  * The Jalview Authors are detailed in the 'AUTHORS' file.
  21  -->
  22 <head>
  23 <title>Running Jalview from the command line</title>
  24 </head>
  25 <body>
  26   <p>
  27     <strong>Running Jalview from the command line</strong>
  28   </p>
  29   <p>
  30     Jalview can be run from the command line, and provides a <a
  31       href="clarguments.html">range of arguments</a>. These arguments
  32     can also be passed via <strong>.JVL</strong> files, which are opened
  33     automatically by the Jalview application when double-clicked in a
  34     file browser on Windows and OSX.
  35   </p>
  36
  37   <p>From version 2.11.2, Jalview includes a <strong>launching shell script</strong> which is the recommended way to
  38   launch an installed Jalview application from the command line.  It supports all the <a href="clarguments.html">command line arguments</a>
  39   that Jalview has previously supported, but makes it easier to launch directly from the command line.</p>
  40
  41   <p>There are some important differences between the using the launching script and launching Jalview from its icon:
  42   <ul>
  43   <li>The launching script will NOT look for updates or perform automatic updates.</li>
  44   <li>The launching script cannot open or use JVL files.</li>
  45   </ul>
  46   </p>
  47
  48   <p>If you installed Jalview prior to version 2.11.2 you will not have had the option to add the launching shell script to your PATH.
  49   If your application has updated to 2.11.2 then the scripts will now be there, but not in your <code>PATH</code>.
  50   There are instructions below to add the launching shell script to your <code>PATH</code> if you want to do so.</p>
  51
  52   <ul>
  53
  54   <li>
  55   <p><em>In <strong>Linux</strong> or <strong>Unix</strong> (<code>jalview.sh</code>)</em></p>
  56   <p>The installer gives you the option of adding a symbolic link to
  57   that script in your <code>$PATH</code>, if it finds a suitable place that your user can add such a
  58   link (e.g. <code>~/bin</code>, <code>~/.local/bin</code>, <code>~/local/bin</code>, <code>~/opt/bin</code>).  If you chose that option then
  59   you should be able to launch Jalview on the command line with the simple command
  60   <pre>jalview</pre>
  61   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
  62   launching shell script with the command
  63   <pre>ln -s /PATH_TO_JALVIEW/bin/jalview.sh jalview</pre>
  64   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>.
  65   </li>
  66
  67   <li>
  68   <p><em>In <strong>Windows</strong> (<code>jalview.bat</code>, <code>jalview.ps1</code>)</em></p>
  69   <p>The installer gives you the option of adding Jalview's script folder to your <code>%PATH%</code> allowing you to launch Jalview
  70   in a Command Prompt simply with the command
  71   <pre>jalview</pre>
  72   If you didn't choose that option during installation (or used an earlier version installer), you can either
  73   </p>
  74   <ul>
  75   <li>
  76   add the <code>\PATH_TO_JALVIEW\bin</code> folder to your <code>%PATH%</code>, or
  77   </li>
  78   <li>
  79   run the launcher script on the command line with its full path
  80   <pre>\PATH_TO_JALVIEW\bin\jalview.bat</pre>
  81   (you can leave off the <code>.bat</code> extension if you want).
  82   </li>
  83   </ul>
  84   The <code>jalview.bat</code> file is a generic wrapper around the
  85   PowerShell script <code>jalview.ps1</code> in the same folder.  This PowerShell script should work with both
  86   PowerShell 5.x (which is installed by default on all modern Windows machines), and also PowerShell 6.0+
  87   which might have been installed afterwards.
  88   </li>
  89
  90   <li>
  91   <p><em>In <strong>macOS</strong> (<code>jalview</code>)</em></p>
  92   <p>
  93   The script you should use to launch Jalview is linked to as
  94   <pre>/Applications/Jalview.app/Contents/MacOS/jalview</pre>
  95   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>.
  96   </p>
  97   <p>
  98   <em>If Jalview automatically updated from a version before 2.11.2</em> you will have to make a symbolic link to <code>/Applications/Jalview.app/Content/Resources/app/bin/jalview.sh</code> with the command
  99   <pre>ln -s /Applications/Jalview.app/Content/Resources/app/bin/jalview.sh jalview</pre>
 100   </p>
 101   </li>
 102
 103   <li>
 104   <p><em>Future</em></p>
 105   A future version of Jalview will include a tool to allow adding these "<code>jalview</code>" links to your <code>PATH</code> automatically.
 106   </li>
 107
 108   </ul>
 109
 110   <p><strong>Older versions of Jalview</strong></p>
 111
 112   <p>
 113   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
 114   use a more platform specific way to launch and use command line arguments.
 115
 116   <ul>
 117     <li>Standard installation on Linux/Unix:
 118     <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>
 119     </li>
 120     <li>Standard installation on Windows:
 121     <pre>\PATH_TO_JALVIEW\Jalview.exe -open %HOMEPATH%\myalignment.fa</pre>
 122     </li>
 123     <li>OSX Application:
 124     <pre>open /Applications/Jalview.app --args -open /FULL/PATH/TO/myalignment.fa</pre>
 125     <em>(put all the Jalview arguments <em>after</em> the --args parameter, and note that paths to files should be full paths from <code>/</code>)</em>
 126     <br />
 127     <br /></li>
 128     <li>Jalview standalone executable Jar<pre>
 129         &lt;Path to Java home&gt;/bin/java -jar &lt;Path to Jalview Jar&gt;/jalview-all-1.8.jar -open myalignment.fa</pre></li>
 130   </ul>
 131   <p>
 132     If you have installed Jalview via <em>conda</em> or another package
 133     manager then you most likely have a 'jalview' command available in
 134     your terminal shell's default path. Alternately, if you have built
 135     Jalview from source, then take a look at the doc/building.md file
 136     included in the source distribution.
 137   </p>
 138   <p>
 139     Use '-help' to get more information on the <a
 140       href="clarguments.html">command line arguments</a> that Jalview
 141     accepts.
 142   </p>
 143   <p>
 144     <strong>Passing JVM Arguments to Jalview</strong><br /> If you need
 145     to modify parameters for Jalview's Java Virtual Machine, or
 146     configure system properties, then take a look at the instructions
 147     for how to <a href="../memory.html#jvm">setting the JVM's
 148       maximum memory</a>.<br />
 149   <p>
 150     <strong>Changing Jalview's 'Look and Feel'</strong> <br />If you
 151     are experiencing issues with the font size or layout of Jalview's
 152     GUI, you can try changing Jalview's 'Look and feel' by
 153     specifying a custom system property 'laf' on startup (see <a
 154       href="../memory.html#jvm">setting the JVM's memory</a> for
 155     instructions on how to do this for your platform). <br />For the
 156     Jalview standalone executable jar, simply provide one of the
 157     property settings before the -jar argument
 158   </p>
 159   <ul>
 160     <li>-Dlaf=system (default look and feel for the OS)</li>
 161     <li>-Dlaf=crossplatform (Java's Metal Look and Feel)</li>
 162     <li>-Dlaf=nimbus (Java's alternative Nimbus Look and Feel)</li>
 163     <li>-Dlaf=mac (only has an effect on OSX)</li>
 164     <li>-Dlaf=gtk (only has an effect on Linux)</li>
 165     <li>-Dlaf=metal (force Java's Metal Look and Feel, default on linux)</li>
 166     <li>-Dlaf=quaqua (macOS only. Force attempt at old macOS theme)</li>
 167     <li>-Dlaf=vaqua (macOS only. Force attempt at modern macOS theme)</li>
 168   </ul>
 169   The currently configured look and feel is logged to Jalview's console.
 170   Once the look and feel has been changed, it will be stored in
 171   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.
 172
 173   <p>&nbsp;</p>
 174   <p>&nbsp;</p>
 175 </body>
 176 </html>