Most of the information on this page is now out of date, as it refers to the old Maven 1 build system. The lcsim projects have been ported to use Maven 2 instead.
To build the org.lcsim software, you should have the following installed.
- Java 1.5 or 1.6
- Maven 2.0.9
- Netbeans 6.5
- CVS client such as command-line on Linux, Tortoise CVS, or just use the Netbeans cvs client
If you are following the lcsim tutorial instructions, these tools should be setup by now.
Building org.lcsim software
The lcsim software consists of three primary packages: GeomConverter, org.lcsim, and lcsim-contrib.
Most users will be primarily interested in building and running lcsim and/or lcsim-contrib.
Here are condensed instructions, which you can execute from any bash-like unix shell.
export CVSROOT=:pserver:firstname.lastname@example.org:/cvs/lcd cvs login (just hit enter when prompted for password) cvs co lcsim cd lcsim mvn
The build procedure for lcsim-contrib is virtually the same. Just replace "lcsim" in the above instructions by "lcsim-contrib".
Keeping the Release Current
Oftentimes new directories are added in a new release. In order
to make sure that cvs adds those, please use the command
cvs update -PdA
P: prune empty directories
d: create directories
A: reset sticky tags
will give more information on the cvs program.
Installing Custom JARs into JAS3
By default, your lcsim and lcsim-contrib builds install their current jar files into ~/.JAS3/extensions.
Edit the pom.xml file to turn off this behavior.
Testing the installation
By default, maven will also run the JUnit tests associated with this distribution.
Test reports are written to
If you wish to build without testing, issue the following command:
To execute a single test case, e.g. for org.lcsim.recon.cluster.fixedcone.FixedConeClusterer:
maven test:single -Dtestcase=org.lcsim.recon.cluster.fixedcone.FixedConeClustererTest
Additional Component Tests
There are also other component tests for many of the org.lcsim classes. Until they can be ported
to the JUnit structure they need to be manually executed. Do so with the following ant target:
ant -f ctest.xml
Running Classes from the Command Line
We have defined a Maven goal that allows users to run a Java class in the project from the command line
using the freehep-run-plugin.
maven run -Drun.class="org.lcsim.geometry.compact.converter.heprep.Main" -Dargs="test/org/lcsim/geometry/compact/sdjan03_compact.xml tst.heprep"
The above command run the Main class to convert the given compact description to a HepRep.
By default, compiler warnings about deprecation and unchecked method or class usages are turned off.
To turn on these warnings, remove the "#" from these two lines in lcsim/project.properties
Now you should see lots of warning messages, which will effect both Netbeans and command-line builds.
To customize Netbeans, only, you can change how the Netbeans Build Mapping works.
Right-click on the org.lcsim project and select "Properties". Now double-click on "Goal to IDE Mappings". Where it says "Build", you should see "jar:install".
To see all warnings, change the Build line to this:
jar:install -Dmaven.compile.deprecation=on -Dmaven.compile.compilerargs=-Xlint:unchecked
This should have the same effect as changing the project.properties file, but command-line builds using maven only will unaffected.
Building the Documentation
Generating the documentation with maven is quite easy. Just execute this command.
This builds the site at the location ./target/docs. You can use this site for local documentation by browsing to ./target/docs/index.html.
The reference copy of the lcsim documentation is kept at http://www.lcsim.org/software/lcsim. This usually corresponds to the CVS head version.
Increasing the Java Heap and Perm Size
The LCSim tests can take up more memory than the default heap/perm size assigned to the java VM.
Use this environment variable setting to allocate more memory, i.e. 1 gigabyte heap / 256 megabyte perm, to maven.
If you are building the lcsim documentation, including running all the tests, you are required to increase the heap size beyond the initial default of 256 megabytes. Otherwise, the target will fail due to an "out of memory" error.
I have still some gripes with the maven setup.
a) It downloads files into the users home directory. The files are just too big. period.
b) Testing is nice before a release, but the current setup is completely unusable. Besides taking forever, the current tests take way too many resources (both cpu and memory). This needs to be fixed. Otherwise I would suggest having maven.test.skip=true added by default.
a) Are you really refering to Maven, or to the data files downloaded by the lcsim test procedures. At least one of these test files is 35MB and I already created a bug report to fix it LCSIM-18@jira. For maven you can already move the repository by creating a ~/build.properties file and including a defintion of maven.home.local (see http://maven.apache.org/reference/properties.html). For the lcsim test files it is hardwired right now, but I will fix it LCSIM-21@jira.
b) Several issues, first I think we should not disable all tests, but probably we should split them into "fast" tests and "extended" tests. It currently takes 90 seconds to build on windows for me, which seems annoyingly long if you are doing frequent builds, but not a big deal if you are just downloading and building the jar. Of course you can turn off the tests when doing frequent builds. The memory usage does seem excessive, and I dont understand it. I tried to track it down once, but didnt succeed, I will look some more.
Thank you, Tony.
It is good to have these options documented here now.
as to b) I am OK with the tests taking some time, but the memory use leads to my machine becoming unresponsive for the duration of the tests, which is simply not acceptible.
Thanks for looking into this.
Unknown User (ebenavid)
Before I forget to mention this, mevenide on Linux does not work if it is not installed globally. Linux users of NetBeans should run NetBeans as user root, install the autoupdate module globally (in one step of installation toward the end, check the "Global" as well as the "Include" checkbox). Then, go to Tools -> Update Center and install everything from the Mevenide Update Server, remembering to check the "Global" as well as the "Include" checkboxes toward the end of installation.
In essence, Linux users should install mevenide globally.
Maven beta 1.1 is pretty broken on my Windows laptop. I am going to try using 1.0.2, instead.
It is constantly spewing bizaare error messages, like the following.
File...... C:\Documents and Settings\jeremym\.maven\cache\maven-artifact-plugin-1.5.2\plugin.jelly
Then it randomly fails to execute targets such as "jas:install", but "jar:install" seems to work okay.
I don't get either of these problems when using 1.0.2 on Linux with Netbeans 4.0 .
Unfortunately, the Maven site has this buggy "Test" version as the most obvious link on their download page, so it is easy to get somewhat confused.
Unknown User (jgill)
I'm using Maven 1.0.2 on linux without Netbeans. The build for GeomConverter works fine, but the build for lcsim fails, similar to the problem Jeremy was having:
There were test failures.
Total time: 2 minutes 7 seconds
Finished at: Tue Aug 23 13:15:36 MDT 2005
I'm not sure if this is related to not having Netbeans or not.
Hi Jack, this output shows that one of the tests failed. You need to look a bit higher in the log to see which test failed, you should then be able to click on the link for the failed test, and it should show the full information about the problem. If you can post the details we should be able to help further.
Unknown User (jgill)
I looked in the log, and found this output:
junit Running org.lcsim.conditions.ConditionsManagerTest
junit Tests run: 1, Failures: 0, Errors: 0, Time elapsed: 17.761 sec
junit Running org.lcsim.digisim.DigiSimTest
junit Tests run: 1, Failures: 0, Errors: 1, Time elapsed: 0.34 sec
junit ERROR TEST org.lcsim.digisim.DigiSimTest FAILED
So it looks like the DigiSimTest failed. Any ideas?
In Netbeans I think the underlined ERROR is effectively a hyperlink. If you click on that it will give you the full traceback of the error.
Unknown User (jgill)
I'm not using Netbeans...all this is STDOUT, no links. I looked for the file DigiSimTest in the lcsim src directory, but the file was not present.
Unknown User (jgill)
Tony, it looks like a few recent cvs updates fixed the problem. Thanks for your attention though.
I'm having a problem with the ant stuff...
ant -f ctest.xml
echo Running the component tests in "/home/jstrube/Workspace/lcsim"
mkdir Created dir: /home/jstrube/Workspace/lcsim/ctests
java Could not find ctbuild.CTest. Make sure you have it in your classpath
java at org.apache.tools.ant.taskdefs.ExecuteJava.execute(ExecuteJava.java:166)
java at org.apache.tools.ant.taskdefs.Java.run(Java.java:705)
java at org.apache.tools.ant.taskdefs.Java.executeJava(Java.java:177)
java at org.apache.tools.ant.taskdefs.Java.execute(Java.java:83)
java at org.apache.tools.ant.UnknownElement.execute(UnknownElement.java:275)
java at org.apache.tools.ant.Task.perform(Task.java:364)
java at org.apache.tools.ant.Target.execute(Target.java:341)
java at org.apache.tools.ant.Target.performTasks(Target.java:369)
java at org.apache.tools.ant.Project.executeTarget(Project.java:1214)
java at org.apache.tools.ant.Project.executeTargets(Project.java:1062)
java at org.apache.tools.ant.Main.runBuild(Main.java:673)
java at org.apache.tools.ant.Main.startAnt(Main.java:188)
java at org.apache.tools.ant.launch.Launcher.run(Launcher.java:196)
java at org.apache.tools.ant.launch.Launcher.main(Launcher.java:55)
Total time: 0 seconds
Unknown User (proulx)
A question about building specific org.lcsim packages with maven:
I notice that the project.xml file in lcsim contains tags excluding some directories; in particular, org/lcsim/contrib. To turn my packages on, I have changed the line:
(but not excluding my directory)
Is there a less clunky way to do this; i.e, some command-line argument to maven?
I saw that you added this, Joe.
You can change the compile options using these properties.
I think the property
can be used to modify the settings from project.xml, but I don't know exactly how.