On Tue, Apr 28, 2009 at 9:18 AM, Mike Edwards <[email protected]> wrote: > Mike Edwards wrote: >> >> Ant, >> >> I'd prefer to see a bit more user documentation first. >> >> I'm unclear as to what exactly it does and how to run it properly. >> That's why I'm not voting for it. (note that I have not voted against >> it either...) >> >> Yours, Mike. >> > First, I'd like to make it clear that I'm NOT picking on this release - but > I am keen to see more and better end user documentation for everything we > have in Tuscany. So expect me to be more picky with any release of > anything. > > As a first step for THIS release, here is a suggested improvement to the > documentation which I hope will make it clearer to users what it is for and > how it is used. > > > Yours, Mike. > > > User Documentation > __________________ > > This module is a Maven plugin which supports the creation of a zip format > SCA contribution from > the contents of a Maven project. An SCA contribution can be deployed to the > Tuscany SCA runtime > and run as an application. > > One of the main uses for an SCA zip contribution is that the SCA zip > contribution can contain > Java jar files within the zip and those jar files are available to the Java > classloader of the > contribution. This enables the packaging of application Java classes along > with any other Jar files > which they depend on in one contribution file. As a result the single zip > file can hold everything > that's needed for the SCA application other than the Tuscany runtime itself > - in one neat package. > > The zip Maven plugin is used by adding a section into <build/> portion of > the pom.xml of the Maven > project which relates to the maven zip plugin. It is also necessary for the > packaging of the output > of the project to be declared as "zip". Then run Maven in the project. > > This zip plugin builds the output of the project as an SCA zip archive and > it includes any > jar files from dependencies declared by the project, where those dependency > jar files are placed > into the zip archive in a folder with the name "lib". > > > An outline of a pom.xml including the zip plugin statements: > > ... > <!-- output packaging format is "zip" --> > <packaging>zip</packaging> > ... > <build> > ... > <!-- section referencing the Tuscany zip plugin --> > <plugins> > ... > <plugin> > <groupId>org.apache.tuscany.maven.plugins</groupId> > <artifactId>maven-zip-plugin</artifactId> > <extensions>true</extensions> > </plugin> > ... > </plugins> > </build> > > > Here is an example pom.xml containing the Tuscany zip plugin material: > > <?xml version="1.0" encoding="UTF-8"?> > <project xmlns="http://maven.apache.org/POM/4.0.0"; > xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"; > xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 > http://maven.apache.org/maven-v4_0_0.xsd";> > > <modelVersion>4.0.0</modelVersion> > > <parent> > <artifactId>tuscany-sca</artifactId> > <groupId>org.apache.tuscany.sca</groupId> > <version>2.0-SNAPSHOT</version> > </parent> > <groupId>org.inglenook.test1</groupId> > <artifactId>mikestest</artifactId> > <packaging>zip</packaging> > <version>1.0-SNAPSHOT</version> > <name>quickstart</name> > > <dependencies> > <!-- TUSCANY DEPENDENCIES --> > <dependency> > <groupId>org.apache.tuscany.sca</groupId> > <artifactId>tuscany-sca-api</artifactId> > <version>${tuscany.version}</version> > <scope>provided</scope> > </dependency> > > <!-- AN EXAMPLE APPLICATION DEPENDENCY TO BE INCLUDED IN ZIP --> > <dependency> > <groupId>commons-io</groupId> > <artifactId>commons-io</artifactId> > <version>1.4</version> > </dependency> > > <!-- JUNIT DEPENDENCY FOR TESTING --> > <dependency> > <groupId>junit</groupId> > <artifactId>junit</artifactId> > <version>3.8.2</version> > <scope>test</scope> > </dependency> > > </dependencies> > <build> > <defaultGoal>install</defaultGoal> > <finalName>${artifactId}</finalName> > <resources> > <resource> > <directory>src/main/resources</directory> > </resource> > <resource> > <directory>src/main/java</directory> > <includes> > <include>**</include> > </includes> > <excludes> > <exclude>**/*.java</exclude> > </excludes> > </resource> > </resources> > <testResources> > <testResource> > <directory>src/test/java</directory> > <includes> > <include>**</include> > </includes> > <excludes> > <exclude>**/*.java</exclude> > </excludes> > </testResource> > </testResources> > <plugins> > <plugin> > <inherited>true</inherited> > <groupId>org.apache.maven.plugins</groupId> > <artifactId>maven-compiler-plugin</artifactId> > <configuration> > <source>1.5</source> > <target>1.5</target> > <optimise>true</optimise> > <debug>true</debug> > </configuration> > </plugin> > <plugin> > <groupId>org.apache.maven.plugins</groupId> > <artifactId>maven-eclipse-plugin</artifactId> > <configuration> > <downloadSources>true</downloadSources> > </configuration> > </plugin> > <plugin> > <groupId>org.apache.tuscany.maven.plugins</groupId> > <artifactId>maven-zip-plugin</artifactId> > <extensions>true</extensions> > </plugin> > <plugin> > <groupId>org.apache.tuscany.maven.plugins</groupId> > <artifactId>maven-tuscany-plugin</artifactId> > </plugin> > </plugins> > </build> > <properties> > <tuscany.version>2.0-SNAPSHOT</tuscany.version> > </properties> > </project> > > > TODOs: > - make the "lib/" folder where the dependent jars go configurable > - make which dependencies get included configurable > (currently its those with compile or runtime scope) >
Thanks for the great doc update Mike, I've added that to SVN and re done the release to include the update, see the new vote thread - http://mail-archives.apache.org/mod_mbox/tuscany-dev/200904.mbox/%[email protected]%3e ...ant
