Commit 11be8f19 authored by mindthegab's avatar mindthegab
Browse files

-- improved documentation a lot 

-- added release properties
-- removed parent site generation

git-svn-id: http://maven-alfresco-archetypes.googlecode.com/svn/trunk/maven-alfresco-archetypes@45 04253f4f-3451-0410-a141-5562f1e59037
parent 55a16a15

maven-alfresco-amp-archetype/pom.xml

+14 −0
Original line number Diff line number Diff line
@@ -51,6 +51,20 @@ 
				<version>2.0-alpha-3</version>

			</extension>

		</extensions>

		<plugins>

			<plugin>

				<groupId>org.apache.maven.plugins</groupId>

				<artifactId>maven-release-plugin</artifactId>

				<version>2.0-beta-7</version>

				<configuration>

					<!-- useEditMode>true</useEditMode>-->

					<!--  dryRun>true</dryRun-->

					<preparationGoals>clean package</preparationGoals>

					<goals>deploy site:depoy changes:announcement-mail</goals>

					<tagBase>${svn.tags.url}</tagBase>

				</configuration>

			</plugin>

		</plugins>

	</build>

	<distributionManagement>

		<repository>

maven-alfresco-amp-archetype/src/main/resources/archetype-resources/README.txt

+8 −42
Original line number Diff line number Diff line
@@ -64,20 +64,17 @@ all AMP and WAR dependencies specified) also with a sensible default 'alfresco/e 
default alfresco run. Find these test configuaration files in 'src/test/resources' and environment dependent properties in src/test/properties/<env>/application.properties





SOON TO COME:

------------



- Shared configuration (site + release + plugin config) with maven-alfresco-extension-archetype via super POM 





PROJECT LAYOUT

--------------



src --------------------------------------------------------> (source folder)

		|

		|__ main ___ __ resources --------------------------> mapped in the classpath  (alfresco module config goes here, as well as other classpath resources) 

		|			|			  |							  NB: best practice groupId.artifactId=moduleId is used by the archetype and by the AMP unpacker

		|			|			  |__ ex: alfresco/module/com.sourcesense.${artifactId} ---> Example Alfresco module config 

		|__ main ___ __ resources --------------------------> mapped in the classpath. Add here classpath resources

		|			|

		|			|__ config-----   alfresco module config goes here.

		|			|			  |	  Get's copied (by best practice) by build into package alfresco/module/groupId.artifactId.

		|			|			  |   This convention is used by the archetype and by the AMP unpacker.

		|			|			  |__ ex: alfresco/module/com.sourcesense.alfresco.mymodule ---> Example Alfresco module config 

		|			|

		|			|

		|			|__ java ------------------------------->  customization java classes
@@ -92,38 +89,7 @@ src --------------------------------------------------------> (source folder) 
		|			|			  |

		|			|			  |__ local  ------------->  default application.properties

		|			|



		|

		target - Project build dir



FAQ:

----

--- Eclipse configuration

-Run ' mvn eclipse:eclipse ' 

-hit "Refresh" on your Eclipse project



--- Db access problems:

Remember to setup appropriate permissions for selected db / build profile.

You can either edit accordingly and then run: mysql -u root < tools/mysql/db_setup.sql 



or if you use POM property 'alfresco.db.name' you have sql files already filtered (after process-resources phase) in



mysql -u root -p < target/classes/tools/[db_setup,db_remove].sql   



--- Out of memory errors:

Run your build with :

MAVEN_OPTS="-Xms256m -Xmx512m -XX:PermSize=128m" mvn ... ...



--- Content integrity errors on restore running with jetty embedded

Did you remove also alf_data_jetty apart from the alf_jetty db ?



--- Release Problems with LC_ALL

If underlying svn complains about LC_ALL variable please consider running your release prepending:

