Search/Navigation:
Related:
SLAC/EPP/HPS Public
Jefferson Lab/Hall B/HPS Run Wiki
S30XL-LESA/LDMX
The HPS Java Project is based on the org.lcsim framework and provides a full set of physics reconstruction and simulation tools compatible with the LCIO data format.
Assuming you have internet access and the right command line tools installed already, this should do it.
cd /my/work/dir svn checkout svn://svn.freehep.org/hps/java/trunk hps-java-trunk cd hps-java-trunk mvn install -DskipTests java -jar distribution/target/hps-distribution-[VERSION]-bin.jar
The last command will check that the distribution was installed correctly.
That's it! If you need help installing the build tools, then continue reading the next section.
Before beginning the installation process, you will want to have available the following tools on your machine first.
Being Java software, the project is cross-platform and should run on Linux, OSX and Windows.
The setup instructions assume a Unix-like environment using the bash shell. Windows users should be able to execute the equivalent commands on their system to perform the installation successfully.
Java on your system
If you are using a shared Unix environment or a machine that is centrally managed, you will want to check first with your system administrator about installing Java so you don't have a redundant installation. They may want to manage the Java installations, or (probably) the JDK is already installed and available for you to use without needing to install it yourself.
The software is currently compatible with Java versions 1.7 and greater. It will not currently build with Java 1.6 or other earlier versions. You need to download the "Java Platform (JDK)" and not just the JRE. It should work with Java 1.8 releases.
The bundle for your system should be downloaded from the Java SE downloads site. Then you need to follow the setup instructions listed there.
You may want to add lines like the following to your shell initialization script, especially if Java is not installed in a standard system location like the /usr directory.
export JAVA_HOME=/path/to/java/jdk export PATH=$JAVA_HOME/bin:$PATH
This will make sure that the shell can find the Java commands such as java and javac that will be needed for the installation.
There have been problems when using the OpenJDK distribution of java to compile HPS Java. Therefore, make sure that the distribution of java is Oracle's version.
Once the Java installation is completed, you should make sure that the compiler is available from the command line.
[$] javac -version javac 1.7.0_17
If this command prints "command not found", the current PATH variable probably does not contain the Java bin directory or the location was set incorrectly.
Java on OSX
On OSX, the Java configuration found by Maven can sometimes conflict with what is shown by the 'java -version' from the command line. In particular, the Java version that comes bundled with the operating system might be 1.6 when a 1.7 JDK is required to build HPS software.
In order to fix this, setup the JAVA_HOME variable as follows:
export JAVA_HOME=$(/usr/libexec/java_home -
v
1.7)
Of course, a valid Java 1.7 JDK installation must be present for this to work. You can get the latest version from here.
Simply install the DMG file as normal, and then setting up your environment as above should configure your machine successfully for Maven usage.
Maven is a Java based build tool used to create a runnable version of HPS Java on your machine.
You will need to get Maven from the Maven Download Site and save (for instance) the tar.gz file to your machine.
Then you can set it up as follows.
tar -zxvf apache-maven-3.2.3-bin.tar.gz export MAVEN_HOME=$PWD/apache-maven-3.2.3 export PATH=$MAVEN_HOME/bin:$PATH
Now you should check that the mvn command works.
[$] mvn -version Apache Maven 3.2.3 [etc.]
If this command does not work, then you should check that the PATH variable is set correctly.
Subversion on your system
Subversion is a common tool on Unix systems, and it is likely already installed for you to use. If not, then check with your system administrator about installing it.
Subversion is the source control system system used to obtain the source code from a remote server. You will need the Subversion client tool in order to checkout the HPS Java code.
Subversion should not be compiled from source code. It is probably best to either have your local administrator install it if it is not present already, or you can use your package manager (like yum on Redhat systems).
This is an example of using your package manage to do this.
yum install subversion
Windows users can install the TortoiseSVN tool, but its usage is not covered in these instructions.
The Subversion client is a complex command line tool with many sub-commands and options. You may want to study detailed documentation such as The SVN Book in order to familiarize yourself with it.
First, you are going to want to create some kind of work directory so that everything can be kept organized.
mkdir /work/hps cd /work/hps
You will now use the svn command to checkout the trunk, or main development branch, of the HPS Java Project.
svn checkout svn://svn.freehep.org/hps/java/trunk hps-java-trunk
This may take awhile as the source code is downloaded from the server.
The Maven tool is used to build all of the modules and produce the jar file used to run command line jobs.
From the hps_trunk directory, you can execute the following command to build the project.
mvn -DskipTests
Especially the first time this is done, it may take quite a long time to bootstrap Maven.
Maven downloads a lot of jar dependencies by default into your home directory in ~/.m2/repo but if you do not have space there this can be changed using a flag.
mvn -Dmaven.repo.local=/path/to/my/repo
At JLab, you might want to use a directory on the work disk for the repo so your home directory does not get filled up.
The list of available modules is available from the Project Modules Webpage on the HPS Java site generated by Maven.
To build a single module, assuming you already have a local copy of the SVN trunk, you just need to go to its sub-directory and type the appropriate Maven command.
For instance, this command will build the tracking reconstruction module.
cd hps-java-trunk/tracking mvn -DskipTests
This will install that module's jar into your local Maven repository. In order to include these changes in the distribution jar, you also need to build the distribution module, also.
cd hps-java-trunk/distribution mvn
The primary tool produced by the installation is a standalone, runnable jar file that can be used along with XML steering files to run reconstruction jobs.
In order to test the installation, you may execute a command such as the following where VERSION is replaced by your actual version from the last successful build.
java -jar ./distribution/target/hps-distribution-[VERSION]-bin.jar
The Maven tool will also install this file into your local repository. This is an example of running the bin jar from your local repository.
java -jar ~/.m2/repository/org/hps/hps-distribution/3.0.3-SNAPSHOT/hps-distribution-3.0.3-SNAPSHOT-bin.jar
The output of these commands will be something like this.
java -jar lcsim-bin.jar [options] steeringFile.xml usage: -D Define a variable with form [name]=[value] -b Run in headless mode in which plots will not be shown. -i Add an LCIO input file to process -n Set the max number of events to process -p Load a properties file containing variable definitions -q Turn on quiet mode -r Use a steering resource rather than a file -s Set the number of events to skip -v Turn on verbose mode -w Rewrite the XML file with variables resolved -x Perform a dry run which does not process events
Actually running steering files using this tool is covered elsewhere.
Congratulations! You now have a working local installation of HPS Java.
As an alternative to the above instructions for building the software locally, you may also download and run the distribution jars from a Nexus repository.
This search URL will show all the available versions of the distribution jar that can be downloaded.
You can also get the latest version from Nexus at http://srs.slac.stanford.edu/nexus/index.html#nexus-search;quick~hps-distribution
Now you can simply click on the "bin jar" link for the distribution version you want to download, save it to your machine, and run it using the previous instructions.
HPS Java is publicly accessible as a read only download from the server. But valid credentials must be supplied in order to commit your local source code changes to the repository.
Requesting a Subversion Account
In order to request a username and password for the Subversion repository, please email <hps-software AT slac.stanford.edu> indicating your full name, desired username, and institutional affiliation.
To commit changes, the username and password must be supplied, or the command will fail:
svn commit --username [username] --password [password] -m "commit message goes here" the/file/to/commit
After the username and password have been supplied once, they can be cached automatically in the directory ~/.subversion if you select 'Y' when prompted whether to store them (unencrypted unfortunately!). Then these two arguments can be omitted from subsequent commit commands.
Maven is able to resolve project dependencies by downloading jar files from remote repositories. In order to do this, it must know about the locations of these jars, or local builds can fail with errors about missing dependencies.
This should not be a problem when building the entire trunk But errors may occur when building individual modules, if the parent POM has not already been installed locally beforehand.
There are several different ways to resolve these kinds of issues, and generally only one will be needed:
The third option entails adding the remote repository information to a local settings file that will apply to all your local Maven builds.
In order to do this, the following XML can be put into the file ~/.m2/settings.xml which you should create if it does not exist already:
<?xml version="1.0"?> <settings> <profiles> <profile> <id>yourNameHere</id> <activation> <activeByDefault>true</activeByDefault> </activation> <repositories> <repository> <id>lcsim-maven</id> <name>org.lcsim Maven Repository</name> <url>http://srs.slac.stanford.edu/nexus/content/groups/lcsim-maven2-public/</url> </repository> </repositories> </profile> </profiles> </settings>
The above configuration will allow Maven to check the repository used by HPS whenever it looks for dependencies during a build.