====================================
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:

         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.

   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.  For this reason, it's a good idea run
      "ant get-maven-poms" after you update from origin.

      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