Ganttproject-developers-guide-0 9

GanttProject Developer Guide Version 0.9

by Jean-Marc Libs, Benoît Baranne, Julien Seiler

Version

Author

Date

Most changes

0.1

Jean-Marc Libs

Initial revision

0.2

Jean-Marc Libs

Running code with eclipse

0.3

Jean-Marc Libs

0.4

Benoît Baranne

0.5

Benoît Baranne

0.6

Benoît Baranne July 2005 & Juien Seiler

MacOS

0.7

Benoît Baranne

July 2005

Windows installer information

0.8

Benoît Baranne

July 2005

Complete MacOS for dmg creation

0.9

Jean-Marc Libs

July 2005

Quick explanation of Linux RPM creation

GanttProject Developer Guide

Pluginization changes June 2005

Eclipsito run

Page 2/33

CONTENTS SECTION 1 - INTRODUCTION..................................................................................................................4 1.1 - Purpose of this document...............................................................................................................................................4 1.2 - TODO............................................................................................................................................................................4

SECTION 2 - JAVA INSTALLATION.............................................................................................................5 2.1 - Java Software Development Kit download........................................................................................................................5 2.2 - SDK installation on Linux.................................................................................................................................................5 2.3 - SDK installation on Windows...........................................................................................................................................6

SECTION 3 - ECLIPSE

INSTALLATION.........................................................................................................7

3.1 - Eclipse download............................................................................................................................................................7 3.2 - Eclipse installation on Linux.............................................................................................................................................7 3.3 - Eclipse installation on Windows.......................................................................................................................................8

SECTION 4 - CREATE 4.1 4.2 4.3 4.4 4.5

-

A

GANTTPROJECT

PROJECT WITH ECLIPSE......................................................................... 9

Create a new project based on sourceforge CVS .............................................................................................................9 View your new eclipse projects......................................................................................................................................15 How to run the software from the project source............................................................................................................18 How to update projects from CVS..................................................................................................................................21 How to commit changes................................................................................................................................................22

SECTION 5 - DEPLOYMENT...................................................................................................................24 5.1 - General........................................................................................................................................................................24 5.2 - Building installers..........................................................................................................................................................27

GanttProject Developer Guide

Page 3/33

Section 1 - Introduction

1.1 - PURPOSE

OF THIS DOCUMENT

This document describes various useful information of interest to developers who would be interested in working on GanttProject source code.

1.2 - TODO Debian package

GanttProject Developer Guide

Page 4/33

Section 2 - Java installation

2.1 - JAVA SOFTWARE DEVELOPMENT KIT DOWNLOAD Since GanttProject has been developed in Java, the first thing you have to get is a Java Software Development Kit. There are several Development Kit that Sun provide. The one we advise you to use is the Java 2 Platform Standard Edition version 1.4.2 (J2SE 1.4.2). There are two things you can get about J2SE 1.4.2 : the Java Runtime Environment (JRE) and the Sofware Development Kit (SDK) which includes JRE. To develop you need the SDK. It is available for free at : http://java.sun.com/j2se/1.4.2/download.html.

2.2 - SDK INSTALLATION ON LINUX The following describes how to install the SDK on Linux. If you have downloaded the linux self-extracting file change to the directory where the file j2sdk-1_4_2_07-linux-i586.bin is. > sh j2sdk-1_4_2_07-linux-i586.bin Accept the licence by typing yes when asked. The SDJ will be extracted into the same directory. > ls j2sdk1.4.2_07/ j2sdk-1_4_2_07-linux-i586.bin Before starting GanttProject, you have to update your PATH. This can be done by typing the following lines in your shell: For Korn-shells (ksh, bash): > export JAVA_HOME=<path_to_sdk>/j2sdk1.4.2_07/ > export PATH=$PATH:$JAVA_HOME/bin/ For C-shells (csh, tcsh): > setenv JAVA_HOME <path_to_sdk>/j2sdk1.4.2_07/ > setenv PATH $PATH:$JAVA_HOME/bin/ Alternately, you can add these lines in your .bashrc file (or equivalent for other shells), so they are executed automatically. Now Java SDK is correctly installed. To check the java type the following : >java -version java version "1.4.2_07" Java(TM) 2 Runtime Environment, Standard Edition (build 1.4.2_07b05) Java HotSpot(TM) Client VM (build 1.4.2_07-b05, mixed mode)

