How to develop on Ametys ?

Principle

Ametys is a JEE Servlet web application.

It is divided in severals component. The base component is the "Runtime". Several "plugins" and "workspaces" will take place on it.

Requirements

To develop you will need at least

  • Java 6 JDK
  • Apache Ant 1.7 or more
  • SVN
  • SVNMerge

For librairies dependencies we are using IVY

The projet svn url is : https://svn.ametys.org

Structure

You need to have a copy of the ivyrep on your local drive.

You need the "Deliver" projet that is a base for all the build system. (if you want to build the Deliver project, you will need the "Tools" project)

You then need the projects you want to edit, in the versions you want.
The kernel part of Ametys is : Runtime + RepositoryApp + RepositoryPlugin + Workflow + ExplorerPlugin + ExplorerApp + CMS + WEB + Site.
Then you have 3 kinds of plugins : the officials, the communities, the odf.
Finally you have the application template : currently there is one CMSWeb.

Build

You can see technical details on the dedicated page.

The principle is when you build a project in local, it is added to your local IVY repository. Then your local projects can depends on it.

 SVNMerge

When correcting a bug you have to svnmerge it on old versions.

When adding a feature you have to svnblock it on old versions

Practically

This is about how to do it "for real", using ours methods and our tools.

Requirements

  • Download and install Java 6 at at www.oracle.com (JRE is enought)
  • Download and install Eclipse for Java developper at www.eclipse.org
  • On eclipse, you have to install the svn plugin Subversive and the svn connector
  • On eclipse, you have to install IVYDE
  • Download and install a command line svn tool and add it to the path
  • Download and install SVNMerge (python for linux or directly exe for windows) and add it to the path

Install

In eclipse, configure the Ametys SVN repository and download the Deliver project (optionnaly the Tool project) in a ametys directory

In the project Deliver, click right on dev-kit/startup/build.xml and choose Run as / Ant Build...
(you can optionnaly set "dest-dir" and enter the absolute path where you want to dev on Ametys
or the "project.name.prefix" that is "Ametys - " by default.

In the "Classpath" tab you may need to add the startup-kit/lib/*.jar the additionnal lib, add the following jvm parameter -XX:MaxPermSize=256m

In the "Targets" tab, choose a target : all, all-trunk, all-old, kernel-trunk...
    The "all" target gets all projects in trunk and old versions (but not obsolete)

    The other targets are a prefix + a suffix :

        The prefix "all" means all projects
        The prefix "kernel" means kernel projects
        The prefix "officials" means officials plugins
        The prefix "community" means community plugins
        The prefix "odf" means odf plugins

        The suffix "-trunk" means the last version
        The suffix "-old"  means the older versions (but you also need the -trunk in case a project only have a trunk version)
        The suffix "-obsolete" means the non supported versions (you will need old and trunk projects as well)

Then run and have a billions coffee

Once this is done, in Eclipse do File / Import / General - Existing projects into workspace and select the dest-dir you set above.

Eclipse will list all the created projects. Finish

And wait for eclipse to build all.

Build

You can run any ant file "build" to build a particular project, and do right-click Resolve on "Ivy library" of another project.

Properties to set on each (I recommand setting them as default in window preferences / Ant / Runtime / Properties)

  • check.i18n If present will check the i18n catalog is the same in all langages
  • check.license If present will check the license header is ok on all files
  • common-build Set the absolute path to the Deliver\common-build.xml file
  • ivy.jar Set the absolute path to the Deliver\lib\ivy-X.X.X.jar file
  • ivy.settings Set the absolute path the Ivyrep\ivysettings.xml file
  • skip.docs If present will not produce docs (recommanded)
  • skip.tests If present will do unitary tests(recommanded)

Keep in mind that ivy is a chain.

For example, if you change something in the runtime and want to see it in the template you have three ways

  • Build repoApp : you have then a repoApp that depends on YOUR runtime
  • Build repoAppPlugin : you have then a repoPlugin that depends on YOUR repoAPP that depends on YOUR runtime
  • ...
  • Build WEB
  • Resolve ivy in your template.
  • The second way is to set into the ivy.xml file of the template a direct dependancy to the Runtime
  • The third way is the more powerfull but the most complicated : The idea is not to run plugins as jars but as directories. Add a softlink in "plugins/cms" to "CMS/main/plugins-cms" and edit the ivy.xml so the cms jar will not be used... but you have then to add the cms dependencies manually in your ivy.xml file... Ask the forum for more informations

How to test your dev

Configure the templates projects on a Tomcat or Jetty.

Configure the ivy librairie to retrieve the configuration "runtime", type "jar,lib" to the pattern webapp/cms/WEB-INF/lib/[artifact]-[revision].[ext]

In the directory lib you should see (do F5 if not) all the required jar files (more than 100 files)

Keep uptodate

Regularly, you have to update all projects of course.

But what to do if there are new projects ? Update Deliver, and re-run the "startup-kit" (that will be very fast this time) and re-imports all projects.

(If you have tweak you .projects or .classpath don't worry they will not we overriden - but the an existing project has a new .classpath conf, you will not have it : good luck !)