From ee7fcf8d9d817e079c2f0498d149ec45a21f82dc Mon Sep 17 00:00:00 2001 From: Jim Procter Date: Thu, 4 Jul 2019 08:36:42 +0100 Subject: [PATCH] JAL-3348 revised bsoares memory settings documentation and updated docs for launching jalview from command line --- help/help/html/features/commandline.html | 62 ++++++---- help/help/html/memory.html | 194 +++++++++++++----------------- 2 files changed, 117 insertions(+), 139 deletions(-) diff --git a/help/help/html/features/commandline.html b/help/help/html/features/commandline.html index 92d9323..27a1a68 100644 --- a/help/help/html/features/commandline.html +++ b/help/help/html/features/commandline.html @@ -26,38 +26,48 @@

Running Jalview from the command line

-

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.

-

The Java Webstart version of Jalview can be executed from the - command line using something like : - 

javaws http://www.jalview.org/webstart/jalview.jnlp -open
- yourFileName
-
- 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.

- Running Jalview from the InstallAnywhere - installation + Jalview can be run from the command line, and provides a range of arguments. These arguments + can also be passed via .JVL files, which are opened + automatically by the Jalview application when double-clicked in a + file browser on Windows and OSX.

+ The way that you launch Jalview from the command line depends on the + platform you are on, and how it has been installed. + +

- 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.
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 conda 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.

- 
java -classpath "$INSTALL_DIR$/lib/*:$INSTALL_DIR$/jalview.jar" jalview.bin.Jalview -open [FILE]

Use '-help' to get more information on the command line arguments that - Jalview accepts. + href="clarguments.html">command line arguments that Jalview + accepts. +

+

+ Passing JVM Arguments to Jalview
If you need + to modify parameters for Jalview's Java Virtual Machine, then take a + look at the instructions for how to setting + the JVM's maximum memory.

 

 

diff --git a/help/help/html/memory.html b/help/help/html/memory.html index 396507b..4baebf2 100755 --- a/help/help/html/memory.html +++ b/help/help/html/memory.html @@ -28,24 +28,18 @@ Memory Usage Settings for Jalview +

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.

- 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.
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). + Signs that Jalview is Running out of Memory
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).

Jalview Memory Usage Monitor: If you are concerned about @@ -58,108 +52,82 @@ window's background.

- Increasing the memory available to Jalview
- 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. + Increasing the memory available to Jalview
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.
+
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:

Assuming the java (or java.exe on Windows) + commands are available to you, you can run, e.g. 
       java -Xmx1500m -cp "/PATH_TO_RELEASE_DIR/*" jalview.bin.Jalview
-
- or on Windows - 
+
Or on Windows 
       java.exe -Xmx1500m -cp "\PATH_TO_RELEASE_DIR\*" jalview.bin.Jalview
-
- Note that the classpath argument wildcard must be simply a '*' and not '*.jar'. This is a limitation of Java. -

-

- You can also add other Jalview command line arguments as above after the jalview.bin.Jalview class name (you cannot use jvl files if launching Jalview in this way). - - - + Note: for this to work the classpath argument wildcard must be simply + a '*' and not '*.jar'.

+ You can also add other Jalview + command line arguments as above after the jalview.bin.Jalview + class name, but you cannot use jvl files + if launching Jalview in this way. - -- 1.7.10.2