LC_ALL="C"  (macosx environments, see http://svn.haxx.se/users/archive-2006-07/0320.shtml)



-- Deploy a generally available AMP into a maven repo for dependency usage



mvn deploy:deploy-file -DrepositoryId=repo

-Dfile=/Users/youruser/projectz/alfresco/alfresco-recordsmanagement-2.1.0.amp 

-DgroupId=org.alfresco.community -DartifactId=recordsmanagement -Dversion=2.1.0 

-Dpackaging=amp -Durl=scp://...
 
 No newline at end of file

maven-alfresco-amp-archetype/src/site/apt/layout.apt.vm

0 → 100644
+43 −0
Original line number Diff line number Diff line 
 -----

 Archetype Project Generated Layout

 -----







What do I have when I created the project?



 You will encounter an AMP project structure, filtered with values you provided in creation phase,

 which has the following layout:





------------------------------------------------------------------

 

 

src --------------------------------------------------------> (source folder)

		|

		|__ main ___ __ resources --------------------------> mapped in the classpath. Add here classpath resources

		|			|

		|			|__ config-----   alfresco module config goes here.

		|			|			  |	  Get's copied (by best practice) by build into package alfresco/module/groupId.artifactId.

		|			|			  |   This convention is used by the archetype and by the AMP unpacker.

		|			|			  |__ ex: alfresco/module/com.sourcesense.alfresco.mymodule ---> Example Alfresco module config 

		|			|

		|			|

		|			|__ java ------------------------------->  customization java classes

		|			|

		|			|__ webapp -----------------------------> AMP overlay folder - this folder is overlayed (so may overwrite other dependent AMPs)



		|			

		|__ test __ __ resources _

		|			|			  |

		|			|			  |__ alfresco/extension ---> alfresco overriding Spring contexts

		|			|

		|			|__ properties ------------------------->  environment aware application properties files  

		|			|			  |

		|			|			  |__ local  ------------->  default application.properties

		|			|

		|

		target - Project build dir



------------------------------------------------------------------

maven-alfresco-amp-archetype/src/site/apt/readme.apt.vm

+56 −0
Original line number Diff line number Diff line 
 -----

 Alfresco maven2 AMP lifecycle

 -----





What an AMP is?



	Alfresco Module packages are software modules to be added on top of the Alfresco ECM 

	platform. \ 

	As opposed to Alfresco Extensions (which can be generated with {{{http://repository.sourcesense.com/maven2-sites/maven-alfresco-extension-archetype} maven-alfresco-extension-archetype }})

	which are meant to mainly produce a single customized build of Alfresco, an AMP is a small

	ZIP file primary product of the build lifecyle defined by the 

	

	

---------

	<packaging>amp</packaging>

---------



	POM property. Use this build to create and modules which then can be used as dependencies

	by a maven-alfresco-extension generated project (e.g. enterprise Alfresco WAR customization).

	

	



One command quickstart





-------------

	$ MAVEN_OPTS="-Xms256m -Xmx512m -XX:PermSize=128m" mvn  clean integration-test -P webapp 

----------------





	will runns the jetty embedded with overlayed the currently developed AMP





FEATURES:







	AMP archetype + plugin features:

	

		* AMP customized build :  <<<mvn clean package>>>

		

		* Alfresco webapp integrationt test via war creation and embedded run				 <<<mvn clean integration-test -P webapp>>>

		

		* Install/deployment of Alfresco compatible AMPs on a m2 repo   <<< mvn install / deploy  [ params ] >>>

		

		* using the {{{http://repository.sourcesense.com/maven2-sites/maven-amp-plugin} maven-amp-plugin}} WAR can depend on AMP artifacts and have them overlayed within the maven lifecycle, avoiding the boring MMT run.

		

		* AMP dependencies management: 	<<<mvn clean package>>> can take care of overlay AMP deps

		

		* Error safe single sourcing of POM properties <<<groupId>>> and <<<artifactId>>> used to copy config in the proper package and to ensure consistency 

		



	Specific dependencies and different Alfresco versions can be specified in 'webapp' profile dependecies. Alfresco test webapp is overlayed (apart with 

	all AMP and WAR dependencies specified) also with a sensible default 'alfresco/extension' folder to have a clean safe reproduceable and portable 

	default alfresco run. Find these test configuaration files in 'src/test/resources' and environment dependent properties in src/test/properties/<env>/application.properties

maven-alfresco-amp-archetype/src/site/fml/faq.fml

+39 −13
Original line number Diff line number Diff line
@@ -6,7 +6,8 @@ 
			<question>How do I build an AMP?</question>

			<answer>

				<p>

				Just Run <verbatim> mvn clean package </verbatim>

					Just Run

					<source>mvn clean package</source>

				</p>

			</answer>

		</faq>
@@ -15,7 +16,7 @@ 
			<answer>

				<p>

					You can run Jetty embedded in maven by typing

					<verbatim>mvn clean integration-test -P webapp</verbatim>

					<source>mvn clean integration-test -P webapp</source>

				</p>

			</answer>

		</faq>
@@ -23,11 +24,9 @@ 
			<question>Are AMP transitive dependencies supported?</question>

			<answer>

				<p>

					Yes, they are, both from AMP and WAR packaging projects.

					For AMP projects this  will turn out into having a final built AMP

					which contains all the chain of AMPs the current AMP is depending upon.

					For WAR projects all AMPs will be unpacked in the proper position

					same as the MMT would do.

					Yes, they are, both from AMP and WAR packaging projects. For AMP projects this will turn out into having a final built AMP which

					contains all the chain of AMPs the current AMP is depending upon. For WAR projects all AMPs will be unpacked in the proper

					position same as the MMT would do.

				</p>

			</answer>

		</faq>
@@ -35,12 +34,39 @@ 
			<question>Is MMT needed with maven?</question>

			<answer>

				<p>

					No, it is not. The whole point of it is getting rid of the annoying

					non integrated in the lifecycle MMT run.

					We created the <a href="https://forge.alfresco.com/projects/maven4alfresco" target="_blank" >maven-amp-plugin</a> for 

					managing and processing AMP lifecycle, making MMT obsolete.

					No, it is not. The whole point of it is getting rid of the annoying non integrated in the lifecycle MMT run. We created the

					<a href="https://forge.alfresco.com/projects/maven4alfresco" target="_blank">maven-amp-plugin</a>

					for managing and processing AMP lifecycle, making MMT obsolete.

				</p>

			</answer>

		</faq>

	</part>

	<part id="Developer">

		<title>Developer questions</title>

		<faq id="Eclipse">

			<question>How do I configure Eclipse?</question>

			<answer>

				<ul>

					<li>Run <source> mvn eclipse:eclipse </source></li>

					<li>hit "Refresh" on your Eclipse project</li>

				</ul>

			</answer>

		</faq>

		<faq id="Memory">

			<question>Why I get PermGen or HeapSpace errors</question>

			<answer>

				<p>Run your build with : <source>MAVEN_OPTS="-Xms256m -Xmx512m -XX:PermSize=128m" mvn ...</source> </p>

			</answer>

		</faq>

		<faq id="AMPs">

			<question>How do I deploy a generally available AMP into a maven repo for dependency usage</question>

			<answer>

				<source>

					mvn deploy:deploy-file -DrepositoryId=repo -Dfile=/Users/youruser/projectz/alfresco/alfresco-recordsmanagement-2.1.0.amp

					-DgroupId=org.alfresco.community -DartifactId=recordsmanagement -Dversion=2.1.0 -Dpackaging=amp -Durl=scp://...

				</source>

			</answer>

		</faq>

	</part>



</faqs>
 
 No newline at end of file