GanttProject Developer Guide

Page 5/33

2.3 - SDK INSTALLATION ON WINDOWS You have downloaded a file named j2sdk-1_4_2_XX-windows-i586-p.exe (where XX is the update version). Run this file. Follow the installer to install SDK. The installation is complete, SDK is correctly installed.

GanttProject Developer Guide

Page 6/33

Section 3 - Eclipse installation You don't NEED to use eclipse in order to work on the GanttProject code. But if you don't know eclipse, you should give it a try, as it's what the GanttProject developers are using, and it's powerful and open source software. Prior to installing Eclipse, be sure you have a Java SDK installed.

3.1 - ECLIPSE

DOWNLOAD

You can download Eclipse at http://www.eclipse.org/downloads/index.php. Choose the latest stable version.

3.2 - ECLIPSE

INSTALLATION ON

LINUX

Installating Eclipse is quite simple : you only have to extract the downloaded archive. For instance, if the archive is a TAR-GZ archive, type the following : > tar -xvzf eclipse-SDK-3.1M5a-linux-gtk.tar.gz It creates a directory in which the Eclipse binary is. To run Eclipse change to eclipse directory and type : > ./eclipse

GanttProject Developer Guide

Page 7/33

3.3 - ECLIPSE

INSTALLATION ON

WINDOWS

Normally you have downloaded a ZIP archive. Installing Eclipse only consist in decompress this archive. It creates a eclipse folder. Change to this folder and run the eclipse.exe file. That's all !

GanttProject Developer Guide

Page 8/33

Section 4 - Create a GanttProject project with eclipse This section is for user which already have a working installation of eclipse. All the snapshots are taken on Eclipse Version: 3.1M7

4.1 - CREATE A NEW PROJECT BASED

ON SOURCEFORGE

CVS

GanttProject source code is put on a CVS repository on SourceForge.net. You can check out the sources using CVS. Eclipse supplies a CVS team programming environment that enables you to share your work with others. 4.1.1 - Create an eclipse CVS repository view First of all, you have to create a CVS repository view on GanttProject. To create a new repository location: 1. Open the CVS Repositories perspective by selecting Window > Open Perspective > Other... on the main menu bar and then selecting CVS Repository Exploring from the Select Perspective dialog. 2. On the toolbar, click on Add CVS Repository (or from the context menu of the CVS Repositories View, select New > Repository Location). The Add CVS Repository wizard opens. 3. Enter the information required to identify and connect to the repository location: a. In the Host field, type the address of the host cvs.sourceforge.net b. In the Repository path field, type the path to the repository on the host. /cvsroot/ganttproject c. In the User field, type the user name under which you want to connect to the repository. anonymous d. In the Password field you have nothing to type because you are anonymous. e. From the Connection Type list, select the authentication protocol pserver. 4. Click Finish. The repository location is created.

GanttProject Developer Guide

Page 9/33

Step 1 - Open a new perspective

Step 2 - Select CVS Repository perspective GanttProject Developer Guide

Page 10/33

step 3 - Add a new CVS repository

GanttProject Developer Guide

Page 11/33

step 4 - add information

GanttProject Developer Guide

Page 12/33

step 5- browse cvs Head

It is now possible to browse the CVS repository. The source is in the HEAD -> ganttproject. The repository, in this case, is the distant repository on SourceForge, so it is not surprising that the browsing is slow.

Of course, as you have used the « anonymous » user name, you may not commit your code to the CVS. If you wish to be able to commit code, you have to contact the project leader and ask for inclusion of your sourceforge login in the project developer's list. When the GanttProject admins have registered your SourceForge login as a GanttProject developper, you may configure the above differently in order to have write (« commit ») permissions: –

Use your SourceForge login and password instead of « anonymous »

–

Use connexion type « extssh » instead of « pserver »

