Merge pull request #22 from petebankhead/config

Add config file info

docs/reference/config.rst

@@ -0,0 +1,95 @@
+*************
+Configuration
+*************
+
+QuPath's launcher is controlled by a configuration file generated by jpackage.
+It exists somewhere within the installation (probably the *app* subdirectory) and has a name like *QuPath.cfg*.
+
+The *.cfg* file provides a way to modify some aspects of QuPath's behavior via the ``[JavaOptions]`` section.
+The contents may change across QuPath versions, but the following gives an example:
+
+.. code:: bash
+  
+  [JavaOptions]
+  java-options=-Djpackage.app-version=0.3.0
+  java-options=-Djava.library.path=$APPDIR
+  java-options=--illegal-access=permit
+  java-options=-XX:MaxRAMPercentage=50
+
+
+The most relevant JavaOptions you might want to change are described below.
+
+.. tip::
+
+  These configuration options are also very useful when running QuPath from within an IDE.
+
+
+Java parameters
+===============
+
+Memory-related parameters
+-------------------------
+
+These control the amount of memory available to Java.
+
+Note, however, that native libraries accessed via JavaCPP (e.g. OpenCV) accesses memory differently -- and the amount of memory QuPath actually uses can therefore exceed these limits.
+
+Because many computationally/memory intensive operations use JavaCPP (e.g. pixel classification), it is usually best to keep the memory limits here relatively conservative.
+
+.. glossary::
+
+  -XX:MaxRAMPercentage=50
+    Set the default maximum memory for the Java virtual machine to half of the system memory.
+
+  -Xmx16G
+    Set the default maximum memory for the Java virtual machine to 16 GB.
+    May be used as an alternative to ``--XX:MaxRAMPercentage``
+
+  -Xms16G
+    Set the default *starting* memory for the Java virtual machine to 16 GB.
+    Setting this to be equal to ``-Xmx`` may slightly improve performance, since it means QuPath does not need to increase the available memory over time to reach its maximum. 
+
+Other parameters
+-------------------------
+
+.. glossary::
+
+  --illegal-access=permit
+    Sounds dramatic, but this restores pre-Java-16 default behavior to enable access to some internal classes. Many QuPath dependencies still require this, as they have not been updated to handle the stricter access permissions of recent Java versions.
+
+
+
+System properties
+=================
+
+These are specified with ``-Dproperty.name=value``
+
+General system properties
+-------------------------
+
+.. glossary::
+
+  jpackage.app-version
+    Application version. This *should* correspond to the QuPath version, but unfortunately it sometimes difference because of platform-specific rules, e.g. macOS forbidding the first number to be 0.
+
+  java.library.path
+    Path in which Java will look for native libraries (e.g. OpenSlide).
+    You can change this if you need to make other native libraries available to QuPath extensions, e.g. to use ``$APPDIR:/path/to/somewhere/else/lib``.
+
+    Note that on Windows the separator is ``;`` rather than ``:``.
+
+  java.util.concurrent.ForkJoinPool.common.parallelism
+    Control the number of threads used in the common ForkJoinPool.
+    This determines the default parallelism of parallel streams.
+    Because streams provide an easy way parallelize some operations, and they are used in several places within QuPath, this property can be useful if memory errors are seen because of too many threads relative to the amount of available memory.
+
+QuPath-specific properties
+--------------------------
+
+.. glossary::
+
+  qupath.prefs.name
+    Specify the location for the QuPath preferences, as a node name (not a file path). This is useful if you want to have two separate QuPath instances installed with different preferences, or if you are developing a QuPath extension and don't want to load extensions from another QuPath installation.
+
+    Example use:
+    ``-Dqupath.prefs.name="qupath.eclipse/0.3``

docs/reference/index.rst

@@ -8,5 +8,6 @@ Reference
   faqs
   shortcuts
   commands
+  config
   building
   projects_structure