Scarab commit: svn commit: r11178 - branches/20120417_mavenPort/site/xdocs: databases howto
[email protected] Tue, 17 Apr 2012 04:13:49 -0700 (PDT)
| Newsgroups | gmane.comp.java.scarab.cvs |
|---|---|
| Message-ID | <[email protected]> |
Author: mcoss
Date: 2012-04-17 04:13:49-0700
New Revision: 11178
Removed:
branches/20120417_mavenPort/site/xdocs/howto/ant-build-howto.xml
Modified:
branches/20120417_mavenPort/site/xdocs/databases/hypersonic.xml
branches/20120417_mavenPort/site/xdocs/howto/build-howto.xml
branches/20120417_mavenPort/site/xdocs/howto/maven-build-howto.xml
branches/20120417_mavenPort/site/xdocs/howto/migrate-howto.xml
branches/20120417_mavenPort/site/xdocs/howto/release-howto.xml
Log:
ENH - Update of xdoc files for new maven 3 build.
Modified: branches/20120417_mavenPort/site/xdocs/databases/hypersonic.xml
Url: http://scarab.tigris.org/source/browse/scarab/branches/20120417_mavenPort/site/xdocs/databases/hypersonic.xml?view=diff&pathrev=11178&r1=11177&r2=11178
==============================================================================
--- branches/20120417_mavenPort/site/xdocs/databases/hypersonic.xml (original)
+++ branches/20120417_mavenPort/site/xdocs/databases/hypersonic.xml 2012-04-17 04:13:49-0700
@@ -15,7 +15,7 @@
Everything you will need for a very basic installation, is already included into Scarab.
</p>
<p>
-Set property for database type:
+Edit your build.properties and the property for database type to:
<source>scarab.database.type=hypersonic</source>
</p>
<p>
@@ -29,7 +29,11 @@
</source>
</p>
<p>
-Then run <source>ant create-db</source> and it should work.
+Then run
+<source>
+mvn clean package -Dmaven.test.skip=true
+mvn initialize scarab:create-db -Dscarab.database.build.mode=sample -DapplicationRoot=target/scarab
+</source> and it should work.
</p>
</section>
</body>
Removed: branches/20120417_mavenPort/site/xdocs/howto/ant-build-howto.xml
Url: http://scarab.tigris.org/source/browse/scarab/branches/20120417_mavenPort/site/xdocs/howto/ant-build-howto.xml?view=markup&pathrev=11177
Modified: branches/20120417_mavenPort/site/xdocs/howto/build-howto.xml
Url: http://scarab.tigris.org/source/browse/scarab/branches/20120417_mavenPort/site/xdocs/howto/build-howto.xml?view=diff&pathrev=11178&r1=11177&r2=11178
==============================================================================
--- branches/20120417_mavenPort/site/xdocs/howto/build-howto.xml (original)
+++ branches/20120417_mavenPort/site/xdocs/howto/build-howto.xml 2012-04-17 04:13:49-0700
@@ -10,7 +10,9 @@
<body>
<section name="The Scarab Build System">
<subsection name="Introduction">
-
+<p>
+This document is for installation of Scarab. Please see <a href="maven-build-howto.html">Maven Build How-To</a> for clearification about the build process itself.
+</p>
<p>
The installation and configuration of Scarab is intended to be as simple as
possible. This document outlines the directory structure of the distribution, the requirements for running Scarab,
@@ -51,35 +53,16 @@
the SDK is included.
</p>
<p>
- When compiling Scarab with Jikes, version 1.18 or higher is
- required. Please do not try with Jikes 1.17, as it is buggy.
+ Compiling Scarab with Jikes, is not supported.
</p>
</li>
-<li>Maven-1.x available from
+<li>Maven-3.0.3 or higher available from
<p>
<code>
<a href="http://maven.apache.org/">http://maven.apache.org/</a>
</code>
</p>
- <p>
- Note: If you prefer to use Ant (see below), you don't need to install Maven.
- If you want to contribute to Scarab Source code, or you need to rebuild all
- bits and pieces of Scarab, you will be more happy with Maven though.
- </p>
-</li>
-
-<li>Ant 1.5 or higher available from
- <p>
- <code>
- <a href="http://ant.apache.org/">http://ant.apache.org/</a>
- </code>
- </p>
- <p>
- If you prefer to use Maven (see above), you don't need to install Ant.
- If you only want to install, configure and use Scarab, Ant is your
- best choice.
- </p>
</li>
<li>Tomcat 4.0.4 or higher available from
@@ -204,7 +187,7 @@
<source>
export MYSQL_HOME=/path/to/mysql-install
export JAVA_HOME=/path/to/jdk-install
-export PATH=${PATH}:${ANT_HOME}/bin:${MYSQL_HOME}/bin:${JAVA_HOME}/bin
+export PATH=${PATH}:${MYSQL_HOME}/bin:${JAVA_HOME}/bin
</source>
<p>
Put these settings into your ~/.bashrc or ~/.login file
@@ -214,7 +197,7 @@
<source>
setenv MYSQL_HOME /path/to/mysql-install
setenv JAVA_HOME /path/to/jdk-install
-setenv PATH ${PATH}:${ANT_HOME}/bin:${MYSQL_HOME}/bin:${JAVA_HOME}/bin
+setenv PATH ${PATH}:${MYSQL_HOME}/bin:${JAVA_HOME}/bin
</source>
<p>
Put these statements into your ~/.cshrc file
@@ -224,7 +207,7 @@
<source>
set MYSQL_HOME=\path\to\mysql-install
set JAVA_HOME=\path\to\jdk-install
-set PATH=%PATH%;%ANT_HOME%\bin;%MYSQL_HOME%\bin;%JAVA_HOME%\bin
+set PATH=%PATH%;%MYSQL_HOME%\bin;%JAVA_HOME%\bin
</source>
<p>
Add these settings to your Environment ( start settings system )
@@ -294,7 +277,8 @@
+- book <-- xml versions of manuals (guides)
+- dtd <-- DTD's
+- repository <-- The .jar repository for jars used by Scarab.
- +- xdocs <-- xml files for maven site (misc documentation files, howtos etc)
+ +- site
+ +- xdocs <-- xml files for maven site (misc documentation files, howtos etc)
</source>
<p>
Within the /src directory you find following subdirectories...
@@ -607,22 +591,14 @@
follows:
</p>
<source>
-with ant:
-
- cd build
- ant
-
-with Maven:
- maven java:compile
- maven war:webapp -Dmaven.test.skip
+ mvn clean package -Dmaven.test.skip=true
</source>
<p>
After the build system finishes, the directory <code>target/scarab</code>
contains the Scarab webapplication. We provide additional informations about
-the <a href="ant-build-howto.html">Ant build system</a>
-and the <a href="maven-build-howto.html">Maven build system</a>
+the Maven build system <a href="maven-build-howto.html">here</a>
</p>
<p>
NOTE: Make sure that your TOMCAT_HOME environment variable is defined
@@ -656,7 +632,7 @@
<p>
NOTE: You should use the copy of Xerces that is included with Scarab
and make sure that no other copies of Xerces are in your
- JAVA_HOME, ANT_HOME or your CLASSPATH. Otherwise,
+ JAVA_HOME, or your CLASSPATH. Otherwise,
you may get build errors.
</p>
@@ -670,7 +646,7 @@
binaries into your PATH environment variable.
</p>
<p>
-Simply put, the idea is that the database creation scripts and the Java
+The idea is that the database creation scripts and the Java
database driver (JDBC) need the ability to connect to the database. In
order to do this, the code needs to be given a host machine, database
name, database-username and password.
@@ -682,14 +658,9 @@
access, you can simply execute the following:
</p>
<source>
-with ant:
- cd build
- ant create-db
+ mvn clean initialize scarab:create-db
-with Maven:
-
- maven scarab:create-db
</source>
<p>
If you need to specify a host/username/password/databasename, you will
@@ -707,20 +678,13 @@
You find more informations about the settings in <code>project.properties</code>
</p>
<p>
-NOTE: If you would like to only load the required database data and not
- the sample/default data, you can do so by passing the property
-</p>
- <source>ant create-db -Dskip.sample.data=true -Dskip.default.data=true -Dskip.jira.templates.data=true</source>
-<p>
- to your JVM upon startup of the build processs or by adding the
- same property to your <i>build.properties</i>:
+NOTE: If you would like to load not only the required database data, e.g.
+ the sample/default data, you can do so by passing the property <i>scarab.database.build.mode</i>,
+ see <a href="maven-build-howto.html">Maven Build</a> for more informations.
</p>
- <code>skip.sample.data=true
- ...
- </code>
<p>
NOTE: The create scripts will attempt to first drop your scarab database
- and then recreate it. If you execute "ant create-db", all of your
+ and then recreate it. If you execute "mvn clean initialize scarab:create-db", all of your
previous data in that database will be lost without warning!
</p>
<p>
Modified: branches/20120417_mavenPort/site/xdocs/howto/maven-build-howto.xml
Url: http://scarab.tigris.org/source/browse/scarab/branches/20120417_mavenPort/site/xdocs/howto/maven-build-howto.xml?view=diff&pathrev=11178&r1=11177&r2=11178
==============================================================================
--- branches/20120417_mavenPort/site/xdocs/howto/maven-build-howto.xml (original)
+++ branches/20120417_mavenPort/site/xdocs/howto/maven-build-howto.xml 2012-04-17 04:13:49-0700
@@ -4,7 +4,7 @@
<properties>
<title>How to Build Scarab</title>
- <author email="[email protected]">Eric Pugh</author>
+ <author email="opensource@memocomp">Johannes Höchstädter</author>
</properties>
<body>
@@ -12,35 +12,44 @@
<section name="Maven Build">
-<subsection name="Intro">
+<subsection name="Introduction">
<p>
In the early days of Scarab the build system was entirely based on Ant.
-We have recently switched over to use Maven as our primary build system.
-But for quite a few reasons we continue supporting an
-<a href="ant-build-howto.html">Ant based</a> build.
+We have recently switched over to use Maven 1.x and then to <a href="http://maven.apache.org">Maven 3.0.3 upwards</a> as our primary build system.
</p>
<p>
-The new Maven based build system allows to build a Scarab instance from
+The Maven based build system allows to build a Scarab instance from
the Source distribution and in addition adds all functionality to build
-the documentation-set, update the jar-repository and so on.
+the database, documentation-set, update the jar-repository and so on.
</p>
+</subsection>
+<subsection name="Prerequisites">
+<p>
+Maven build is customized with the file <i>build.properties</i>.
+The location of this file is in the Scarab root directory.
+Create it from one of the already existing property files, e.g. <i>minimal.properties</i>, and adapt it to your needs, e.g the database configurations.
+The file <i>build.properties</i> is an absolutely necessary prerequisite for the build system, see <a href="build-howto.html">chapter for installation</a>, too.
+</p>
+<code>$SCARAB_ROOT/build.properties</code>
<p>
-<font color="red">NOTE:</font> Like Ant the Maven build can be customized
-with the file <i>build.properties</i> . But beware, the location of this
-file is now the Scarab root directory. Otherwise Maven would not see this
-file. The Ant build system has been modifyed to use the same build.properties
-file, hence you can even intermix the usage of Ant and Maven without any
-problems. If you are upgrading from an old system, please ensure, that
-your old build.properties file migrates to
+Before you are able to build, you have to install the follwing dependencies, which are special by license or version. See Scarab directory www/repository and pom.xml accordingly.</p>
+<ul>
+<li>turbine-20041117.142852.jar</li>
+<li>jndi-1.2.1.jar</li>
+<li>fulcrum-parser-1.0.2-dev-r223202-patched.jar</li>
+</ul>
+<p>
+You will need Scarab's own maven plugin: org.tigris.scarab.scarab-maven-plugin.
</p>
-<code>$SCARAB_ROOT/build.properties</code>
+</subsection>
+<subsection name="Default Build">
<p>
In most cases you will utilize Maven as follows:
<source>
1:> cd $SCARAB_ROOT
-2:> maven war:webapp -D maven.test.skip
-3:> maven scarab:create-db
+2:> mvn clean initialize scarab:create-db
+3:> mvn clean package
</source>
This will setup the database and build Scarab's webapp in target/ directory.
@@ -50,28 +59,18 @@
</p>
</subsection>
-
-<subsection name="Build sources">
-<p>
- <source>maven java:compile</source>
- This will simply compile Scarab and the various Torque objects.
-</p>
-</subsection>
-
-
<subsection name="Generating Database">
<p>
You can generate your database by doing this:
- <source>maven scarab:create-db</source>
+ <source>mvn clean initialize scarab:create-db</source>
This will create in <code>/target/sql</code> the various SQL files
that you need. It will also install the database for certain types
of databases.
</p>
<p>
- If you want to create the database without sample data (example
- data for test purposes) you can call maven as follows:
- <source>maven -Dskip.sample.data=true scarab:create-db</source>
+ Use the property scarab.database.build.mode if you want to create the database with or without sample, or default data. The basic build, as described above,
+ will build the schema, inculding the required data, only. See section for <a href="#properties">Scarab Maven Properties</a>.
</p>
</subsection>
@@ -79,36 +78,21 @@
<subsection name="Testing the code">
<p>
To test that everything is working properly, you should run the unit tests!
- <source>maven test</source>
- This will compile your newly generated Torque classes and run the unit
- tests. One thing to note is that in <code>/src/test/</code> are some
- config files that you probably will need to update the database
- settings for.
+ <source>mvn clean test</source>
+ This will compile your newly generated Torque and Scarab classes and run the unit
+ tests.
</p>
</subsection>
<subsection name="Generating the documentation">
<p>
If you want to generate the entire site documenation, then you can run
- <source>maven site</source>
- or, if you don't want to execute the unit tests (maybe they are failing)
- <source>maven site -Dmaven.test.skip</source>
+ <source>mvn clean initialize site</source>
</p>
-
-<p>
- If you want to see only the subset of the documenation, which is
- generated from the xml-sources (the Scarab documentation manuals and
- Howto's), then you can run
- <source>maven xdoc:transform</source>
- This call is significantly faster than generating the whole site
- (order of seconds vs. order of minutes).
-</p>
-
</subsection>
-
<subsection name="Creating a WAR file">
<p>
Once things are to your liking you can use Maven to generate your WAR file:
- <source>maven war</source>
+ <source>mvn clean package</source>
This will compile Scarab, run the unit tests, and then generate
in <code>/target</code> a WAR file that you can then use to deploy
to any Servlet container.
@@ -117,31 +101,17 @@
<subsection name="Updating the www/repository">
<p>
-The www/repository is mainly used for the Ant build, because with
-ant it is not so easy to dynamically grab jar files from the network.
-Besides this we decided to also support offline generation when an
-online access to the network is not available. Therefore the www/repository
-contains all bits and pieces needed to build Scarab.
-</p>
-<p>
-It is not very handsome to maintain the www/repository by hand. Therefore
-we have provided a Maven goal, that automatically updates the www/repository
-according to the maven dependency file. If you want to perform such an
-update (e.g. because you want to check in a new jar file or simply want to
-maintain the repository) you can call:
-<source> maven scarab:update-repo</source>
-This goal will remove unneeded jars from the repository and add
-needed jars to it. Maven gathers the jars from the network if needed.
+TODO, see SCOF156
</p>
</subsection>
<subsection name="Clean target">
<p>
Run the following goal to clean everything back up:
- <source>maven clean</source>
+ <source>mvn clean</source>
</p>
</subsection>
</section>
-<section name="Scarab Maven Properties">
+<a name="properties" /><section name="Scarab Maven Properties">
<table>
<tr>
<th>Property name</th>
@@ -149,27 +119,27 @@
<th>Description</th>
</tr>
<tr>
- <td>scarab.scarabgen.home=../scarab-gen</td>
+ <td>scarab.database.build.mode</td>
<td>Yes</td>
<td>
- Location of the scarab-gen project.
+ Mode value to fill the database during build. Use "basic" (default value), "default" or "sample" here.
</td>
- </tr>
- <tr>
- <td>scarab.docs.head=${scarab.scarabgen.home}/www/head</td>
+ </tr>
+ <tr>
+ <td>scarab.database.build.drop</td>
<td>Yes</td>
<td>
- Where to store the HEAD version of the documentation.
+ Set this if you want to be sure not to loose all your data during build. Use "true" to drop the current database (default) or "false" to prevent your database to be dropped.
+ But be warned, if you set this property value to "false" not all database scripts may work correctly, because of duplicates.
</td>
- </tr>
- <tr>
- <td>scarab.docbook.enable=true</td>
+ </tr>
+ <tr>
+ <td>maven.test.skip</td>
<td>Yes</td>
<td>
- Whether to transform docbook documentation. Turn it off if you aren't connected to the
- internet!
+ Alawys good to skip unit tests for building. Use "true" to skip maven tests or "false" (default).
</td>
- </tr>
+ </tr>
</table>
</section>
</body>
Modified: branches/20120417_mavenPort/site/xdocs/howto/migrate-howto.xml
Url: http://scarab.tigris.org/source/browse/scarab/branches/20120417_mavenPort/site/xdocs/howto/migrate-howto.xml?view=diff&pathrev=11178&r1=11177&r2=11178
==============================================================================
--- branches/20120417_mavenPort/site/xdocs/howto/migrate-howto.xml (original)
+++ branches/20120417_mavenPort/site/xdocs/howto/migrate-howto.xml 2012-04-17 04:13:49-0700
@@ -9,6 +9,7 @@
<body>
<section name="Scarab Migration Guide">
+<subsection name="Introduction">
<p>
This document outlines data migration between versions of Scarab.
It aplies only for already existing installations, which are upgrading
@@ -22,12 +23,13 @@
WARNING: Before performing any of the operations outlined by this
document, please BACKUP YOUR DATABASE!!!
</p>
+</subsection>
<subsection name="Upgrading the database">
<subsection name="The quick step migration procedure">
<ul>
- <li>We assume, you have already built the "b21" web application either with Ant or with Maven. It is the same for other versions, too, e.g. "22".</li>
+ <li>We assume, you have already built the "b22" web application with Maven.</li>
<li>Change to the build/ directory of your generated web application and run the appropriate target for the predecessor's version number, e.g. for "b21":
- <source>ant migrate-from-b20</source></li>
+ <source>mvn clean scarab:migrate-1b20-to-1b21</source></li>
<li>
<p>REMEMBER: Not all the information is inside the database!</p>
<p>
@@ -114,7 +116,10 @@
</subsection>
</subsection>
-<subsection name="Migrating from older releases">
+<subsection name="Migrating for older releases">
+<p>
+This obviously outdated section is kept because of backwards compatibility reasons, but there should be still some of the migration tasks working for Maven, as stated in section above.
+</p>
<source>
,-------------------------------------------------------------------------.
| 2. Migrating from older releases |
Modified: branches/20120417_mavenPort/site/xdocs/howto/release-howto.xml
Url: http://scarab.tigris.org/source/browse/scarab/branches/20120417_mavenPort/site/xdocs/howto/release-howto.xml?view=diff&pathrev=11178&r1=11177&r2=11178
==============================================================================
--- branches/20120417_mavenPort/site/xdocs/howto/release-howto.xml (original)
+++ branches/20120417_mavenPort/site/xdocs/howto/release-howto.xml 2012-04-17 04:13:49-0700
@@ -11,11 +11,13 @@
<body>
<section name="Preparations before cutting">
+<subsection name="Introduction">
<p>
Basically you need to test and build the distribution, and
then build and commit the generated documentation.
</p>
- <a name="buildtest"/><subsection name="Building a Distribution">
+</subsection>
+<a name="buildtest"/><subsection name="Building a Distribution">
<p>
Make sure your working copy has no local modifications and is
up-to-date. Starting with a fresh copy is recommended using:
@@ -26,9 +28,9 @@
<p>
Build and execute tests.
<source>
- maven -Dmaven.test.skip=true
- maven scarab:create-db
- maven test
+ mvn clean initialize scarab:create-db -Dscarab.database.build.mode=sample
+ mvn clean package -Dmaven.test.skip=true
+ mvn test
</source>
</p>
<p>
@@ -38,14 +40,13 @@
Edit scarab/scarab_properties.xml and change the
property with name "version" removing the "-dev" appendix from
the final version number for the release.<br/>
- Do the same in the <currentVersion> tag in project.xml file.
+ Do the same in the <version> tag in pom.xml file.
</p>
<p>
Run the property file generator and update the www/repository:
<source>
- maven scarab:update-repo
- maven scarab:update-properties
+ mvn initialize scarab:update-properties
</source>
</p>
@@ -86,10 +87,9 @@
<p>
Build a source release.
This will create a .tar.gz and a .zip file in
- the scarab directory.
+ the target directory.
<source>
- cd scarab/build
- ant package
+ mvn clean assembly:single -Dmaven.test.skip=true
</source>
</p>
</subsection>
@@ -102,12 +102,12 @@
Edit scarab/xdocs/scarab_properties.xml and change the
property with name "version" to the next version with the "-dev" appendix from
the final version number for the release.<br/>
- Do the same in the <currentVersion> tag of project.xml file.
+ Do the same in the <version> tag of pom.xml file.
</p>
<p>
Update the property files again.
<source>
- maven scarab:update-properties
+ mvn initialize scarab:update-properties
</source>
</p>
<p>
------------------------------------------------------
http://scarab.tigris.org/ds/viewMessage.do?dsForumId=3577&dsMessageId=2949086