Commit in projects/lcsim/trunk/site on MAIN | |||
TODO | +31 | added 2855 | |
src/site/apt/build.apt | +216 | added 2855 | |
/intro.apt | +12 | added 2855 | |
/maven-repo.apt | +30 | added 2855 | |
/source-code.apt | +103 | added 2855 | |
/users.apt | +15 | added 2855 | |
src/site/site.xml | +30 | added 2855 | |
+437 |
commit website content so can work locally on laptop
--- projects/lcsim/trunk/site/TODO (rev 0) +++ projects/lcsim/trunk/site/TODO 2013-12-14 22:02:58 UTC (rev 2855) @@ -0,0 +1,31 @@
+X Maven build instructions + +X top level descriptive paragraph of lcsim (get more from Norman) + +X list of users (SiD, CLiC, etc.) + +X lcsim Maven repository information + +explanation of Maven module structure + +software license + +news + +publications + +coding standards + +Eclipse instructions + +Netbeans instructions + +links e.g. to Confluence etc + +instructions on running the software on the grid; should mostly be links to ILCDIRAC documentation + +steering file usage; can point to the lcsim xml documentation page + +---------------------------------------------------- + +see freehep/trunk/site/src/site/apt/*.apt for examples and java.freehep.org for the output
--- projects/lcsim/trunk/site/src/site/apt/build.apt (rev 0) +++ projects/lcsim/trunk/site/src/site/apt/build.apt 2013-12-14 22:02:58 UTC (rev 2855) @@ -0,0 +1,216 @@
+ --- +LCSim - Build Instructions + --- + +Build Instructions + +* Prerequisites + + The following tools are required for building HPS Java software: + + * {{{http://subversion.tigris.org/}Subversion}} + + This is the revision control system used by the experiment. + Unix and OSX machines should have this installed by default. + Windows users can install TortoiseSVN or the SVN command line tool. + + * {{{http://www.oracle.com/technetwork/java/javase/downloads/index.html}Java}} + + A valid JDK 1.7 installation is required for building and running the software. + The commands java and javac must both work from the command line. + + * {{{http://maven.apache.org/}Maven}} + + This is the build tool used to create a local installation of the Java software. + Any 3.x.x version should work fine. + + [] + + Should any of these tools be missing on your system, you need to install them before proceeding with the build instructions. + + The following are optional IDE applications, either of which will be very useful for developing Java code: + + * {{{http://eclipse.org/}Eclipse}} + + This is the most popular Java IDE and has a wide range of plugins available for various other languages and purposes. + + * {{{https://netbeans.org/}Netbeans}} + + This development tool is supported by Oracle and comes with built-in Maven support. + + [] + + The instructions below which involve command line input assume a bash shell on Unix but those which don't involve Unix-specific + utilities will also work from a Windows command prompt. + +* Downloading + + The {{{./source-code.html}source code instructions}} should be followed to obtain the project code. + +* Maven Overview + + LCSim projects are built using the Maven project management tool. It provides facilities for compiling Java source code, + as well as downloading a project's dependencies from remote repositories, among other {{{http://maven.apache.org/maven-features.html}features}}. + +* Installing Maven + + The command line 'mvn' tool can be installed by getting the latest release from the {{{http://maven.apache.org/download.cgi}download area}}. + + Or you may fetch it directly from the command, e.g. using a wget command such as: + ++-- +wget http://mirror.cc.columbia.edu/pub/software/apache/maven/maven-3/3.1.1/binaries/apache-maven-3.1.1-bin.tar.gz ++-- + + Once downloaded, untar the file into a directory on your system where you install local software: + ++-- +tar -zxvf apache-maven-3.1.1-bin.tar.gz ++-- + + Now all that needs to be done is setting up your environment to find the command line tool: + ++-- +cd apache-maven-3.1.1/ +export MAVEN_HOME=$(pwd) +export PATH=$MAVEN_HOME/bin:$PATH ++-- + + Finally, check that the command line client is accessible in your shell: + ++-- +mvn -version ++-- + + This should print out the local configuration starting with a line like: + ++-- +Apache Maven 3.1.1 ++-- + + Now you are ready to build LCSim on your system. + +* IDE Support + + Both Netbeans and Eclipse support Maven builds. + + Netbeans comes with built-in support and will automatically detect if your project has a POM file in it. + + For Eclipse, install the {{{http://www.eclipse.org/m2e/}m2e}} plugin and then enable it for a given project + by right-clicking on it in the "Project Explorer" pane and selecting <Configure \> Convert to Maven Project>. + +* Installing a Module + + The default target of most modules is "install" which will compile, package and copy the artifacts + into the local Maven repository on your machine. This can be done using either of the following commands + from a system shell, assuming that your current working directory is the module's root directory containing + the pom.xml file: + ++-- +mvn +mvn install ++-- + + After the build completes successfully, the artifact for the project, usually a jar file containing compiled Java classfiles, + will show up in the target directory with the form: + ++-- +target/${artifactId}-${version}.jar ++-- + + For instance, suppose you have compiled a local copy of the tracking module, then its artifact will show up at: + ++-- +target/lcsim-tracking-3.0-SNAPSHOT.jar ++-- + + This jar would also be installed into your local Maven repository here: + ++-- +~/.m2/repository/org/lcsim/lcsim-tracking/3.0-SNAPSHOT/lcsim-tracking-3.0-SNAPSHOT.jar ++-- + + There it will be accessible to other Maven projects as a dependency. + +* Running Tests + + Some modules come with unit and integration tests, which run by default. + + To skip these tests, the following command can be used: + ++-- +mvn -DskipTests=true ++-- + + Tests can be executed individually using the following syntax: + ++-- +mvn test -Dtest=[TestCaseName] ++-- + + For instance, suppose you are in the detector-framework module. The test <org.lcsim.geometry.GeometryReaderTest> could + be executed as follows: + ++-- +mvn test -Dtest=GeometryReaderTest ++-- + + The package name is not used here, so it will always be a good idea to make the class names of tests unique within a + given module. + +* Resolving Dependencies + + Maven can resolve project dependencies by downloading jar files from remote repositories. But in order to do this, it must know + about the locations of the repositories where these jars are available. When required artifacts are not avaiable either locally or + remotely, it can fail with errors about missing dependencies. + + When building all the modules together from the top project directory, this is unlikely to be an issue. However, errors can occur + when building individual modules, if the parent POM files have not already been installed locally beforehand. + + There are several ways to deal with these kinds of issues: + + [[1]] Install the parent POM files. + + The modules site-parent and parent can be checked out individually and built using the standard build commands. This should allow + other projects to find the external jar on which they depend. + + [[2]] Install the entire project. + + If you install all modules by building from the top level directory in the SVN, then all necessary parent POM files will be put + into your local repository for other modules to use for resolving their dependencies. + + [[3]] Add the LCSim remote repository to your Maven settings. + + Repositories may also be added to a file at <~/.m2/settings.xml> which you may create if it does not already exist. The following + text should be used: + ++-- +<?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> ++-- + + This will allow the LCSim repository to be used by all projects for resolving their dependencies. + + [] + +* Distribution Module + + TODO + +
\ No newline at end of file
--- projects/lcsim/trunk/site/src/site/apt/intro.apt (rev 0) +++ projects/lcsim/trunk/site/src/site/apt/intro.apt 2013-12-14 22:02:58 UTC (rev 2855) @@ -0,0 +1,12 @@
+ --- +LCSim - Introduction + --- + +Introduction + + LCSim, standing for "Linear Collider Simulation", is a Java-based framework for physics + event reconstruction and analysis. It uses the {{{lcio.desy.de}LCIO}} event model, + the {{{aida.freehep.org}AIDA}} histogramming and plotting API, and also makes use of + the {{{jas.freehep.org}JAS}} (or Java Analysis Studio) GUI which includes the + {{{wired.freehep.org}Wired Event Display}}. LCSim also makes extensive use of the + {{{java.freehep.org}FreeHEP Java Libraries}}.
\ No newline at end of file
--- projects/lcsim/trunk/site/src/site/apt/maven-repo.apt (rev 0) +++ projects/lcsim/trunk/site/src/site/apt/maven-repo.apt 2013-12-14 22:02:58 UTC (rev 2855) @@ -0,0 +1,30 @@
+ --- +LCSim - Maven Repository + --- + +Maven Repository + + LCSim module artifacts such as jar files are deployed to a remote repository where they are + publically available for download, either manually or via a dependency in a POM file. + +* Repository Information + + The following information can be put into the repositories section of your Maven project: + ++-- +<repository> + <id>lcsim-repo-public</id> + <name>LCSIM Public Maven Repository</name> + <url>http://srs.slac.stanford.edu/nexus/content/groups/lcsim-maven2-public/</url> +</repository> ++-- + + Both releases and snapshots are available through that URL, so this should be the only + configuration that is required. + +* Nexus + + The {{{http://www.sonatype.org/nexus/}Sonatype Nexus}} application is used to manage the repository. + + To search for jars, go to the {{{http://srs.slac.stanford.edu/nexus/index.html}SLAC SRS Nexus Application}} and + enter "lcsim" in the "Keyword Search" box, which will show the artifacts that are available.
\ No newline at end of file
--- projects/lcsim/trunk/site/src/site/apt/source-code.apt (rev 0) +++ projects/lcsim/trunk/site/src/site/apt/source-code.apt 2013-12-14 22:02:58 UTC (rev 2855) @@ -0,0 +1,103 @@
+ --- +LCSim - Source Code + --- + +Source Code + +* Check Out the Code + + The full project sources are stored in a Subversion repository at the following location: + ++-- +svn://svn.freehep.org/lcdet/ ++-- + +* Repository Credentials + + The project sources can be downloaded anonymously, but checking in changes to the SVN requires a valid username and password combination. + + These should be supplied when executing the 'commit' command: + ++-- +svn commit --username [username] --password [password] -m "commit message goes here" the/file/to/commit ++-- + + Generally, this will only need to be done once, as you may allow Subversion to cache this information locally (unencrypted unfortunately!). + + Repository write access can be requested by emailing jeremym AT slac.stanford.edu and including your full name, institution, and desired username. + +* Getting All the Modules + + The entire set of modules can be found under this directory: + ++-- +svn://svn.freehep.org/lcdet/projects/lcsim/trunk/ ++-- + + This command will checkout all of the modules locally: + ++-- +svn co svn://svn.freehep.org/lcdet/projects/lcsim/trunk/ lcsim ++-- + +* Getting a Single Module + + The HEAD revision of an individual module can be found at a URL with the following form: + ++-- +svn://svn.freehep.org/lcdet/projects/lcsim/trunk/[module] ++-- + + To see a list of available modules, e.g. directories containing Maven modules, the following + command can be used: + ++-- +svn list svn://svn.freehep.org/lcdet/projects/lcsim/trunk/ ++-- + + For instance, to checkout the HEAD copy of the tracking module, this command can be used: + ++-- +svn co svn://svn.freehep.org/lcdet/projects/lcsim/trunk/tracking lcsim-tracking ++-- + +* Downloading Tags and Branches + + Global tag names are used, and Maven generates these automatically for releases. + + All tags can be found at this URL: + ++-- +svn://svn.freehep.org/lcdet/projects/lcsim/tags ++-- + + To download a certain tag, use a command with this form: + ++-- +svn co svn://svn.freehep.org/lcdet/projects/lcsim/tags/[tagName] ++-- + + To see what tags are available, use this command: + ++-- +svn list svn://svn.freehep.org/lcdet/projects/lcsim/tags/ ++-- + + Similarily, branch names also have globally unique names, and all branches can be found here: + ++-- +svn://svn.freehep.org/lcdet/projects/lcsim/branches ++-- + + To download a certain branch, use a command with this form: + ++-- +svn co svn://svn.freehep.org/lcdet/projects/lcsim/tags/[branchName] ++-- + + To see what branches are available, use this command: + ++-- +svn list svn://svn.freehep.org/lcdet/projects/lcsim/branches/ ++-- +
\ No newline at end of file
--- projects/lcsim/trunk/site/src/site/apt/users.apt (rev 0) +++ projects/lcsim/trunk/site/src/site/apt/users.apt 2013-12-14 22:02:58 UTC (rev 2855) @@ -0,0 +1,15 @@
+ --- +LCSim - Users + --- + +Users + + The following groups are users of the LCSim framework: + + * {{{http://silicondetector.org/}Silicon Detector (SiD) Collaboration}} + + * {{{http://lcd.web.cern.ch/LCD/}CERN Linear Collider Detector Project}} + + * {{{https://confluence.slac.stanford.edu/display/MCPDS/Home}Muon Collider Detector}} + + * {{{https://confluence.slac.stanford.edu/display/hpsg/Heavy+Photon+Search+Experiment}Heavy Photon Search Experiment}}
\ No newline at end of file
--- projects/lcsim/trunk/site/src/site/site.xml (rev 0) +++ projects/lcsim/trunk/site/src/site/site.xml 2013-12-14 22:02:58 UTC (rev 2855) @@ -0,0 +1,30 @@
+<?xml version="1.0" encoding="ISO-8859-1"?> +<project name="LCSim Project Homepage"> + + <body> + + <menu name="General"> + <item name="Introduction" href="intro.html"/> + <item name="Users" href="users.html"/> + <item name="Team" href="team-list.html"/> + <item name="Mailing List" href="mail-lists.html"/> + </menu> + + <menu name="For Users"> + <item name="Bugs and Issues" href="issue-tracking.html"/> + </menu> + + <menu name="For Developers"> + <item name="Getting the Source Code" href="source-code.html"/> + <item name="Building the Software" href="build.html"/> + <item name="LCSim Maven Repository" href="maven-repo.html"/> + <item name="Continuous Integration" href="integration.html"/> + </menu> + +<!-- + <menu ref="reports"/> +--> + + </body> + +</project>
Use REPLY-ALL to reply to list
To unsubscribe from the LCDET-SVN list, click the following link:
https://listserv.slac.stanford.edu/cgi-bin/wa?SUBED1=LCDET-SVN&A=1