GanttProject Developer Guide

Page 13/33

4.1.2 - Checkout a local copy of the code Now, you have to check out a local copy of GanttProject source code. There are several nodes in CVS head that you should check out to fully get GanttProject. Actually there are GanttProject core, and GanttProject plugins. Presently there are 3 plugins available: MS-Project import/export, HTML export and PERT view. In the future, there will probably be more and more plugins that you should check out. Obviously, you can check out GanttProject core source code without plugins. ➢ Check Out GanttProject core This is done by right-clicking on the « ganttproject » branch and selecting « Check Out As... »:

step 6 - Check out GanttProject core This may take a while...

GanttProject Developer Guide

Page 14/33

➢ Check Out GanttProject plugins This is done in the same way. Instead of chosing ganttproject node, you would choose: • org.ganttproject.impex.msproject for MS-Project import/export • org.ganttproject.impex.htmlpdf for HTMl export • org.ganttproject.chart.pert for PERT view

4.2 - VIEW

YOUR NEW ECLIPSE PROJECTS

Now you can view these projects in the Java Perspective:

GanttProject Developer Guide

Page 15/33

GanttProject Developer Guide

Page 16/33

N.B.: the [jabba] label will be different. The screenshots have been taken with eclipse communicating with a proxy named jabba. You will probably have [cvs.sourceforge.net] instead. As you can see, there are four new projects: •

ganttproject which is GanttProject core ;

•

org.ganttproject.chart.pert which is the PERT plugin ;

•

org.ganttproject.impex.htmlpdf which is HTML and PDF export plugin ;

•

org.ganttproject.impex.msproject which is MS-Project import/export plugin.

In the future, there will probably be more plugins, that should also appear here if you have correctly checked them out.

GanttProject Developer Guide

Page 17/33

4.3 - HOW

TO RUN THE SOFTWARE FROM THE PROJECT SOURCE

To run project you should be in the Java Perspective. There are several ways to compile and run GanttProject. You may compile and run GanttProject as: •

A separate application with no Eclipse knowledge: at the moment the only thing you need to fully compile GanttProject is to add library "eclipsito.jar" from lib/core. Having this done, you may continue compiling and running GP in the usual way, by command line for example.

•

A runtime workbench: you may run GanttProject as Eclipse's runtime workbench. •

Open Run dialog

GanttProject Developer Guide

Page 18/33

•

create a new Run-time workbench configuration

N.B.: the profilers configurations that you can see on screenshots is not available by defaut in eclipse. It is an eclipse plugin you don't need to run GanttProject. You may not have these configurations in your eclipse version. •

On "Arguments" tab In the combobox "net.sourceforge.ganttproject.GanttProject".

•

Clear "Program arguments" field.

GanttProject Developer Guide

"Run

an

application"

select

application

Page 19/33

•

On "Plug-ins" tab select option "choose plugins and fragments to launch from the list" and select the following plugins: •

all workspace plugins if you want to have all plugins available. The only one that is absoluteley necessary is net.sourceforge.ganttproject;

•

externals plugins: •

org.eclipse.core.runtime;

•

org.eclipse.core.runtime.compatibility;

•

org.eclipse.osgi;

•

org.eclipse.update.configurator;

Then you can « apply » and « run »! N.B.: Using this way of launching GanttProject, you may have an error message saying « can't open file -pdelaunch ». It is a known issue that you should not care about. GanttProject Developer Guide

Page 20/33

4.4 - HOW

TO UPDATE PROJECTS FROM

CVS

To keep the newer version of GanttProject, you should update the projects regularly. You can update the whole project, some parts or a single file if you want. •

Select the item (whole project, folder, file, etc.) you want to update

•

right-click on it and select “Team” -> “Update”

Eclipse will connect CVS and update the files.

GanttProject Developer Guide

Page 21/33

Eclipse may ask you to select the tag for the update. Choose HEAD to get Head trunk.

4.5 - HOW

TO COMMIT CHANGES

