lucene/dev-tools/maven

====================================
Lucene/Solr Maven build instructions
====================================

Contents:

A. How to use nightly Jenkins-built Lucene/Solr Maven artifacts
B. How to generate Maven artifacts
C. How to deploy Maven artifacts to a repository
D. How to use Maven to build Lucene/Solr

-----

A. How to use nightly Jenkins-built Lucene/Solr Maven artifacts

   The most recently produced nightly Jenkins-built Lucene and Solr Maven
   snapshot artifacts are available in the Apache Snapshot repository here:

      http://repository.apache.org/snapshots

   An example POM snippet:

     <project ...>
       ...
       <repositories>
         ...
         <repository>
           <id>apache.snapshots</id>
           <name>Apache Snapshot Repository</name>
           <url>http://repository.apache.org/snapshots</url>
           <releases>
             <enabled>false</enabled>
           </releases>
         </repository>


B. How to generate Lucene/Solr Maven artifacts

   Prerequisites: JDK 1.8+ and Ant 1.8.2+

   Run 'ant generate-maven-artifacts' to create an internal Maven
   repository, including POMs, binary .jars, source .jars, and javadoc
   .jars.

   You can run the above command in three possible places: the top-level
   directory; under lucene/; or under solr/.  From the top-level directory
   or from lucene/, the internal repository will be located at dist/maven/.
   From solr/, the internal repository will be located at package/maven/.


C. How to deploy Maven artifacts to a repository

   Prerequisites: JDK 1.8+ and Ant 1.8.2+

   You can deploy targets for all of Lucene/Solr, only Lucene, or only Solr,
   as in B. above.  To deploy to a Maven repository, the command is the same
   as in B. above, with the addition of two system properties:

      ant -Dm2.repository.id=my-repo-id \
          -Dm2.repository.url=http://example.org/my/repo \
          generate-maven-artifacts

   The repository ID given in the above command corresponds to a <server>
   entry in either your ~/.m2/settings.xml or ~/.ant/settings.xml.  See
   <http://maven.apache.org/settings.html#Servers> for more information.
   (Note that as of version 2.1.3, Maven Ant Tasks cannot handle encrypted
   passwords.)


D. How to use Maven to build Lucene/Solr

   In summary, to enable Maven builds, perform the following:

         svn update
         ant get-maven-poms
         cd maven-build

   The details, followed by some example Maven commands:

   1. Prerequisites: JDK 1.8+ and Maven 2.2.1 or 3.X

   2. Make sure your sources are up to date.  If you checked your sources out
      from the Apache Subversion repository, run "svn update" from the top
      level.

   3. Copy the Maven POM templates from under dev-tools/maven/ to the
      maven-build/ directory using the following command from the top-level
      directory:

         ant get-maven-poms

      Note that you will need to do this whenever changes to the POM
      templates are committed.  It's a good idea to follow every "svn update"
      with "ant get-maven-poms" for this reason.

      The above command copies all of the POM templates from dev-tools/maven/,
      filling in the project version with the default "X.X-SNAPSHOT".  If you
      want the POMs and the Maven-built artifacts to have a version other than
      the default, you can supply an alternate version on the command line
      with the above command, e.g. "my-special-version":

         ant -Dversion=my-special-version get-maven-poms

      or to append "my-special-version" to the current base version, e.g. 5.0,
      resulting in version "5.0-my-special-version":

         ant -Ddev.version.suffix=my-special-version get-maven-poms

      Note: if you change the version in the POMs, there is one test method
      that will fail under maven-surefire-plugin:
      o.a.l.index.TestCheckIndex#testLuceneConstantVersion().  It's safe to
      @Ignore this test method, since it's just comparing the value of the
      lucene.version system property (set in the maven-surefire-plugin
      configuration in the lucene-core POM) against a hard-wired official
      version (o.a.l.util.Constants.LUCENE_MAIN_VERSION).

   4. To remove the maven-build/ directory and its contents, use the following
      command from the top-level directory:

         ant clean-maven-build


   Some example Maven commands you can use after you perform the above
   preparatory steps:

   - Compile, package, and install all binary artifacts to your local
     repository:

         mvn install

     After compiling and packaging, but before installing each module's 
     artifact, the above command will also run all the module's tests.

   - Compile, package, and install all binary artifacts to your local
     repository, without running any tests:

         mvn -DskipTests install

   - Compile, package, and install all binary and source artifacts to your
     local repository, without running any tests:

         mvn -DskipTests source:jar-no-fork install

   - Run all tests:

         mvn test

   - Run all test methods defined in a test class:

         mvn -Dtest=TestClassName test