[WIP] Add information for macOS into the user docs

Modify command line topics to indicate which ones do/don't apply to OS X, plus any specific information for this platform. Updates also for the directory conventions topic, environment variables topic, and messages. Closes: eclipse-openj9#82 Signed-off-by: Sue Chaplain <[email protected]>
SueChaplain · Jan 7, 2019 · 46dca2b · 46dca2b
1 parent 19f1076
commit 46dca2b
Show file tree

Hide file tree

Showing 27 changed files with 88 additions and 122 deletions.
diff --git a/docs/cmdline_specifying.md b/docs/cmdline_specifying.md
@@ -45,7 +45,6 @@ Use single or double quotation marks for command-line options only when explicit
 
 The sequence of the Java options on the command line defines which options take precedence during startup. Rightmost options have precedence over leftmost options. In the following example, the `-Xjit` option takes precedence:
 
-    :::java
     java -Xint -Xjit myClass
 
 
@@ -81,31 +80,26 @@ At startup, the list of VM arguments is constructed in the following order, with
 
     - On Windows&trade; systems:
 
-            :::java
             set IBM_NOSIGHANDLER=<non_null_string>
 
-    - On AIX&reg;, Linux&reg;, and z/OS&reg; systems:
+    - On AIX&reg;, Linux&reg;, OS X&reg;, and z/OS&reg; systems:
 
-            :::java
             export IBM_NOSIGHANDLER=<non_null_string>
 
 4.  The `OPENJ9_JAVA_OPTIONS` environment variable. You can set command-line options using this environment variable. The options that you specify with this environment variable are added to the command line when a VM starts in that environment. The environment variable can contain multiple blank-delimited argument strings, but must not contain comments. For example:
 
     - On Windows systems:
 
-            :::java
             set OPENJ9_JAVA_OPTIONS="-Dmysysprop1=tcpip -Dmysysprop2=wait -Xdisablejavadump"
 
-    - On AIX, Linux, and z/OS systems:
+    - On AIX, Linux, OS X, and z/OS systems:
 
-            :::java
             export OPENJ9_JAVA_OPTIONS="-Dmysysprop1=tcpip -Dmysysprop2=wait -Xdisablejavadump"
 
     <i class="fa fa-pencil-square-o" aria-hidden="true"></i> **Note:** The environment variable `JAVA_TOOLS_OPTIONS` is equivalent to `OPENJ9_JAVA_OPTIONS` and is available for compatibility with JVMTI. The equivalent `IBM_JAVA_OPTIONS` environment variable is deprecated and will be removed in a future release.
 
 5.  Options that are specified on the command line. For example:
 
-        :::java
         java -Dmysysprop1=tcpip -Dmysysprop2=wait -Xdisablejavadump MyJavaClass
 
     The Java launcher adds some automatically generated arguments to this list, such as the names of the main class.
@@ -114,7 +108,6 @@ You can also use the `-Xoptionsfile` parameter to specify VM options. This param
 
 To troubleshoot startup problems, you can check which options are used by the OpenJ9 VM. Append the following command-line option, and inspect the Java core file that is generated:
 
-    :::java
     -Xdump:java:events=vmstart
 
 Here is an extract from a Java core file that shows the options that are used:

diff --git a/docs/dcomibmtoolsattachenable.md b/docs/dcomibmtoolsattachenable.md
@@ -30,7 +30,7 @@ Enable the Attach API for this application.
 
         -Dcom.ibm.tools.attach.enable=[yes|no]
 
-On AIX&reg;, Linux&reg;, and Windows&trade; systems, the following default applies:
+On AIX&reg;, Linux&reg;, OS X&reg;, and Windows&trade; systems, the following default applies:
 
 | Value        | Effect  | Default                                                                            |
 |--------------|---------|:----------------------------------------------------------------------------------:|

diff --git a/docs/env_var.md b/docs/env_var.md
@@ -33,27 +33,27 @@ Although the OpenJ9 virtual machine (VM) recognizes many environment variables,
 To show the current environment, run:
 
 -   `set` (Windows&trade;)
--   `env` (AIX&reg;, Linux&reg;, and macOS&reg;)
+-   `env` (AIX&reg;, Linux&reg;, and OS X&reg;)
 -   `set` (z/OS&reg;)
 
 To show a particular environment variable, run:
 
 -   `echo %ENVNAME%` (Windows)
