AMAPstudio

User Tools


Packaging a release of Capsis to be distributed outside the Capsis community

This document explains how to package a release of Capsis that can be distributed to users NOT members of the Capsis community (Developers + Modelers). It was written to help the Capsis modelers distribute their models.

<note> According to the Capsis charter, the whole platform is distributable to anybody thanks to the LGPL free licence, EXCEPTED the modules which are NOT YOURS (growth / dynamics modules in the capsis4/bin/ directory). Those with a free licence can be distributed without asking the author, in any other case, you must ask the permission to the author. </note>

If you want to distribute your models outside the Capsis community, you should choose a distribution licence by copying two files in french and english, named respectively licence_fr.html and licence_en.html, in the main directory of your module (ex: in capsis4/bin/isgm/). We suggest the Lesser General Public Licence (free licence) if you agree with its terms. In this case, you must create a header in every class of your module, you can find details here. You are free to choose another licence.

Create a standalone installer

Capsis includes IzPack tool to generate a standalone installer.

Examples

1. To create an installer containing the modules mountain and fagacees (located in the directory lerfob/fagacees and requiring source files in lerfob/commons) with the sources:

ant clean installer -Dmodules="mountain/**,lerfob/fagacees/**,lerfob/commons/**"

2. To create an installer containing the modules pp3 without the sources:

ant installer -Dincludesrc=false -Dmodules="pp3/**"

It will generate a file named capsis-4.X.Y-setup.jar.

⇒ Rename the file as you want, e.g.: capsis-4.X.Y-mountain-fagacees-setup.jar

You can then distribute this jar file. To use it, please follow the installation instructions.

3. The command to create the downloadable installer on the Capsis web site:

sh ant installer -Dincludesrc=false -Dmodules="lerfob/commons/**, lerfob/abial/**, lerfob/fagacees/**, modispinaster/**, mountain/**, twoe/**, genloader/**, organon/**"

Old method

F. de Coligny - 3.4.2009

Here is a the old way to create a distributable version:

  • 1. Update your local copy through SVN and force total recompilation to be sure you have the last changes and everything is correct, test carefully your modules and correct the small remaining errors (missing or incorrect translations, unneeded trace in the Terminal or in the Log…)
  • 2. Create a directory for the package preparation with a conventional name like capsis4_fc_3apr2009_package/.
  • 3. Make a complete copy of your capsis4/ directory to help resolve unexpected problems later into a zipped file called capsis4_fc_3apr2009_backup.zip and place it in the package directory.
    • This backup will not be distributed to the end-user.
  • 4. In the package directory, create a directory named user_cd/. In user_cd/, create another directory named capsis4_fc_3apr2009/.
  • 5. From SmartSVN, export a backup of your capsis4/ local copy into user_cd/capsis4_fc_3apr2009/.
    • Use Tools > Export Backup… > Export all files and directories > Into directory (Export Backup may be in another menu depending of your version of SmartSVN). Everything will be copied except the .svn/ management directories (not needed in the user release).
    • Note: if you do not want to export the source codes (*.java), you may remove them afterwards but anyway it is possible to regenerate them from the .class files with a free utility. In this case, you can use your favourite file manager (search function, *.java and delete).
  • 6. Choose the modules to be distributed with the capsis installer.
    • With a Terminal, change directory to user_cd/capsis4_fc_3apr2009/bin/ and run install (Windows install.bat, Linux install.sh). Choose the customized install and select the modules you want to distribute (ex: only your model). You may keep the default values for the other options. After confirmation, all the other growth / dynamics modules will be removed from the current directory. The Capsis installer will also create a capsis launch script (capsis.bat / capsis.sh).
  • 7. Test carefully the release under construction.
    • From user_cd/capsis4_fc_3apr2009/bin/, run capsis (capsis.bat / capsis.sh) and check if everything is correct by running few simulations and trying the tools you usually use with your model.
  • 8. Clean the release.
    • Remove every file in capsis4_fc_3apr2009/tmp/, remove the data files of the other models in capsis4_fc_103apr2009/data/ and delete capsis.bat (capsis.sh under Linux). The Capsis launch script will be regenerated when the end user will run the Capsis installer on his own machine.
  • 9. Compress the capsis4_fc_3apr2009/ directory into an archive named capsis4_fc_3apr2009.zip in the user_cd directory (do not forget to remove the original capsis4_fc_3apr2009/ directory).
    • Note: this compression is needed if the release is distributed on a read-only support like a cdrom, else all the files will be tagged “read only” resulting in future problems for the end user installation.
  • 10. Copy interesting files in user_cd.
    • The Capsis installation guide in capsis4/html_en/install.html, the java installer by Sun microsystems (ex: the jdk 1.6 - with java compiler - or a jre 1.6 - without java compiler - installer), a tutorial for the end-user explaining the basic use of the software and your model, optionally a copy of the licence file of your module, a readme file explaining the content of the archive, etc.
  • 11. Burn the user_cd/ directory on a cdrom and send to the end user. He will have to install as explained in the install.html file (install java, change the system PATH, decompress Capsis, install Capsis and finally run Capsis).
    • Note: it is highly recommended to test the complete installation of the user cd on another machine before sending it to the end-user.
    • Note: it is suggested to burn a second cdrom for you with all the package directory (included the complete backup) and to keep it in a safe place in case of trouble encountered by the user later. The backup archive will allow to help solve problems later if needed.
documentation/packaging.txt · Last modified: 2014/09/15 08:45 by coligny