This topic examines commands and the effects of working with completed directive files.
The command line provides an interface to add and print compiler directives while starting a program.
Only one directives file is specifiable from the command line. All directives within that file are added to the directives stack and are immediately active as the program starts. This makes it possible to test the performance effects of directives during a program’s early stages. You’re also free to focus on debugging and developing your program.
Adding Directives Through the Command Line
XX:CompilerDirectivesFile=file
Include this command-line option when you start a Java program. This is shown in the following example, which starts TestProgram:
java -XX:+UnlockDiagnosticVMOptions -XX:CompilerDirectivesFile=File_A.json TestProgram
-XX:+UnlockDiagnosticVMOptions enables diagnostic options. You must enter this before working with directives on the command line.
-XX:CompilerDirectivesFile is a type of diagnostic option. It specifies one directives file to add to the directives stack.
File_A.json is a directives file. It contains any number of directives, all of which are added to the stack of active directives as the program starts.
If File_A.json contains syntax errors or malformed directives, then an error message is displayed and TestProgram does not start.
Printing Directives Through the Command Line
-XX:+CompilerDirectivesPrintAn example of including this diagnostic command on the command line is:
java -XX:+UnlockDiagnosticVMOptions -XX:+CompilerDirectivesPrint -XX:CompilerDirectivesFile=File_A.json TestProgram
Diagnostic commands provide an interface to manage which directives are active at runtime. You can add directives to or remove directives from a running program without restarting it.
Crafting a single perfect directives file may take some iteration and experimentation. However, diagnostic commands provide powerful mechanisms for testing different configurations of directives in the directives stack. Diagnostic commands let you add or remove directives without restarting a running program’s JVM.
The first step in testing directives is to find the process identification (pid) number of your running program.
TestProgram:
11084 TestProgram
All directives in a file are added to the directives stack through a single diagnostic command.
jcmd pid Compiler.directives_add fileAn example is:
jcmd 11084 Compiler.directives_add File_B.jsonThe terminal reports the number of individual directives added. However, if the directives file contains syntax errors or malformed directives, then an error message is displayed, and no directives from the file are added to the stack. There are no changes to the running program.
There are two diagnostic commands that remove directives.
jcmd pid Compiler.directives_remove
To clear every directive you added to the directives stack, enter:
jcmd pid Compiler.directives_clear
It’s not possible to specify an entire file of directives to remove, nor is there any other way to remove directives in bulk.Diagnostic commands are used to print the directives stack of a running program.
jcmd pid Compiler.directives_print
Example output is shown in What Is the Default Directive?The order directives are written in a file, or added to the stack, is very important. The top-most best-matching directive in the stack receives priority and is applied to code compilation.
Diagrams in this topic illustrate the ordering effects in an example directives stack. There are three directive files in this scenario:
File_A contains Directive 1 and Directive 2.
File_B contains Directive 3.
File_C contains Directive 4 and Directive 5.
The Initial State of the Directives Stack
TestProgram can be started without involving directive files.
java TestProgram
TestProgram starts without any directives file specified.
The default directive is always at the bottom of the directives stack. Figure 2-1 shows the default directive as Directive 0. When you don’t specify a directives file, then the default directive is also the top directive and receives priority.
Figure 2-1 Starting a Program Without Directives

TestProgram:
File_A.json to the directives stack:
java -XX:+UnlockDiagnosticVMOptions -XX:CompilerDirectivesFile=File_A.json TestProgram
Directives are added to the stack in the reverse order they’re written. The top-most directive in the file becomes the top-most directive on the stack.
Figure 2-2 shows that the order of directives in the stack, from top to bottom, becomes: [1, 2, 0].
Figure 2-2 Starting a Program with Directives

Additions to the Directives Stack
TestProgram is running, then you must supply additional directives through diagnostic commands:
File_B to the directives stack:
jcmd 11084 Compiler.directives_add File_B.json
Directive 3 is added to the top of the stack. This is the only directive found in File_B.
Figure 2-3 shows that the order of directives in the stack becomes: [3, 1, 2, 0].
Figure 2-3 Adding a Directive to a Running Program

TestProgram continues running:
File_C to the directives stack.
jcmd 11084 Compiler.directives_add File_C.json
Figure 2-4 shows that the order of directives in the stack becomes: [4, 5, 3, 1, 2, 0].
Figure 2-4 Adding Many Directives to a Running Program

Removals from the Directives Stack
Directive 4 from the stack:
jcmd 11084 Compiler.directives_remove
Top directives are removable one at a time by repeating this diagnostic command until only the default directive remains. You can’t remove the default directive.
Figure 2-5 shows that the order of directives in the stack becomes: [5, 3, 1, 2, 0].
Figure 2-5 Removing One Directive from the Stack

jcmd 11084 Compiler.directives_clear
All directives are removed at one time except the default directive. You can’t remove the default directive.
Figure 2-6 shows that only Directive 0 remains in the stack.
Figure 2-6 Removing All Directives from the Stack
