= Running the Compiler =
[[TracNav]]
[[TOC(inline)]]

== Command Line ==

The compiler can be invoked from the command line by using "panc".  This is a script that is installed with the pan compiler package that invokes a java virtual machine and the compiler.  The script options have been designed to be as compatible with previous versions of the "panc" command as possible.

The full list of options can be obtained with the "--help" option.

== Ant Task ==

Using an ant task to invoke the compiler allows the compiler to be easily integrated with other machine management tasks.  To use the pan compiler within an ant build file, the pan compiler task must be defined.  This can be done with a task like:
{{{
<target name="define.panc.task">

	<taskdef resource="org/quattor/ant/panc-ant.xml">
		<classpath>
			<pathelement path="${panc.jar}" />
		</classpath>
	</taskdef>

</target>
}}}
where the property {{{${panc.jar}}}} points to the jar file panc.jar distributed with the pan compiler release.

Running the compiler can be done with a task like the following:
{{{
<target name="compile.cluster.profiles">

	<!-- Define the load path.  By default this is just the cluster area. -->
	<path id="pan.loadpath">
		<dirset dir="${basedir}" includes="**/*" />
	</path>

	<panc ...options... >
		<path refid="pan.loadpath" />
		<fileset dir="${basedir}/profiles" casesensitive="yes" includes="*.tpl" />
	</panc>

</target>
}}}
where {{{...options...}}} is replaced with valid options for the panc ant task.  The full set of options can be found by looking at the javadoc information for the "org.quattor.pan.ant.PanCompilerTask" class in the javadoc distributed with the release.

== Java Virtual Machine Parameters ==

The performance of the compiler can degrade markedly if there is not sufficient memory to do a particular compile and build.  Moreover, the default memory allocation and vary wildly depending on how and when the compiler is invoked.  Similarly, there are other options that may improve the performance of the compiler.  For instance, it is usually advisable to use the "-server" option.

=== Direct Invocation via Java ===

If the java compiler class is being directly invoked via the {{{java}}} command, then the option "-Xmx" must be added to change the VM memory available.  For example to start java with 1024 MB, the following command and options can be used:
{{{
java -Xmx1024M org.quattor.pan.Compiler [options...]
}}}
For the panc command, currently the panc script must be edited to add this option.  The same must be done for other options.

=== Direct Invocation via Ant ===

If the compiler is invoked via the panc ant task, then the memory option can be added with the ANT_OPTS environmental variable.
{{{
export ANT_OPTS="-Xmx1024M"
}}}
or 
{{{
setenv ANT_OPTS "-Xmx1024M"
}}}
depending on whether you use an "sh"- or "csh"-type shell.  Other options can be similarly added to the environmental variable.  (The value is a space-separated list.)

=== Invocation via Eclipse ===

If you use the default VM to run the panc ant task, then you will need to increase the memory when starting eclipse.  From the command line you can add the VM arguments like:
{{{
eclipse -vmargs -Xmx<memory size>
}}}
You may also need to increase the memory in the "permanent" generation for a Sun VM with
{{{
eclipse -vmargs -XX:MaxPermSize=<memory size>
}}}
This will increase the memory available to eclipse and to all tasks using the default virtual machine.  For Max OS X, you will have to edit the application "ini" file.  See the  [http://help.eclipse.org/help32/index.jsp?topic=/org.eclipse.platform.doc.user/tasks/running_eclipse.htm eclipse instructions] for how to do this.

If you invoke a new java virtual machine for each build, then you can change the ant arguments via the run parameters.  From within the "ant" view, right-click on the appropriate ant build file, and then select "Run As -> Ant Build...".  In the pop-up window, select the JRE tab.  In the "VM arguments" panel, add the "-Xmx<memory size>" option without the quotes.  (You can also add other options here.)  The next build will use these options.

Other VM options can be changed in the same way.

The options can also be set using the "Window -> Preferences -> Java -> Installed JREs" panel. Select the JRE you want use, click edit and add the additional parameters in the "DefaultVM arguments" field.

== Enabling Logging ==
From version 8, panc provides extensive logging facilities. These may be activated using the following options:

{{{
 --logging=string
           Enable compiler logging; possible values are "all", "none", "include", "call", "task", and "memory". A log file must be specified with the --logfile option to capture the logging information.

 --logfile=file
           Set the name of the file to use to store logging information.
}}}

panc also includes scripts for interpreting logging information. These are documented [wiki:Doc/compiler/results#UsingLoggingInformation here].