perfsonar development work

Author: nordunet.behrmann
Date: 2012-12-21 09:14:49 +0000 (Fri, 21 Dec 2012)
New Revision: 6076

Added:
   trunk/BUILDING.txt
Log:
Added BUILDING.txt

Issue: PSSERVICES-594

Added: trunk/BUILDING.txt
===================================================================
--- trunk/BUILDING.txt                          (rev 0)
+++ trunk/BUILDING.txt  2012-12-21 09:14:49 UTC (rev 6076)
@@ -0,0 +1,154 @@
+PerfSONAR Java Services
+=======================
+
+PerfSONAR consists of several subproducts, such as the Measurement
+Archives (MA) SQL MA and RRD MA, the Measurement Points (MP) OWAMP MP
+and BWCTL MP, and the Lookup Service (LS). Some of these are written
+in Java, collectively called the PerfSONAR Java Services. These
+include the MAs and the LS. 
+
+Notably, the MPs are not written in Java and are hosted outside of
+this repository. The UI is written in Java, but still not considered
+part of the PerfSONAR Java Services and not hosted in this repository.
+
+
+Building PerfSONAR Java Services
+--------------------------------
+
+PerfSONAR Java Services use Maven as a build system and as a
+repository of Maven artifacts. A top level aggregator project allows
+services to be build in one operation:
+
+        mvn package
+
+Generated artifacts are to be found in the target directories inside
+each subproject (sub-directory).
+
+
+Note that currently not all components are included in the aggregator
+project. This is because not all components have been updated to use
+the latest snapshot revisions of dependent artifacts.
+
+
+Specific subprojects can be build using the -am and -pl options of
+Maven, e.g.:
+
+       mvn package -am -pl perfsonar-java-sql-ma
+
+will build perfsonar-java-sql-ma and all sibling projects required by
+SQL MA. 
+
+It is not immediately possible to just cd into a subdirectory and
+execute Maven on a single project only. Such an attempt would fail
+because dependencies like PerfSONAR Base 1 would be unavailable (this
+is only partially true as we use GÉANT's continious integration
+service, Jenkins, to build the latest version and publish artifacts in
+the GÉANT Artifactory repository - you would however be using the
+latest committed version of the base package rather than the code in
+your working directory; it is generally safer to rely on the Maven
+aggregator project).
+
+
+Maven project structure
+-----------------------
+
+The top-level directory contains the Maven aggregator project. The
+sole purpose of this project is to list sub-projects as modules.
+
+Sub-projects all refer to a parent project in the parent
+directory. Common Maven settings are specified in the parent and
+inherited by other sub-projects. Specifically, the following settings
+should be taken from the parent:
+
+- File character encoding (UTF-8).
+
+- Java source and target version (1.6).
+
+- Maven plugin version numbers.
+
+  Altough Maven plugins have to be explicitly enabled in sub-projects,
+  the version number of the plugin should only ever be specified in the
+  parent. This ensure consistency.
+
+- Project management information like organization, license, issue
+  management, continous integration, Artficatory references, common
+  Maven repositories.
+
+- Reporting configuration used to generate a Maven site report.
+
+
+
+Library version numbers are NOT specified in the parent, as various
+subproducts use different versions of third party libraries.
+
+
+Note again that currently not all subproducts follow this structure.
+
+
+Packaging
+---------
+
+Running 'mvn package' produces jar and in some cases war files for
+each module. For modules that represent subproducts, the Maven package
+phase also builds distribution packages such as DEB and RPM.
+
+Debian packages are build using the Maven jdeb plugin. This is a
+portable pure Java implementation capable of producing a Debian
+package on any Java enabled platform.
+
+RedHat packages are build using the Maven RPM plugin. This plugin is
+only a wrapper around native RPM tools and thus RPM packaging only
+works if RPM is installed. RPM is commonly available on Linux, even on
+non-RPM distributions. RPM is not common on Mac OS or Windows.
+
+Debian and RedHat packaging is defined in two Maven profiles, deb and
+rpm, respectively. The deb profile is enabled by default and must be
+explicitly disabled using -P !deb as an option to Maven. The rpm
+profile is only enabled on Linux. This profile too can be explicitly
+disabled using -P !rpm, or explicitly enabled using -P rpm.
+
+
+Like any other artifacts, the output packages are found in the target
+directory of each module (the RPM package is in a subdirectory; look
+for it in the target/rpm directory tree).
+
+
+Note that we deliberately build these artifacts as secondary
+artifacts. The main artifact type is typically JAR (for libraries like
+PerfSONAR Base) or WAR for subproducts (these are deployable to common
+servlet containers like Tomcat and Jetty).
+
+
+Continous Integration
+---------------------
+
+PerfSONAR uses GÉANTs continious integration platform, Jenkins, at
+https://ci.geant.net/.
+
+The PerfSONAR-CI job monitors the SVN repository and any commit
+triggers a new build. If the build is successfull, all artifacts are
+published at http://artifactory.geant.net/.
+
+Statistics from static analysis are kept, and the output of Unit
+tests, findbugs, and pmd can be inspected in Jenkins.
+
+
+
+Releasing PerfSONAR
+-------------------
+
+There is currently no procedure for branching, tagging, and producing
+non-SNAPSHOT builds. Such a procedure is being developed.
+
+
+
+Legacy stuff
+------------
+
+There is still plenty of legacy code in the subversion
+repository. Originally, PerfSONAR was build using custom Ant scripts
+and plenty of shell scripts. Bits and pieces of these are still used,
+eg to package eXist as DEB and RPM packages. The intent is to get rid
+of these pieces and no attempt is made at documenting those legacy
+components.
+