--   `echo $ENVNAME` (AIX, Linux, macOS, and z/OS)
+-   `echo $ENVNAME` (AIX, Linux, OS X, and z/OS)
 
-Use values exactly as shown in the documentation. The names of environment variables are case-sensitive in AIX, Linux, macOS, and z/OS.
+Use values exactly as shown in the documentation. The names of environment variables are case-sensitive in AIX, Linux, OS X, and z/OS.
 
 To set the environment variable **LOGIN\_NAME** to *Fred*, run:
 
 -   `set LOGIN_NAME=Fred` (Windows)
--   `export LOGIN_NAME=Fred` (AIX/Linux: ksh or bash shells)
--   `setenv LOGIN_NAME Fred` (macOS or csh shells)
+-   `export LOGIN_NAME=Fred` (AIX/Linux/OS X: ksh or bash shells)
+-   `setenv LOGIN_NAME Fred` (csh shells)
 
 These variables are set only for the current shell or command-line session.
 
 If you are setting multiple values for an environment variable in a list:
 
--   On AIX, Linux, macOS, and z/OS the separator is typically a colon (:).
+-   On AIX, Linux, OS X, and z/OS the separator is typically a colon (:).
 -   On Windows the separator is typically a semicolon (;).
 
 ## General options
@@ -134,7 +134,7 @@ Setting `JAVA_DUMP_OPTS` affects only those conditions that you specify. Actions
 
 When setting the `JAVA_DUMP_OPTS` environment variable, the mapping of operating system signals to the "condition" is shown in the following table:
 
-| Condition        | z/OS                                                      |  Windows                | Linux and AIX                                     |
+| Condition        | z/OS                                                      |  Windows                | Linux, OS X, and AIX                                     |
 |------------------|-----------------------------------------------------------|-------------------------|---------------------------------------------------|
 | **EXCEPTION**    | SIGTRAP, SIGILL, SIGSEGV, SIGFPE, SIGBUS, SIGSYS, SIGXFSV | SIGILL, SIGSEGV, SIGFPE | SIGTRAP, SIGILL, SIGSEGV, SIGFPE, SIGBUS, SIGXFSV |
 | **INTERRUPT**    | SIGINT, SIGTERM, SIGHUP                                   | SIGINT, SIGTERM         | SIGINT, SIGTERM, SIGHUP                           |
@@ -176,7 +176,7 @@ The following table lists other environment variables that can be set for diagno
 
 | Environment variable                          | Usage Instructions                                                                                              |
 |-----------------------------------------------|-----------------------------------------------------------------------------------------------------------------|
-|`IBM_COREDIR=<directory>`                      | Set this variable to specify an alternative location for system dumps, JIT dumps, and snap trace. On z/OS, `_CEE_DMPTARG` is used instead for snap trace, and transaction dumps are written to TSO according to `JAVA_DUMP_TDUMP_PATTERN`. On Linux, the dump is written to the directory that is specified directory by the operating system before being moved to the specified location.|
+|`IBM_COREDIR=<directory>`                      | Set this variable to specify an alternative location for system dumps, JIT dumps, and snap trace. On z/OS, `_CEE_DMPTARG` is used instead for snap trace, and transaction dumps are written to TSO according to `JAVA_DUMP_TDUMP_PATTERN`. On Linux and OS X, the dump is written to the directory that is specified directory by the operating system before being moved to the specified location.|
 |`IBM_JAVA_ABEND_ON_FAILURE=Y` (z/OS only)      | This setting tells the Java launcher to mark the Task Control Block (TCB) with an abend code if the OpenJ9 VM fails to load or is terminated by an uncaught exception. By default, the Java launcher does not mark the TCB.|
 |`JAVA_DUMP_TDUMP_PATTERN=<string>` (z/OS only) | The specified `<string>` is passed to IEATDUMP to use as the data/set name for the Transaction Dump. The default `<string>` is `%uid.JVM.TDUMP.%job.D%y%m%d.T%H%M%S` (31-bit) or `%uid.JVM.%job.D%y%m%d.T%H%M%S.X&amp;DS` (64-bit), where `%uid` is found from the C code fragment shown in **Notes**.|
 |`JAVA_THREAD_MODEL=<string>`                   | `<string>` can be defined as one of the following values: *NATIVE* (all threads are created as `_MEDIUM_WEIGHT`), *HEAVY* (all threads are created as `_HEAVY_WEIGHT`), *MEDIUM* (same as *NATIVE*), or *NULL*. The default is *NATIVE*. |

