/*
 * Date   : $Date: 2013/02/25
 * Version: $Revision: 1.6 $
 *
 * This file is part of opencmsantbuild -
 * the Open Source OpenCms ANT build project.
 *
 * Copyright (c) 2010 Achim Westermann
 *
 * Additions ssh and antform Copyright (c) 2013 Marc Johnen (http://www.johnen.biz)
 * 
 */

How to start local development with eclipse?

1. Under Eclipse choose "File->Import->Existing project into Workspace" and select the parent folder of this file.
2. adjust the properties in ant-opencmsantbuild.properties (and ant-opencmsantbuild-live.properties)
3.a) Right click build.xml and chose "Run As -> ANT build" to open the gui. 
  b) or Right click opencms-build.xml and chose "Run As -> ANT build" to use without gui	
     This will start the module build of the demo module given in the property "module.module.name" of build.xml.
    
   Watch the output to see where the generated module is written to. 
4. Have a look at the build.xml to see the options for generating modules. 
5. Have a look at the build tree to get familiar with it. 

Start the gui via commandline:

cd scripts/
ant -lib ../lib/build/

How to add new files to the build tree (helloworld.jsp)? 

1. Create the file in the module folder below the vfscontent folder at the desired location <folder>.  
2. Also create <folder>/__properties/helloworld.jsp.properties. 
3. Add at least one entry in that file: 
   a) FileInfo.type = jsp 
4. Run the build and see if it works. 


How to add new resource types to the module? 

Just have a look at 
/modules/info.monitorenter.opencms.minimaldemo/resourcetypes.xml 
/modules/info.monitorenter.opencms.minimaldemo/explorertypes.xml 

How to import an existing module to the build tree (without gui, using the opencms-build.xml)? 

1. Set the property "module.module.name" to the name of the module to import. For the module "org.opencms.welcome_7.5.2.zip" 
   for example you have to use the value "org.opencms.welcome". 
2. Check the property "module.vfs2cvs.importfolder". It's value points to the directory where you have to put the module 
   to import. If it does not exist, create it first. Then place your module into it. 
3. Run the build.xml target OpenCmsModule_TO_IDE. This should create you a complete directory tree below /modules/<modulename>. 
   Caution currently this task finally deletes the module you put into the import folder. This is necessary to avoid potential 
   ambiguities when grabbing the module from the folder. 

If you have a local application server with OpenCms that carries your module you could also have a look at the task 
VFS_To_IDE. For this provide the correct settings in ant-opencmsantbuild.properties and ant-opencmsantbuild-live.properties for: 
opencms.username 
opencms.password
and other properties

and run the target "VFS_To_IDE" in opencms-build.xml or use the Antform

Something does not work. My build tree seems to be broken or this build environment. How do I investigate?

Add the flags "-verbose -debug" to your ANT build. This creates a lot of output. Within Eclipse you do this by 
"Run -> External Tools -> External Tools Configuration..." in the "Main" Tab in the "Arguments" text box. 


How does the build environment deal with siblings (OpenCms VFS files)?

- siblings are to visible files in VFS that share the same content. If you modify one file the other files content is also changed.
- siblings allow to show the same content with different representations (e.g. via different template properties)
- siblings allow to serve the same file under different URLs while an update to the file will be reflected for all urls.

-> Within the OpenCms module manifest.xml siblings are identified by:
- A missing <source> entry for all further siblings, only one <source> among all siblings pointing to one content file.
- The same <uuidresource> among all sibling files.
- Different <uuidstructure> and <destinatioin> entries for all siblings.

I wanted to avoid duplicate content files within the build tree for siblings as the results would be unpredictable. 
So siblings are dealt in the following way:
- Only one content file.
- For every further sibling another properties file with the same resource id but different structure id.  


How to handle module version within your ANT build? 

You can rely on the built-in mechanism. It checks the module info xml file which you specify via the "moduleinfo" 
attribute for the <version> node and uses the value for naming the generated module.zip. 
If you want your own version number management use the "moduleVersion" attribute in your build xml to specify the number. 

After the createmanifestxml task has been running successfully a property will have been set in your build with the 
name "module.version". Access this like: <sometask someattribute="mymodule-${module.version}".../>. Beware that 
this property can only be set by the task if you did not set a property with the same name before! 