To commit changes you have to be able to access CVS in writing. With the anonymous access that is describe above, you don't have writing access, so you cannot commit your changes. To get a writing access, you have to contact one of GanttProject administrators whom be competent to allow you such an access. Once you have the writing access, you can commit your changes. The files that have been modified have a '>' in front of their name. As updating, you can commit, whole project, folders or single files. To commit: •

select the item you want to commit;

•

right-click on it and select “Team” -> “Update”;

•

enter a comment and validate.

Here are some screenshots about committing:

GanttProject Developer Guide

Page 22/33

GanttProject Developer Guide

Page 23/33

Section 5 - Deployment

5.1 - GENERAL Since GanttProject is a plugin and has plugins, you should export GanttProject as a plugin when you want to deploy it. Select menu item “File” -> “Export”

GanttProject Developer Guide

Page 24/33

Choose “Deployable plug-ins and fragments”

GanttProject Developer Guide

Page 25/33

Select all available plug-ins

In the “Export Options” you can choose “a single ZIP file”, “a directory structure” or “individual Jar archives for Update site”. The two first would suit, this example shows the process with “a directory structure”. As soon as the export is finished, a directory named “plugins” is created with the plug-ins (ganttproject core plus the other plug-ins you have chosen to export). Now you can test with eclipsito library if GanttProject will run correctly: copy the eclipsito.jar file at the same level as “plugins” folder you have just created by exporting GanttProject; copy the ganttproject-eclipsito-config.xml file too; Now you can run GanttProject using the command: > java -classpath yourclasspath;eclipsito.jar org.bardsoftware.eclipsito.Boot eclipsito-sample-config.xml You can also create a script file if you want... GanttProject Developer Guide

Page 26/33

5.2 - BUILDING

INSTALLERS

5.2.1 - Windows Principle The Windows installer for GanttProject is built with a free software: NSIS. You can find any information about NSIS at http://nsis.sourceforge.net/ and also download its latest release. The principle is to write a NSIS script file that, once compiled, will produce a windows installer. You can find a script file named ganttproject.nsi to build a Windows installer for GanttProject in the installer folder at the CVS Head of GanttProject.

How to build the installer To build the installer you have to compile the ganttproject.nsi script using NSIS. Prior to compile you have to install NSIS on your computer and there are some files to put together in the same folder: + doc folder - COPYING (required) - AUTHORS (not currently used) - README (not currently used) + plugins folder (all GanttProject plug-ins) + net.sourceforge.ganttproject_2.0.0 GanttProject Developer Guide

Page 27/33

+ org.ganttproject.chart.pert_1.0.0 + org.ganttproject.impex.htmlpdf_2.0.0 + org.ganttproject.impex.msproject_2.0.0 - eclipsito.jar - ganttproject-eclipsito-config.xml - ganttproject_16.ico - ganttproject_32_2.ico The COPYING, AUTHORS and README files are located at ganttproject root. eclipsito.jar can be found in lib/core. ganttproject-eclipsito-config.xml is located at ganttproject root. The icons files can be found in data/resources/icons. The plugins folder may be built using eclipse as follow: select ganttproject projects and all plug-ins projects, right-click and choose export from the context menu.

GanttProject Developer Guide

Page 28/33

Choose deployable plug-ins and fragments

Select all plug-ins, choose deploy as a directory structure and specify the right destination

GanttProject Developer Guide

Page 29/33

In the Windows explorer, you will have all the needed files in the same folder, then right-click ganttproject.nsi file and choose Compile NSIS Script.