diff --git a/docs/messages_intro.md b/docs/messages_intro.md
@@ -91,6 +91,10 @@ For more information about AIX logging, see: [Error-logging overview](http://www
 
 On Linux&reg;, messages are logged by the **syslog** daemon. To find where messages are logged, check the syslog configuration file.
 
+### Finding OS X messages
+
+On OS X&reg;, messages are logged by the **syslog** daemon. However, on Sierra and High Sierra, syslog does not work. If `/var/log/system.log` is not available, `Console.app` can be used instead. 
+
 ### Finding Windows messages
 
 On Windows&trade;, messages are logged in the application events section of the event viewer.

diff --git a/docs/openj9_defaults.md b/docs/openj9_defaults.md
@@ -59,7 +59,7 @@ The last 2 columns show whether the default setting can be changed by a command-
 
 <i class="fa fa-pencil-square-o" aria-hidden="true"></i> **Notes:**
 
-1. On AIX&reg;, Linux&reg;, macOS&reg;, and Windows&trade;: Enabled for **-Xmx** values &le; 57 GB, otherwise disabled.</p>
+1. On AIX&reg;, Linux&reg;, OS X&reg;, and Windows&trade;: Enabled for **-Xmx** values &le; 57 GB, otherwise disabled.</p>
 
     On z/OS&reg;: Enabled for **-Xmx** values &le; 25 GB, otherwise disabled. With [APAR OA49416](http://www.ibm.com/support/docview.wss?uid=isg1OA49416), enabled for **-Xmx** values &le; 57 GB.
 
@@ -68,7 +68,7 @@ The last 2 columns show whether the default setting can be changed by a command-
 
 
 
-|VM setting                                                    |AIX       |Linux    |macOS     |Windows          |z/OS      | Command line           | Env. variable          |
+|VM setting                                                    |AIX       |Linux    |OS X      |Windows          |z/OS      | Command line           | Env. variable          |
 |--------------------------------------------------------------|----------|---------|----------|-----------------|----------|------------------------|------------------------|
 |Default locale                                                |None      |None      |None     |N/A              |None      | <i class="fa fa-times" aria-hidden="true"></i><span class="sr-only">no</span> |<i class="fa fa-check" aria-hidden="true"></i><span class="sr-only">yes</span>|
 |Time to wait before starting plug-in                          |N/A       |Zero      |N/A       |N/A              |N/A       | <i class="fa fa-times" aria-hidden="true"></i><span class="sr-only">no</span> |<i class="fa fa-check" aria-hidden="true"></i><span class="sr-only">yes</span>|

diff --git a/docs/openj9_directories.md b/docs/openj9_directories.md
@@ -28,10 +28,11 @@ The following tables provide a quick reference to the OpenJ9 VM directory locati
 pages refer to the VM directory location as `<vm_dir>`.
 
 
-| Operating system            | Java 8                                  | Java 10 and later                          |
-|-----------------------------|-----------------------------------------|-------------------------------------------|
+| Operating system | Java 8                                  | Java 10 and later                          |
+|------------------|-----------------------------------------|--------------------------------------------|
 | AIX&reg;         | `<install_dir>/jre/lib/ppc[64]/default` | `<install_dir>/` |
-| Linux&reg;     | `<install_dir>/jre/lib/<arch>/default`  | `<install_dir>/` |
+| Linux&reg;       | `<install_dir>/jre/lib/<arch>/default`  | `<install_dir>/` |
+| OS X&reg;        | `<install_dir>/jre/lib/default`         | `<install_dir>/` |
 | Windows&trade;   | `<install_dir>\jre\bin\default`         | `<install_dir>\` |
 | z/OS&reg;        | `<install_dir>/jre/lib/s390[x]/default` | `<install_dir>/` |
 

diff --git a/docs/openj9_support.md b/docs/openj9_support.md
@@ -227,5 +227,5 @@ building OpenJDK 8 on Linux is v4.4.7. However, plans are in place to update the
 | Linux on POWER LE 64-bit    | Ubuntu 16.04             | gcc 7.3                         |
 | Linux on IBM Z 64-bit       | Ubuntu 16.04             | gcc 7.3                         |
 | Windows x86 64-bit          | Windows Server 2012 R2   | Microsoft Visual Studio 2017    |
-| MacOS x86 64-bit            | macOS 10.13.5            | xcode/clang 9.4                 |
+| MacOS x86 64-bit            | OS X 10.13.5             | xcode/clang 9.4                 |
 | AIX POWER BE 64-bit         | AIX 7.1 TL04             | xlc/C++ 13.1.3                  |
diff --git a/docs/xcodecache.md b/docs/xcodecache.md
@@ -22,7 +22,7 @@
 * Classpath-exception-2.0 OR LicenseRef-GPL-2.0 WITH Assembly-exception
 -->
 
-# -Xcodecache 
+# -Xcodecache
 
 Use this option to tune performance.
 
@@ -33,12 +33,11 @@ This option sets the size of each block of memory that is allocated to store the
 
 ## Syntax
 
-        -Xcodecache <size>
+        -Xcodecache<size>
 
 : See [Using -X command-line options](x_jvm_commands) for more information about specifying the `<size>` parameter.
 
 
 
 
 <!-- ==== END OF TOPIC ==== xcodecache.md ==== -->
-
diff --git a/docs/xdiagnosticscollector.md b/docs/xdiagnosticscollector.md
@@ -22,9 +22,15 @@
 * Classpath-exception-2.0 OR LicenseRef-GPL-2.0 WITH Assembly-exception
 -->
 
-# -Xdiagnosticscollector 
+# -Xdiagnosticscollector
 
-This option is now redundant, and only generates a warning message. Use the [IBM&reg; Support Assistant Data Collector](http://www-01.ibm.com/software/support/isa/#isa-dc-dl) instead.
+This option is now redundant and generates only the following warning message:
+
+```
+JVMJ9VM138W The -Xdiagnosticscollector option is not supported by this JVM.
+```
+
+Use the [IBM&reg; Support Assistant Data Collector](http://www-01.ibm.com/software/support/isa/#isa-dc-dl) instead.
 
 
 ## Syntax
@@ -34,4 +40,3 @@ This option is now redundant, and only generates a warning message. Use the [IBM
 
 
 <!-- ==== END OF TOPIC ==== xdiagnosticscollector.md ==== -->
-
diff --git a/docs/xdump.md b/docs/xdump.md
@@ -277,7 +277,7 @@ The following table shows the events that are available as dump agent triggers:
 | Event           |  Triggered when....                                                         | Filters on ....                                                |
 | ----------------|-----------------------------------------------------------------------------|----------------------------------------------------------------|
 | **gpf**         | A General Protection Fault (GPF) occurs.                                    | Not applicable                                                 |
-| **user**        | The VM receives the SIGQUIT (Linux, AIX&reg;, z/OS) or SIGBREAK (Windows&trade;) signal from the operating system.|  Not applicable                      |
+| **user**        | The VM receives the SIGQUIT (Linux, OS X&reg;, AIX&reg;, z/OS) or SIGBREAK (Windows&trade;) signal from the operating system.|  Not applicable                      |
 | **abort**       | The VM receives the SIGABRT signal from the operating system.               | Not applicable                                                 |
 | **vmstart**     | The virtual machine is started.                                             | Not applicable                                                 |
 | **vmstop**      | The virtual machine stops.                                                  | Exit code; for example, `filter=#129..#192#-42#255`            |
@@ -535,7 +535,7 @@ You can filter the **slow** event to change the time threshold from the default
 ```
 
 #### allocation event
-**(Linux and Windows only)**
+**(Linux, OS X, and Windows only)**
 
 You must filter the **allocation** event to specify the size of objects that cause a trigger. You can set the filter size from zero up to the maximum value of a 32-bit pointer on 32-bit platforms, or the maximum value of a 64-bit pointer on 64-bit platforms. Setting the lower filter value to zero triggers a dump on all allocations.
 
@@ -725,7 +725,7 @@ In general, the default request options are sufficient.
 
 Dump output is written to different files, depending on the type of dump and the platform. File names include a time stamp.
 
-| Dump type      | File name  (AIX, Linux, Windows)                                | File name (z/OS)                                                                                         |
+| Dump type      | File name  (AIX, Linux, OS X, Windows)                                | File name (z/OS)                                                                                         |
 |----------------|-----------------------------------------------------------------|----------------------------------------------------------------------------------------------------------|
 | System dump    | core.%Y%m%d.%H%M%S.%pid.dmp                                     |  %uid.JVM.TDUMP.%job.D%Y%m%d.T%H%M%S (31-bit),  %uid.JVM.%job.D%y%m%d.T%H%M%S.X&DS (64-bit) See **Note** |
 | Java dump      | javacore.%Y%m%d.%H%M%S.%pid.%seq.txt                            | javacore.%Y%m%d.%H%M%S.%pid.%seq.txt                                                                     |

diff --git a/docs/xgc.md b/docs/xgc.md
@@ -41,7 +41,7 @@ Options that change the behavior of the Garbage Collector (GC).
 | [`minContractPercent`          ](#mincontractpercent          ) | Sets the minimum percentage of the heap that can be contracted at any given time.                       |
 | [`maxContractPercent`          ](#maxcontractpercent          ) | Sets the maximum percentage of the heap that can be contracted at any given time.                       |
 | [`overrideHiresTimerCheck`     ](#overridehirestimercheck     ) | Overrides GC operating system checks for timer resolution.                                              |
-| [`preferredHeapBase`           ](#preferredheapbase           ) | Sets a memory range for the Java&trade; heap. (AIX&reg;, Linux&reg;, and Windows&trade; only) |
+| [`preferredHeapBase`           ](#preferredheapbase           ) | Sets a memory range for the Java&trade; heap. (AIX&reg;, Linux&reg;, OS X&reg;, and Windows&trade; only) |
 | [`scvNoAdaptiveTenure`         ](#scvnoadaptivetenure         ) | Turns off the adaptive tenure age in the generational concurrent GC policy.                             |
 | [`scvTenureAge`                ](#scvtenureage                ) | Sets the initial scavenger tenure age in the generational concurrent GC policy.                         |
 | [`tlhIncrementSize`            ](#tlhincrementsize            ) | Sets the size of the thread local heap (TLH)  increment                                      |
@@ -142,7 +142,7 @@ Options that change the behavior of the Garbage Collector (GC).
 
 ### `preferredHeapBase`
 
-**(AIX, Linux, Windows only)**
+**(AIX, Linux, OS X, and Windows only)**
 
         -Xgc:preferredHeapBase=<address>
 
@@ -152,8 +152,7 @@ Options that change the behavior of the Garbage Collector (GC).
 
 : where, `<address>` is the base memory address for the heap. Use this option with the `-Xcompressedrefs` option to allocate the heap you specify with the [`-Xmx`](xms.md) option, in a memory range of your choice. If `-Xcompressedrefs` is not specified, this option has no effect. In the following example, the heap is located at the 4 GB mark, leaving the lowest 4 GB of address space for use by other processes.
 
-        :::java
-        -Xgc:preferredHeapBase=0x100000000
+      -Xgc:preferredHeapBase=0x100000000
 
     If the heap cannot be allocated in a contiguous block at the `preferredHeapBase` address you specified, an error occurs detailing a Garbage Collection (GC) allocation failure startup. When the `preferredHeapBase` option is used with the [`-Xlp`](xlp.md) option, the `preferredHeapBase` address must be a multiple of the large page size. If you specify an inaccurate heap base address, the heap is allocated with the default page size.
 

diff --git a/docs/xgcpolicy.md b/docs/xgcpolicy.md
@@ -123,7 +123,7 @@ The following options are ignored when specified with `-Xgcpolicy:balanced`:
 
 : The generational concurrent policy (default) uses a concurrent mark phase combined with generational garbage collection to help minimize the time that is spent in any garbage collection pause. This policy is particularly useful for applications with many short-lived objects, such as transactional applications. Pause times can be significantly shorter than with the `optthruput` policy, while still producing good throughput. Heap fragmentation is also reduced.
 
-### `metronome` (AIX&reg;, Linux&reg; only)
+### `metronome` (AIX&reg;, Linux&reg; x86 only)
 
         -Xgcpolicy:metronome