<?xml version="1.0" encoding="ISO-8859-1"?>
<!-- 
/****************************************************************
 * Licensed to the Apache Software Foundation (ASF) under one   *
 * or more contributor license agreements.  See the NOTICE file *
 * distributed with this work for additional information        *
 * regarding copyright ownership.  The ASF licenses this file   *
 * to you under the Apache License, Version 2.0 (the            *
 * "License"); you may not use this file except in compliance   *
 * with the License.  You may obtain a copy of the License at   *
 *                                                              *
 *   http://www.apache.org/licenses/LICENSE-2.0                 *
 *                                                              *
 * Unless required by applicable law or agreed to in writing,   *
 * software distributed under the License is distributed on an  *
 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY       *
 * KIND, either express or implied.  See the License for the    *
 * specific language governing permissions and limitations      *
 * under the License.                                           *
 ****************************************************************/

 -->
<document>
    <properties>
        <title>Building mime4j</title>
    </properties>
    <body>
        <section name="Building mime4j">
            <subsection name="Using a Stable Release">
            <p> Go to the <a href="http://james.apache.org/download.cgi">download 
              pages</a> and download the most recent
                release in your preferred format, either
                <code>james-mime4j-x.y-src.tar.gz</code> or <code>james-mime4j-x.y-src.zip</code>.
                Extracting the archived sources will create the directory
                <code>james-mime4j-x.y/</code>.</p>
            </subsection>
            <subsection name="Checking Out From Subversion">
                <p>
                    Issue the following commands in a shell:
                    <blockquote>
                        <code>svn checkout http://svn.apache.org/repos/asf/james/mime4j/trunk james-mime4j</code><br/>
                    </blockquote>
                </p>
            </subsection>
            <subsection name="Download and Install Maven">
                <p> You will need to download and install <a
                    href="http://maven.apache.org/">Maven</a> before building
                    the sources. The build has been tested with version 2.0 of
                    Maven so use this or a later version if possible. </p>
                <p> One of the main differences between Maven and plain ant is
                    that Maven manages external dependencies for your projects
                    and (at least in theory) you should no longer have to store
                    third-party jar files in your source code tree. It maintains a local
                    repository of versioned libraries and shares them between
                    your Maven projects. If it can't find the necessary files
                    there it will attempt to download them from the main Maven
                    repository at www.ibiblio.org/maven. So to use the Maven
                    build, you need to have a network connection available for
                    the inital download of the project dependencies. </p>
            </subsection>
            <subsection name="Building the mime4j Jar">
                <p> Once Maven has been installed, building the project should
                    be as simple as typing <blockquote>
                        <code>cd james-mime4j-x.y/ (cd james-mime4j/ if sources come from
                            Subversion)<br/>mvn package</code>
                    </blockquote> from the command line. Maven will
                    automatically run all test cases for you and create the
                    jar file in the <code>target</code> directory. 
                </p>
                <p>
                    To install the jar into your local Maven repository run <blockquote>
                        <code>mvn install</code></blockquote>
                </p>
                <p>
                    To generate an Eclipse project from the sources run <blockquote>
                        <code>mvn eclipse:eclipse</code></blockquote>
                </p>
                <p>
                  <strong>NOTE!</strong> Mime4j uses <a href="https://javacc.dev.java.net/">JavaCC</a> to generate parsers for
                  header fields. If you're using an old version of maven eclipse pluing
                  <code>mvn eclipse:eclipse</code> could have problems  
                  generating proper source folders for the JavaCC generated code.
                  After running <code>mvn eclipse:eclipse</code> you must manually
                  add <code>target/generated-sources/javacc</code> and 
                  <code>target/generated-sources/jjtree</code> as source folders
                  under <em>Project -&gt; Properties</em> in Eclipse.
                </p>
                <p>
                    For more information on using
                    Maven, have a look at the <a
                        href="http://maven.apache.org/">Maven web site</a>. </p>
            </subsection>
        </section>
    </body>
</document>