After compilation, a exe file will be created, it is the Windows installer for GanttProject! To get further information about NSIS and NSIS script file format, read the NSIS manual and visit the NSIS Web site (http://nsis.sourceforge.net/). This way of creating the GanttProject Windows installer will certainly evolute in the future. So keep the developers' guide up to date...

GanttProject Developer Guide

Page 30/33

5.2.2 - GNU/Linux RPM package Principle The simplest way is to be root (one needs to be root later on anyway) and locate the /usr/src/RPM directory (or it may be in another place on your distribution, but it is not important). Install a working directory of ganttproject (anywhere), check that you can launch GanttProject, and zip it: zip -r package.zip directory place the zip file in RPM/SOURCES/ First round of creating the rpm Then we found a spec file and edited it to pur needs under the name ganttproject.spec in RPM/SPECS [root@PXX-KRISS SPECS]# rpmbuild -ba -v ganttproject.spec << TODO: here put the ganttproject file example >> One gets: RPM/SRPMS/ganttproject-1.12-alpha_3.src.rpm RPM/RPMS/i586/ganttproject-1.12-alpha_3.i586.rpm Beware: this executes all scripts from the spec file without registering the package in the rpm database. Check that ganttproject can be launched by a normal user. Check that GanntProject rpm works: # rm -rf /usr/share/ganttproject/ # rm /usr/bin/ganttproject Now ganttproject can't be launched by a normal user. # rpm -Uv RPM/RPMS/i586/ganttproject-1.12-alpha_3.i586.rpm Check that ganttproject can be launched by a normal user. Complete ganttproject.spec with the file list add /usr/bin/ganttproject in the list of files in the end of ganttproject.spec then du /usr/share/ganttproject/ >> ganttproject.spec and edit (this is easy if you are familiar with vi) Create the real rpm -----------------[root@PXX-KRISS SPECS]# rpmbuild -ba -v ganttproject.spec

GanttProject Developer Guide

Page 31/33

5.2.3 - GNU/Linux Debian package 5.2.4 - MacOS Principle The MacOS software package is an archive containing all the files that the software needs and a properties file describing how the software has to be run. Once the package is suitably configured, a double-click on the file will launch the software. Package architecture The file contents could be viewed by right-clicking the file and selecting the “Display package content” option. The package is organized as follow : •

GanttProject.app •

Contents •

MacOS •

•

JavaApplicationStub :Java application launcher

Resources •

Java : folder containing all the needed file to run the software.

•

GanttProject.icns : package icon

•

Info.plist : package properties list

•

PkgInfo : package ID

Package working The package launch the Java application through the JavaApplicationStub executable. This program is able to launch a Java program from the package using the options supplied in the properties file Info.plist It is thus enough to suitably configure the Info.plist file and to include all the needed files for the running of the software in the Resources/Java folder. The info.plist file The Info.plist file gathers all settings information of the package. It is possible to easily publish this file thanks to the Property List Editor application. The settings concerning the Java launcher (JavaApplicationStub) is in the Java branch of the properties. To define these properties, it is possible to use the environment variable %JAVAROOT which corresponds to the Resources/Java file path. The following list presents the package properties :

•

In /root : •

CFBundleAllowMixedLocalizations

Use of several locales

•

CFBundleDevelopmentRegion

Package language

•

CFBundleExecutable

File to run being in the MacOS folder

GanttProject Developer Guide

Page 32/33

•

•

•

•

CFBundleGetInfoString

Application full name

•

CFBundleIconFile folder

Name of the file containing the icon is the ressources

•

CFBundleIdentifier

Simple software identifier

•

CFBundleInfoDictionaryVersion

Properties file version

•

CFBundleName

Application name

•

CFBundePackageType

Package type (APPL)

•

CFBundleSignature

Packager identifier or ????

•

CFBundleVersion

Application version

In /root/Java : •

Arguments

Command line arguments being in the args of the application main method

•

JVMVersion

Needed JVM version

•

MainClass

Name of the class containing the main method

•

VMOptions

JVM options

In /root/Java/ClassPath : •

0

Path to add at the first position in the classpath

•

1

Path to add at the second position in the classpath

•

n

Path to add at the nth position in the classpath

In /root/Java/Properties : •

apple.laf.useScreenMenuBar screen

Property to pass to Java for displaying the menu bar top of the

Resources The files that are needed to run the software are the Contents/Resources/Java folder into the package. DMG Once you have made the app package, you may want to create a dmg file. Use the disk tools to create a new image which size should be just a little bigger than the app package. Once the image created, mount the drive and copy the app package into it. Unmount the drive. You should have a dmg file in your documents folder by default (if you don't have specified another target when you have created the image).

- END OF DOCUMENT GanttProject Developer Guide

Page 33/33