Introduction

XAL is the open source development environment used for creating accelerator physics applications, scripts and services for the Spallation Neutron Source. This page describes how to install and configure XAL for development from the command line. Note that almost any integrated development environment (e.g. Xcode, JEdit, Eclipse, Netbeans) can be used to manage the XAL project including source control, building, running and debugging applications. Here we will focus on doing everything from the command line since it provides the foundation for XAL development.

Requirements

1. •Java J2SE 6 with JDK
   

2. •Ant 1.7
   

3. •Subversion 1.6 or later
   

Steps to prepare for XAL development

1. 1.Become familiar with UNIX and shell scripting: Shell Scripting Primer
   

2. 2.While not required, it is recommended that you install and configure EPICS Channel Access binaries and resources (a convenient installer for Mac OS X users is provided). If you don’t install the native channel access libraries, you can still communicate with channel access using the pure java channel access library which is not recommended for production use as it has suspected compatibility issues which may result in IOC crashes.
   

3. 3.Install jruby and jython scripting executables in /usr/local/bin
   

Checkout XAL Source Code from the Source Forge repository

1. 1.You need to have a Source Forge account to access the source code
   

2. 2.Request developer access to the xaldev project (be sure to provide your Source Forge Unix name)
   

3. 3.Checkout the XAL trunk source code to a new directory of your choosing (e.g. xal):
   

   > svn co https://YourID@xaldev.svn.sourceforge.net/svnroot/xaldev/trunk xal

   
   (replacing YourID with your Source Forge Unix name).
   

4. 4.Authenticate using your Source Forge account password if prompted.
   

Obtain and Install Third Party Jars

XAL depends upon several third party jars which are not included in the source code repository (we are in the process of obtaining permission to redistribute them).

1. 1.The file located at ext_jars/README of your new XAL project explains how to obtain all of the required third party jars. Contact me if you need help locating a particular jar file.
   

2. 2.Place the third party jar files in the ext_jars/ folder and be sure to assign them the names as they appear in the README file
   
   

Configure your Shell for XAL

You must configure your environment to build and run XAL. You do so by editing your shell startup file (such as  ~/.bashrc or ~/.profile or whatever shell startup file you use) and inserting the following commands.

1. 1.Export the XAL_HOME environment variable to specify the path to the root of your new XAL project.

   > export XAL_HOME=/my/path/to/xal

   
   
2. 2.Export the CLASSPATH environment variable to point to a couple XAL products.

   > export CLASSPATH=${XAL_HOME}/build/jar/xal.jar:${XAL_HOME}/build/jar/ext.jar

   
   

Building XAL at the Command Line

1. 1.Change directory to the root of the XAL project
   

2. 2.Build the external third party jar files into a single jar file
   

   > ant jar-ext

   
   
3. 3.Build the XAL core
   

   > ant

   
   
4. 4.Build the XAL services
   

   > ant build-services

   
   
5. 5.Build the XAL applications
   

   > ant build-apps

   
   
6. 6.Deploy XAL Scripts
   

   > ant deploy-scripts

   
   

Running a XAL Application

1. 1.Execute a XAL application using java -jar and the application’s jar file path

   > java –jar ${XAL_HOME}/build/jar/apps/demo.jar

   
   to run the demo application (for example).
   

Running a XAL JRuby Script

1. 1.Execute a XAL Jruby script

   > jruby ${XAL_HOME}/build/scripts/orbit_viewer/orbit-viewer.rb

   
   to run the orbit-viewer script (for example).
   

Running a XAL Jython Script

1. 1.Execute a XAL Jython script

   > jython ${XAL_HOME}/build/scripts/scl_waveform_capture/capture_scl_waveforms.py

   
   to run the SCL Waveform Capture script (for example).
   

Configuring Channel Access

1. 1.More configuration is required before you can run XAL applications that communicate with the control system using EPICS Channel Access.
   

2. 2.As noted above in preparing for XAL development, you might want to install EPICS Channel Access client if you would like to use the native libraries (recommended for production), otherwise you can use the pure Java CAJ package which (for convenience) is distributed along with XAL.
   

3. 3.Download and install the JCALibrary.properties file in the following location: ~/.JCALibrary/JCALibrary.properties
   

4. 4.Edit the JCALibrary.properties file to indicate for your platform the path to the EPICS base libraries and the path to the CA Repeater executable if using the native channel access libraries
   

5. 5.If using the native JCA library, in JCALibrary.properties you must list for it the addresses of the channel access servers to use:

   gov.aps.jca.jni.JNIContext.addr_list = some.1.ca.server some.2.ca.server 127.0.0.1

   
   
6. 6.Likewise, if instead you are using the pure Java CAJ library, in JCALibrary.properties you must list for it the addresses of the channel access servers to use:

   com.cosylab.epics.caj.CAJContext.addr_list = some.1.ca.server some.2.ca.server 127.0.0.1

   
   

7. 7.By default, XAL will use the JCA CAJ (pure Java) context, but you can select to use a JCA JNI (native JCA requiring EPICS CA client installation) context instead. You select this JCA back end (the high level API is identical) you want to use by specifying one of the corresponding JCA contexts (either of the first two options are recommended):
   

8. •com.cosylab.epics.caj.CAJContext
   

9. •gov.aps.jca.jni.ThreadSafeContext
   

10. •gov.aps.jca.jni.SingleThreadedContext
    

11. There are several ways you can select whether to use JCA JNI (native JCA) or JCA CAJ (pure Java). You can specify the JCA Context (in order of highest to lowest priority) at the command line, as an environment variable or as a Java user preference.
    

8. 8.To run an XAL application (for example Orbit Correction) using the JCA JNI Thread Safe Context specified at the command line:

   > java -Dgov.sns.jca.Context=gov.aps.jca.jni.ThreadSafeContext -jar ${XAL_HOME}/build/jar/apps/orbitcorrect.jar

   
   
9. 9.To set an environment variable to specify the JCA Context such as CAJ Context:

   > export JCA_CONTEXT=com.cosylab.epics.caj.CAJContext

   
   

10. 10.Specifying a Java user preference for gov.sns.jca.Context is platform specific. Running an XAL application which uses JCA once should automatically create a default preference file that you can then edit as follows:
    

11. •On Mac OS X you edit the ~/Library/Preferences/gov.sns.jca.plist file and specify the Context sub property value of the /gov/sns/jca/ property.
    

12. •On Linux, you edit the ~/.java/.usrPrefs/gov/sns/jca/prefs.xml file and specify the context value for the Context key.
    

Running the Virtual Accelerator

The XAL Virtual Accelerator allows you to simulate the accelerator specified in your optics file. It is useful for initial testing and debugging of your code offline from the real accelerator.

1. 1.Edit your JCALibrary.properties file and set either or both of the CAJ or JNI Context (depending on which one you are using) Address List to point to your local machine. I typically just set both and use the loopback address as demonstrated below:

   gov.aps.jca.jni.JNIContext.addr_list = 127.0.0.1
   

   com.cosylab.epics.caj.CAJContext.addr_list = 127.0.0.1

   
   

2. 2.Launch the Virtual Accelerator application and select an accelerator and a sequence from the Accelerator menu.
   

3. 3.Hit the Start VA button to begin updating the process variables.