Add-on Manager
Contents |
How to build Add-on Manager
Prerequisites:
- Linux, Mac (Windows not yet tested)
- cvs
- jdk 1.6
- maven 2
Checkout:
export CVSROOT=:ext:user@cvs.labs.libre-entreprise.org:/cvsroot/neogia cvs co addonmanager
Build:
cd addonmanager sh build-adm.sh
How to install Add-on Manager
You can build the addon Manager as describe in the previous point, or you can use a compile version which is in the ofbizAddon root directory.
alias adm='java -jar <path_to_addonmanager>/addonmanager/addonmanager-cli/target/addonmanager.jar'
How to create an Add-on
- Checkout a fresh ofbiz tree and prepare a new add-on:
cd ofbiz adm new-addon my-addon
- Implement the add-on's feature directly in ofbiz tree
- List all files modified since last add-on creation :
adm status
- Add each file modified for the add-on's feature to the list of files modified by add-on =
adm add-file <file path>
- Once the add-on is considered feature-complete, you must give a version number to the add-on
adm seal 1.0
The last command will generate a file .addons/my-addon-1.0.zip that contains all patchs required to install the add-on on a fresh ofbiz installation.
example
For manager supported commands:
youssef@goree:~/CompactWS/ofbizforaddon$ adm help [INFO] Add-On Manager for /home/youssef/CompactWS/ofbizforaddon [INFO] Usage: java -jar org.neogia.addonmanager.AddOnManager command [command args] [INFO] [INFO] Supported Commands : [INFO] - init [INFO] - install <addon-path> [INFO] - uninstall <addon-name> [INFO] - list [INFO] - status [INFO] - diff <path> [<path> [<path> ...]] [INFO] - revert <path> [<path> [<path> ...]] [INFO] - new-addon [-d addon-location] <addon-name> [INFO] - add-file [-f] <path> [<path> [...]] [INFO] - seal <version>
This example demonstrate how alternate-config add-on has been created :
Peter@garfield:~/Projects/ofbiz$ svn status Peter@garfield:~/Projects/ofbiz$ adm new-addon alternate-config [INFO] Add-On Manager for /Users/Peter/Projects/ofbiz [INFO] Initializing registry ... [INFO] Indexing ofbiz tree ... [INFO] Initializing repository database ... [INFO] Add-on alternate-config registered Peter@garfield:~/Projects/ofbiz$ patch -p0 < ../alternate-config-addon.patch2 patching file framework/start/src/org/ofbiz/base/start/install.properties patching file framework/start/src/org/ofbiz/base/start/rmi.properties patching file framework/start/src/org/ofbiz/base/start/start.properties patching file framework/start/src/org/ofbiz/base/start/jetty.properties patching file framework/start/src/org/ofbiz/base/start/test.properties patching file framework/start/src/org/ofbiz/base/start/setup.properties patching file framework/start/src/org/ofbiz/base/start/pos.properties patching file framework/start/src/org/ofbiz/base/start/Start.java Peter@garfield:~/Projects/ofbiz$ adm status [INFO] Add-On Manager for /Users/Peter/Projects/ofbiz [INFO] M framework/start/src/org/ofbiz/base/start/Start.java [INFO] M framework/start/src/org/ofbiz/base/start/install.properties [INFO] M framework/start/src/org/ofbiz/base/start/jetty.properties [INFO] M framework/start/src/org/ofbiz/base/start/pos.properties [INFO] M framework/start/src/org/ofbiz/base/start/rmi.properties [INFO] M framework/start/src/org/ofbiz/base/start/setup.properties [INFO] M framework/start/src/org/ofbiz/base/start/start.properties [INFO] M framework/start/src/org/ofbiz/base/start/test.properties Peter@garfield:~/Projects/ofbiz$ adm add-file framework/start/src/org/ofbiz/base/start/Start.java [INFO] Add-On Manager for /Users/Peter/Projects/ofbiz [INFO] P framework/start/src/org/ofbiz/base/start/Start.java Peter@garfield:~/Projects/ofbiz$ adm add-file framework/start/src/org/ofbiz/base/start/*.properties [INFO] Add-On Manager for /Users/Peter/Projects/ofbiz [INFO] P framework/start/src/org/ofbiz/base/start/install.properties [INFO] P framework/start/src/org/ofbiz/base/start/jetty.properties [INFO] P framework/start/src/org/ofbiz/base/start/pos.properties [INFO] P framework/start/src/org/ofbiz/base/start/rmi.properties [INFO] P framework/start/src/org/ofbiz/base/start/setup.properties [INFO] P framework/start/src/org/ofbiz/base/start/start.properties [INFO] P framework/start/src/org/ofbiz/base/start/test.properties Peter@garfield:~/Projects/ofbiz$ adm status [INFO] Add-On Manager for /Users/Peter/Projects/ofbiz Peter@garfield:~/Projects/ofbiz$ adm seal 1.0 [INFO] Add-On Manager for /Users/Peter/Projects/ofbiz [INFO] add-on 'alternate-config' sealed to version '1.0' Peter@garfield:~/Projects/ofbiz$ ls -l .addons/ total 32 -rw-r--r-- 1 Peter staff 111 7 mar 16:54 add-ons.xml drwxr-xr-x 4 Peter staff 136 7 mar 16:53 alternate-config -rw-r--r-- 1 Peter staff 4914 7 mar 16:54 alternate-config-1.0.zip -rw-r--r-- 1 Peter staff 281 7 mar 16:51 default-exclude-filters.txt Peter@garfield:~/Projects/ofbiz$
Advice, Howto use (cf Mail from Peter Goron 10/04/2009)
It is no more possible to add files to an add-on because it is surely in the "sealed" state. This state is reached when the add-on is packaged as a zip file.
When you execute the adm new-addon my-add-on, the add-on manager has created a folder my-add-on in ofbiz/.addons and has registered the add-on in the ofbiz/.addons/add-ons.xml file. At this moment, if you run the adm list command, the add-on manager will list your add-on with a star near it, which means that this add-on is modifiable :
Peter@garfield:~/Projects/ofbiz$ adm list [INFO] Add-On Manager for /Users/Peter/Projects/ofbiz Installed add-ons: - my-add-on (*)
There can only be on modifiable add-on. It is always the last created add-on, until it is transformed as a zip file.
Then, for the modified files in ofbiz, you add them in the add-on via the adm add-file pathToFile. At each call of the command, the add-on manager will create a patch according to the changes in the file since the add-on creation.
Once the modifications done, you should have created a distributable version of the add-on via adm seal 1.0 This command has generated an ofbiz/.addons/my-add-on-1.0.zip and has modified the records, to make it call the file instead ot the folder located in ofbiz/.addons/my-add-on.
At this moment, the add-on is no more modifiable.
Peter@garfield:~/Projects/ofbiz$ adm list [INFO] Add-On Manager for /Users/Peter/Projects/ofbiz Installed add-ons: - my-add-on
If you try adding a file, you will have the following error :
youssef@goree:~/CompactWS/ofbizforaddon$ adm add-file > framework/common/webcommon/includes/header.ftl > [INFO] Add-On Manager for /home/youssef/CompactWS/ofbizforaddon > [ERROR] Unable to add file(s) without an add-on being edited
There is no command to revert the add-on manager records to the non-sealed version (except de-install the add-on and install the non-sealed version, or manually edit the .addons/add-ons.xml file).
I think that in some time, the command seal won't call the sealed version of the add-on.
The best arborescence to work with add-ons is the following :
~/Projects/ofbiz ~/Projects/ofbizAddOn (project downloaded from the Neogia CVS)
and to create an add-on as following, from the OFBiz root :
adm new-addon -d ../ofbizAddOn/my-add-on my-add-on
The -d allows you to specify where the add-on sources are located, if you want to put them outside the OFBiz folder.
Howto Add documentation in Addon
Each add-on is documented by an add-on.xml file at the root of the archive. The goal of this file is to keep a lot of information of the specified add-on, as we can see with the pom.xml files in maven project.
This file is automaticaly created with the creation of an add-on (adm new-addon my-add-on), and can be edited without any risk with the add-on manager.
This page is a good introduction to the pom maven schema, until we found something better.
Example of an add-on.xml file
<?xml version="1.0" encoding="UTF-8"?>
<add-on>
<groupId>org.apache.ofbiz</groupId>
<artifactId>uploadFileInContent</artifactId>
<version>1.0</version>
<properties>
<ofbiz-version></ofbiz-version>
</properties>
<name></name>
<description></description>
<licenses>
<license>
<name>Apache 2</name>
<url>http://www.apache.org/licenses/LICENSE-2.0.txt</url>
</license>
</licenses>
<developers>
<developer>
<name></name>
<roles>
<role></role>
</roles>
</developer>
</developers>
</add-on>
How to publish automatically an Add-on in addons.neogia.org
To have the addon available on addons.neogia.org, all you need to do is to change the value of "<version>" tag and commit add-on.xml of the addon you want to publish.
As a best practice, you also need to add a "changeitem" tag corresponding to the version in add-on.xml and modify the ivy.xml to the version you are going to publish.
Every five minutes, a bot will make an svn update to see changes and publish the new version as you asked to. At the same time, it will check which addons have a dependency to itself.
It will then send a first email to neogia-devel@lists.sourceforge.net to tell you that your addon is published (e.g : "publish : crm-common-b2b version 2.9.1" )
At the same time, it will send an email that contains the detail of what it did (details publication of crm-common-b2b). It's a log that you can read to know what it did. But it also sometimes contains a patch (e.g : "patch available at http://addons.neogia.org/patchs/publishdependencies.2010-03-24_15-05.patch") You should download the patch, apply it to your repository and commit changes (be sure that changes are really what you want)
now you can install your addon using adm install addon-name.
/!\ Be carrefull the publish script contains bugs or stuffs to improve :
*"<changeitem" should be in only one line *The patch is created for addons in svn repository that depends to your addon, and with the version corresponding. *If you publish an addon from stable to dev, addons that depends on it will still be supposed to be stable. *The patch sent by mail does not check that the addon is really able to install. for example, addon A create a file aa.xml addon B patch aa.xml if you change aa.xml, modifying A version on the B ivy.xml will not be enough. The best way is to regularly check http://addons.neogia.org:3737/ and selenium.neogia.org
How to install an Add-on
cd ofbiz adm install my-addon
This will download the latest version of my-addon from addons.neogia.org and install it. You can specify a version using -v (e.g : adm install my-addon -v 1.2 )
You can also download the addon and install the zip file :
cd ofbiz adm install /path/to/my-addon.zip
Or install from a directory (for examples svn repository) :
cd ofbiz adm install /path/to/my-addon
