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>.
  32   </p>
  33   <p>There are a few different ways to do this:</p>
  34   <ul>
  35     <li>Use the <strong>jalview</strong> command that links to a <strong>launch
  36         script</strong>. Launch scripts are available if you are running an up to
  37       date version of Jalview (at least 2.11.2.0), or have installed
  38       Jalview via a package manager (e.g. conda, homebrew, apt).
  39     </li>
  40     <li>Embed arguments in a <strong>.JVL</strong> file. These
  41       files will be opened automatically by the Jalview application when
  42       double-clicked in a file browser on Windows and OSX.
  43     </li>
  44     <li>Execute the Jalview standalone Jar file with an existing
  45       Java installation</li>
  46       <li>For older versions of Jalview, call the <a href="#olderinstalls">native launch program directly</a>.
  47   </ul>
  48   <p>
  49     <strong><a name="script">Jalview's command line launch
  50         script</a></strong>
  51   <p>Since version 2.11.2, the Jalview native application includes a <strong>launching shell script</strong>. This is the easiest way to
  52   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>
  53   jalview</pre>
  54
  55
  56   <p>There are some important differences between the using the launching script and launching Jalview from its icon:
  57   </p>
  58   <ul>
  59   <li>The launching script will NOT perform automatic updates.</li>
  60   <li>The launching script cannot open or use JVL files.</li>
  61   </ul>
  62
  63   <em><strong>Adding the launch script to your path</strong></em>
  64   <p>
  65     If typing 'jalview' in the terminal prompt (or windows command line)
  66     doesn't work then you will need to add the location of the jalview
  67     launch script to your
  68     <code>PATH</code>.</p><p>
  69     How you do this depends on your operating system.
  70   </p>
  71
  72   <ul>
  73
  74   <li>
  75   <p><em>In <strong>Linux</strong> or <strong>Unix</strong> (<code>jalview.sh</code>)</em></p>
  76   <p>Running the Linux installer will give you the option of adding a symbolic link to
  77   that script in your <code>$PATH</code>, if it finds a suitable place that your user can add such a
  78   link (e.g. <code>~/bin</code>, <code>~/.local/bin</code>, <code>~/local/bin</code>, <code>~/opt/bin</code>).  If you chose that option then
  79   you should be able to launch Jalview on the command line with the simple command
  80   <pre>jalview</pre>
  81   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
  82   launching shell script with the command
  83   <pre>ln -s /PATH_TO_JALVIEW/bin/jalview.sh jalview</pre>
  84   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>.
  85   </li>
  86
  87   <li>
  88   <p><em>In <strong>Windows</strong> (<code>jalview.bat</code>, <code>jalview.ps1</code>)</em></p>
  89   <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
  90   in a Command Prompt simply with the command
  91   <pre>jalview</pre>
  92   If you didn't choose that option during installation (or used an earlier version installer), you can either
  93   </p>
  94   <ul>
  95   <li>
  96   add the <code>\PATH_TO_JALVIEW\bin</code> folder to your <code>%PATH%</code>, or
  97   </li>
  98   <li>
  99   run the launcher script on the command line with its full path
 100   <pre>\PATH_TO_JALVIEW\bin\jalview.bat</pre>
 101   (you can leave off the <code>.bat</code> extension if you want).
 102   </li>
 103   </ul>
 104   The <code>jalview.bat</code> file is a generic wrapper around the
 105   PowerShell script <code>jalview.ps1</code> in the same folder.  This PowerShell script should work with both
 106   PowerShell 5.x (which is installed by default on all modern Windows machines), and also PowerShell 6.0+
 107   which might have been installed afterwards.
 108   </li>
 109
 110   <li>
 111   <p><em>In <strong>macOS</strong> (<code>jalview</code>)</em></p>
 112                         <p>We don't currently provide a macOS installer program, so you
 113                                 will need to add the command to you path manually. The script you
 114                                 should use to launch Jalview is linked to as
 115                         <pre>/Applications/Jalview.app/Contents/MacOS/jalview</pre> so you
 116                         can run that command with its full path, or make your own symbolic
 117                         link to there, or add that folder to your <code>$PATH</code>. <pre>echo /Applications/Jalview.app/Contents/Resources/app/bin | sudo tee -a /etc/paths.d/Jalview</pre>
 118                         This adds the directory
 119                         &quot;/Applications/Jalview.app/Contents/Resources/app/bin/&quot;
 120                         to a &quot;Jalview&quot; file in the /etc/paths.d/ directory. The
 121                         lines from all the files in this directory are added the $PATH
 122                         variable for all shells and users.
 123                         </p>
 124                         <p>
 125                                 If you cannot see the
 126                                 <code>jalview</code>
 127                                 command in the MacOS directory, then you probably have an older
 128                                 Jalview installation. In that case, you should make a symbolic link
 129                                 directly to the launch script with the command
 130                         <pre>ln -s /Applications/Jalview.app/Content/Resources/app/bin/jalview.sh jalview</pre>
 131                         <em>If this doens't work, check your installation is running
 132                                 Jalview 2.11.2.0 or later.</em>
 133                         </p>
 134                 </li>
 135  </ul>
 136 <!--  <p><em>Future</em></p>
 137   A future version of Jalview will include a tool to allow adding these "<code>jalview</code>" links to your <code>PATH</code> automatically.
 138   </li>
 139
 140   </ul>
 141 -->
 142   <p><strong><a name="olderinstalls">Older versions of Jalview</a></strong></p>
 143
 144   <p>
 145   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
 146   use a more platform specific way to launch and use command line arguments.
 147
 148   <ul>
 149     <li>Standard installation on Linux/Unix:
 150     <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>
 151     </li>
 152     <li>Standard installation on Windows:
 153     <pre>\PATH_TO_JALVIEW\Jalview.exe -open %HOMEPATH%\myalignment.fa</pre>
 154     </li>
 155     <li>OSX Application:
 156     <pre>open /Applications/Jalview.app --args -open /FULL/PATH/TO/myalignment.fa</pre>
 157     <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>
 158     <br />
 159     <br /></li>
 160     <li>Jalview standalone executable Jar<pre>
 161         &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>
 162   </ul>
 163   <p>
 164     If you have installed Jalview via <em>conda</em> or another package
 165     manager then you most likely have a 'jalview' command available in
 166     your terminal shell's default path. Alternately, if you have built
 167     Jalview from source, then take a look at the doc/building.md file
 168     included in the source distribution.
 169   </p>
 170   <p>
 171     Use '-help' to get more information on the <a
 172       href="clarguments.html">command line arguments</a> that Jalview
 173     accepts.
 174   </p>
 175   <p>
 176     <strong>Passing JVM Arguments to Jalview</strong><br /> If you need
 177     to modify parameters for Jalview's Java Virtual Machine, or
 178     configure system properties, then take a look at the instructions
 179     for how to <a href="../memory.html#jvm">setting the JVM's
 180       maximum memory</a>.<br />
 181   <p>
 182     <strong>Changing Jalview's 'Look and Feel'</strong> <br />If you
 183     are experiencing issues with the font size or layout of Jalview's
 184     GUI, you can try changing Jalview's 'Look and feel' by
 185     specifying a custom system property 'laf' on startup (see <a
 186       href="../memory.html#jvm">setting the JVM's memory</a> for
 187     instructions on how to do this for your platform). <br />For the
 188     Jalview standalone executable jar, simply provide one of the
 189     property settings before the -jar argument
 190   </p>
 191   <ul>
 192     <li>-Dlaf=system (default look and feel for the OS)</li>
 193     <li>-Dlaf=crossplatform (Java's Metal Look and Feel)</li>
 194     <li>-Dlaf=nimbus (Java's alternative Nimbus Look and Feel)</li>
 195     <li>-Dlaf=mac (only has an effect on OSX)</li>
 196     <li>-Dlaf=gtk (only has an effect on Linux)</li>
 197     <li>-Dlaf=metal (force Java's Metal Look and Feel, default on linux)</li>
 198     <li>-Dlaf=quaqua (macOS only. Force attempt at old macOS theme)</li>
 199     <li>-Dlaf=vaqua (macOS only. Force attempt at modern macOS theme)</li>
 200   </ul>
 201   The currently configured look and feel is logged to Jalview's console.
 202   Once the look and feel has been changed, it will be stored in
 203   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.
 204
 205   <p>&nbsp;</p>
 206   <p>&nbsp;</p>
 207 </body>
 208 </html>