1. Getting started
If you're new to Hedeby and its architecture, read the the introduction section here.2.Tools used
As other software projects, Hedeby development also uses several tools to speed up its development process. Most obvious one is a high-quality IDE, but there are numerous others tools to help the work to be done.Ant
Ant provides the building mechanism for the Hedeby. Thanks to NetBeans' use of Ant, there is no difference if building Hedeby from command line or from NetBeans. Hedeby is using Ant 1.6.5 (or higher) which is available at http://ant.apache.org.Java
Java is platform for Hedeby. Thanks to lots of new wonderful and very useful features in Java 5 we decided to build Hedeby around this version of Java. If you do not already have JDK 5 you can get it at http://java.sun.com. (we recommend to use JDK 1.5.0.12. Java 6u3 or higher is also supported).NetBeans
IDE is used to develop and maintain code. Most of the code was written using NetBeans, but we also used other well-known text-editors such as vi and emacs.CVS
Stands for concurrent versioning system which is a file repository system storing Hedeby sources, documentation and other related files as well as their history of changes.SunSource.net
is a site devoted to Sun's involvement in Free & Open Source projects, and it provides convenient links to the Hedeby project site, and there is a convenient archive of previous news and mail list discussions.3. Getting the sources
The Hedeby project sources are stored in a CVS repository which is running on the Sunsource.net site. Therefore for getting the Hedeby sources, you will need cvs client tool. Most Linux machines at least have the command-line CVS client installed by default - try typing simply cvs at a command prompt and see what happens. On windows machines we recommend to use WinCVS or Tortoise open sourced CVS client. You might want to visit any of several good sites such as http://www.cvshome.org/ which lists available CVS clients for different platforms, their strengths and weaknesses. Alternatively, you may wish to use the CVS support built into the NetBeans IDE itself or use Sunsource's Version control feature (web interface to CVS repository) here.You can find more detailed information about recommended CVS clients setup here. And you probably should also read the manual included with most CVS clients for general information.
Main module
Hedeby's main module is called simply Hedeby and (easy to guess) it containes the very core functionality of the Hedeby. The module name under cvs is “hedeby”. For a most current opensourced version type following at your command prompt:cvs -d :pserver:<your_sunsource_login>@cvs.sunsource.net:/cvs co hedeby
Grid Engine Adapter
Grid Engine Adapter is Hedeby's service adapter for Grid Engine. It implements functionality needed to discover resource needs of the Grid Engine cluster as well as it implements a service management functionality specific to Grid Engine. You can find more about grid engine adapter here. The submodule name under CVS is “hedeby-ge-adapter”. For a most current opensourced version type following at your command prompt:cvs -d :pserver:<your_sunsource_login>@cvs.sunsource.net:/cvs co -d ge-adapter hedeby-ge-adapter
Security
As its name says, security module implements all stuff related to security needed for Hedeby to function properly in secured enviroment. You can find more about security here. The submodule name under CVS is “hedeby-security”. For a most current opensourced version type following at your command prompt:cvs -d :pserver:<your_sunsource_login>@cvs.sunsource.net:/cvs co -d security hedeby-security
Recommendations
If you plan to use NetBeans IDE to contribute (or just to browse through the Hedeby source codes), we strongly recommend you to keep project directory structure like this:hedeby
|---->ge-adapter
|---->security
That means before you checkout any submodules, switch your working directory to directory where you checkedout the Hedeby main module. Or if you were too fast, simply copy/move all submodules to the directory holding the main module. Although it is possible to have main module and submodules placed in different locations, it is more convenient to keep all submodules under main module directory.
4.External libraries
Couple of external libraries (not stored in Hedeby CVS repository and not part of JDK) are used by Hedeby project. Before you even try to compile and build Hedeby, you should check if you have all of them. All of the below libraries are required for building Hedeby, except the JavaCC, which is the only optional library.JavaCC
JavaCC stands for "Java Compiler Compiler". JavaCC is used generate parser for the role definition file. Hedeby uses version 4.0 of JavaCC.Gridengine
Gridengine is needed for Hedeby's Gridengine adapter. You will need the most current version of the Gridengine installation with JUTI and JGDI libraries.Gridengine is available at http://gridengine.sunsource.net.
JUnit
JUnit is the Unit tests framework for Java. Hedeby uses version 3.8 of JUnit.JUnit 3.8. is bundled with NetBeans, or if you can download it at http://www.junit.org.
JavaHelp
JavaHelp is tool for incorporating help system into applications and thus providing online-documentation. Hedeby uses version 2.0 of JavaHelp.JavaHelp is available at http://java.sun.com/products/javahelp.
Xalan
Xalan is a XSLT processor. Xalan is used by DocBook, which is used by Hedeby for generating the documentation. Hedeby uses version 2.7 of Xalan.Xalan is avaialable at http://xml.apache.org/xalan.
XML Resolver
XML Resolver is tool used to examine URI of requested resources and provides way how to satisfy those requests. Hedeby uses version 1.2 of XML Resolver.XML Resolver is part of the XML Commons and is avaialable at http://xml.apache.org/commons.
DocBook
DocBook is XML based tool for generating documentation. Hedeby uses version 4.2 of DocBook.DocBook is available at http://docbook.sourceforge.net.
DocBook XSL
DocBook XSL Stylesheets is set of XSLT stylesheets that DocBook uses to transform XML into another format (HTML, PDF, MS Help). Hedeby uses version 1.71.1 of DocBook XSL.DocBook XSL is available at http://docbook.sourceforge.net.
5. Ant project
There is no need to use NetBeans if you want to compile, build or contribute to Hedeby. If you prefer another IDE or just plain text editor, you can use Ant to call different call targets from commandline. Before you try to use Ant from commandline, be sure that you have all the required libraries and you have configured you build eviroment properly.Project setup
If you decided to run Ant from commandline the only thing which is needed to do is the customize your 'build*.properties' file according to your working enviroment.The Ant build system does not allow to override the build variables (properties). The Hedeby ant build script therefore imports build files in the following order:
build_private.propertiesbuild_private_<arch>.propertiesbuild_<arch>.propertiesbuild.properties
<arch> should be replaced by gridengine architecture of the build host (e.g. win32-x86, lx26-x86, ...).
Available properties
Following properties are available to customize:| Property | Description |
|---|---|
modules |
List of all modules which you want Hedeby to 'use'. The build process needs
this list to be able dynamicaly build all of the relevant submodules. You can specify your own
set of modules in 'build_private.properties' file.
Example:
Note: This property is also used by NetBeans project.
|
common.dir |
Name of the directory holding part of the main Hedeby module's files. Usually you do not
need to change this property.
Example:
Note: This property is also used by NetBeans project.
|
hedeby-ge-adapter.dir |
Name of the directory holding the Grid Engine adapter module's files. You need to change
this property if you used NetBeans to checkout sources. For more information refer to section 3.
Example:
Note: This property is also used by NetBeans project.
|
hedeby-security.dir |
Name of the directory holding the Security module's files. You need to change
this property if you used NetBeans to checkout sources. For more information refer to section 3.
Example:
Note: This property is also used by NetBeans project.
|
sge.root |
Defines the
path to the gridengine installation. The build process needs the
jgdi.jar and juti.jar in ${sge.root}/lib from a Grid Engine 6.2 distribution.
The sge.root property depends in the user environment. It should be set in
build_private.properties or in build_private_win32-x86.properties
if you try to build hedeby on windows.
Example:
Or on Windows
Note: This property is also used for
some junit tests. If it is not set correct, these tests will
fail.
|
|
This property is need to build the junit
tests. If you build the hedeby project with Netbeans this
property is already set by the IDE. You only need it for build it
from the command line.
Example:
|
distinst.dir |
Specfies where the distinst target unpackes the hedeby distribution. |
javacc.home |
Optional
Some parts of hedeby uses the java compiler compiler version
4.0 (https://javacc.dev.java.net).
The javacc.home property specifies where javacc is installed.
Example:
javacc.home=/tools/javacc-4.0 |
jaxb.home |
Hedeby uses jaxb for xml binding. Version 2.1.6 or higher is required
(https://jaxb.dev.java.net).
The jaxb.home property specifies where javacc is installed.
Example:
javacc.home=/tools/jaxb-2.1.6 |
javahelp.home |
Path the the installation of javahelp. The buildscript adds ${javahelp.home}/lib/jh.jar to the classpath of some tasks. |
xalan.home |
Path the the installation of xalan. The buildscript adds ${xalan.home}/lib/xalan.jar to the classpath of some tasks. |
xml-resolver.jar |
Path the the XML resolver JAR file. The buildscript adds ${xml-resolver.jar} to the classpath of some tasks. |
docbook.xsl.home |
Path the the XSL stylesheets used by DocBook. |
docbook.home |
Path the the DocBook XML installation directory. |
javac.debug |
If set to true, all java classes are compiled with the debug option. |
javac.deprecated |
If set to true, all java classes are compiled with the deprecated flag |
javac.optimize |
If set to true, all java classes area compiled with the optimize flag |
javac.target |
Java version level for the compiled classes. Valid options (depending on your java version) are 1.1, 1.2, 1.3, 1.4, 1.5. Default value is '1.5'. |
javac.source |
Java version level of the source classes. Currently only valid (and default) option is '1.5'. |
distinst.dir |
Target directory where 'distinst' ANT target will install the distribution. Applicable only in build_private*.properties! |
Building project
To allow modularized concept of the Hedeby we made the Hedeby build script quite complex. Int the following table we give you an overview of the major build targets.| Target | Description |
|---|---|
jar |
Builds all jar files of the hedeby (including the jar files of the submodules) |
zip |
Builds the dist/hedeby.zip file containing a binary distribution. |
tar |
Builds the dist/hedeby.tar.gz file containing a binary distribution. This target does not work on windows. |
javadoc |
Generates the javadocs of hedeby (including the javadoc of the submodules). Each submodule creates it's own set of javadocs, crosslinks between the javadocs are generated. |
javadoc.publish |
Copies the javadocs into the www/javadoc/<version> directory. The version is defined in the build script of each submodule (property module.version). |
test |
Run all junit tests of the hedeby project (including the submodules). |
config-center.run |
Starts the hedeby-config-center. |
config-center.debug |
Starts the hedeby-config-center in the debugger of Netbeans. |
distinst |
Install Hedeby into the directory specified by 'distinst.dir' property. |
6. NetBeans project
To make your work on Hedeby as easy and pleasant as possible we recommend to use NetBeans IDE. Following few paragraphs will give you short insight how to use Hedeby and Netbeans together (click on the pictures to enlarge them).How to open Hedeby project
First you will need to get the Hedeby sources from CVS (if you have already done so you can skip this part). The process of getting sources using NetBeans is little bit different from commandline CVS approach so read the next lines carefully.Following picture shows how to set up CVS root to get all Hedeby stuff.
Just a quick note - browse for Hedeby main module (or just type 'hedeby' in the 'Module' textfield), choose HEAD branch (main trunk) and local repository. If you are not sure, see the following picture.
If you are running on *nix platform, be sure that folowing files can be executed:
- <common.dir>/dist_files/util/arch
Once you checkout the Hedeby main module, you can open its associated NetBeans project. Just go to the directory which you chose in the previous step as your local repository and you should be able to open it. See the picture below for details.
Since the Hedeby makes more sense with its additional modules, we recommend you to checkout all available modules before you begin to work with it (see the list of the modules in the section 3. Getting sources). You can use almost the same way of getting the sources of the additional modules as you did use for getting the main module. In the following paragraphs we assume that all aditional modules are checked-out with their original repository names and are placed under the main Hedeby module directory (if you are not sure what we meant just see the first picture in the next section).
Project setup
Thanks to Ant support in NetBeans the same applies to Hedeby NetBeans project setup as for project running Ant from commandline. The changes you will make in the 'build*.properties' file will reflect in NetBeans project. If you used NetBeans CVS wizard to checkout the Hedeby modules you need to make some changes. Since NetBeans CVS wizard does not allow to change local name of the modules that are going to be checked out you need either to change of the local module directories or change build variables in one of the 'build*.properties' file. We recommend to change the names of the local directories containing the Hedeby modules (it will be easier to follow with other examples). Just check the following picture if you are not sure. To make your setup perfectly correct just strip 'hedeby-' from the names of the module directories.
The easiest way to provide custom building enviroment to your copy of the Hedeby NetBeans project is to create your own properties file containg all needed variables. You can use NetBeans to do this - just add new locale named 'private' to 'build.properties' file (which should be in the main Hedeby module). See the following picture for details. More detailed description of each property is in the section 5.
If you followed all the instructions, you should be able to open Hedeby NetBeans project and see the same layout as it is shown on the following picture.
Building Hedeby with NetBeans
Building Hedeby with NetBeans is pretty easy. All the major Ant targets are available on the project context menu. Just see the following picture to know how it looks like and see the section 5 for detailed description of the available Ant targets.
To check if everything is working for you run "Build project" target from the context menu. If everything goes well, you should have built Hedeby jars files. Now you can try to install Hedeby system - more about installation process is available here.
7.Windows specific
Building project
All Windows specific code is automatically compiled if 'ant' is executed on Windows in the hedeby root directory. <YOUR_JAVA_HOME> must point to ...\Java\jdk1.5.0_06\jre.Building the native executables and library
There are currently two native Windows executables and one native Windows library:
- starts hedeby at system boot timeSvcmgmtStarter.exe
- for administering hedeby. This executable gets copied to gstat.exe by the distinst part of the ant script. Depending on it's name, it fullfills different purposes.gconf.exe
- contains several functions for direct access of Windowsplatform.dll
must point to <YOUR_DEVSTUDIO>\Vc7\include; <YOUR_DEVSTUDIO>\Vc7\PlatformSDK\Include; <YOUR_DEVSTUDIO>\Vc7\atlmfc\includeINCLUDE
must point to <YOUR_DEVSTUDIO>\Vc7\lib; <YOUR_DEVSTUDIO>\Vc7\PlatformSDK\Lib; <YOUR_DEVSTUDIO>\Vc7\atlmfc\libLIB
must point to <YOUR_DEVSTUDIO>\Vc7\bin; <YOUR_DEVSTUDIO>\Common7\IDE; ...\Java\jdk1.5.0_06\binPATH
8.Issue submission guide
General info
Hedeby development is not diffrent from other software development projects - developers sometimes make errors. To provide high quality product we use Issue tracker tool which helps us to track all of such cases. Issue tracker is simply repository holding records for all of:defectspatchestasksfeaturesenhancements
Hedeby Issue tracker categories
Putting all defects, feature request, enhancements etc. into one category would probably make a mess in the repository (and in our heads probably too). Therefore there are couple of categories which might help you to navigate in Hedeby Issue tracking. As one would expect the categories relates to components of the Hedeby (and some of them are even more fine-grained). You can find following categories in the Issue tracker:
- main category which serves as a content holder for more specific categories (see below)Hedeby
category related to the main Hedeby modulecore:
category related to Hedeby's configuration toolconfig-center:
category related to Grid Engine adapter for Hedebyge-adapter:
category related to N1SM specific OS provisioner for Hedebyn1sm-adapter:
category related to Hedeby's security modulesecurity:
category related to Hedeby's documentationwww:
Issue Type
a problem with an existing feature that is not developed to spec or does not work as designed. These are often referred to as "bugs."Defect:
an improvement to an existing feature.Enhancement:
an addition to the software to add a piece of functionality that does not yet exist.Feature:
an activity to be done on behalf or in support of a feature or enhancement. Tasks do not typically require direct changes to the code base.Task:
a special kind of issue: a section of code to be applied or attached to existing software. Often, a patch fixes a defect.Patch:
9.Communication
You probably noticed, that Hedeby consists of several modules, which are more or less independent between themselves, but needs to follow certain criteria in relation to main module. It obviously requires great effort to keep Hedeby development consistent (read “all modules are working nicely together”). Big help to this effort is our mailing lists which help us to organize all discussion threads.There are several mailing lists related to Hedeby development :
announce@hedeby.sunsource.netcvs@hedeby.sunsource.netcvs@hedeby-config-center.sunsource.netcvs@hedeby-ge-adapter.sunsource.netcvs@hedeby-n1sm-adapter.sunsource.netcvs@hedeby-security.sunsource.netdev@hedeby-.sunsource.netissues@hedeby.sunsource.netusers@hedeby.sunsource.net
