hc-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Apache Wiki <wikidi...@apache.org>
Subject [Jakarta-httpclient Wiki] Update of "HttpComponentsBuildProcess" by RolandWeber
Date Sun, 27 Aug 2006 11:44:25 GMT
Dear Wiki user,

You have subscribed to a wiki page or wiki category on "Jakarta-httpclient Wiki" for change

The following page has been changed by RolandWeber:

The comment on the change is:
New page about build processes. General stuff about new Ant build, for starters.

New page:
#pragma section-numbers 2

= HttpComponents Build Process =

== About ==

The HTTP components are a set of modules for mixing and matching the
functionality required by a specific application. This poses some
challenges for the build process, compared to the monolithic
[http://jakarta.apache.org/httpclient/ HttpClient].
This document describes the build process(es) used for [http://jakarta.apache.org/httpcomponents/
It is intended for people that want to or need to compile the
HTTP component source code, like committers, patch contributors,
forkers, and everyone else who wants to try.


== Introduction ==

Http''''''Components employ two separate and independent build processes.
[http://maven.apache.org/ Maven] is used to create releases and to
generate the web site.
[http://ant.apache.org/ Ant] is used for Gump. It also offers
additional build targets not supported by Maven, such as compiling
the examples and unsupported contribution classes.

== Directory Structure ==

Http''''''Components source code is maintained in a
[http://subversion.tigris.org/ Subversion] repository.
You can check out the most recent code, called the trunk, from
[http://svn.apache.org/repos/asf/jakarta/httpcomponents/project-trunk/ project-trunk]
(committers: use
[https://svn.apache.org/repos/asf/jakarta/httpcomponents/project-trunk/ https]).
Online access to that URL is of limited value, since each component has
it's own directory tree and is referenced from the project-trunk as an
external item, a kind of symbolic link. To browse the source code online,
switch to the parent directory of the project-trunk, then select the
individual component you want to browse, and there the trunk directory.
When checking out the project-trunk, you will find the following directories:

 * {{{project/}}} -
 Http''''''Components web site and a few resources shared by several components
 * {{{httpcore/}}} -
 Http''''''Core, including the modules "main" and "nio"
 * {{{httpclient/}}} -
 * {{{httpasync/}}} -
 * {{{norobots-rfc/}}} -
 A parser for robots.txt files.
 * {{{tcconnector/}}} -
 A [http://tomcat.apache.org/ Tomcat] Coyote [http://tomcat.apache.org/connectors-doc/ connector]
based on Http''''''Core.

In each of these directories, you will find a file called
{{{pom.xml}}} if it supports the Maven based build process, or a file called
{{{build.xml}}} if it supports the Ant based build process, or both.

== Maven ==

''This is work in progress. (anyone wants to help me out here?)''

 * tool is Maven2
 * components don't depend on parent directory structure
 * Maven repository
 * 'mvn package' remains within component's directory tree
 * 'mvn install' copies build result into local repository for other components
 * site plugin, targets for generating the web sites?

== Ant ==

There are two versions of the Ant build process. The traditional one depends
on a central file called {{{build.properties}}} in the {{{project/}}} component.
It is being phased out and replaced with a new build process which also
relies on an external properties file, but does not require a specific
location for it. Http''''''Core and Http''''''Async are updated, the other components
will follow. The description here applies only to the '''new''' Ant build process.

=== Standard Build Targets ===

The Ant based build process defines standard build targets across
all components. To execute a build target, change to the base directory
of a component and type "ant <target-name>". For many targets you will
have to define some external dependencies before they can execute correctly.
If you want to try out the build process quickly, use the '-src' targets
in Http''''''Core. They do not have external dependencies.
There are targets for building JARs, for generating Java''''''Docs, and for
running unit tests. By default, intermediate results like compiled classes
will be put below directories called target/, final build results like JARs or
Java''''''Doc in a directory called dist/ directly in the component base directory.

 package-src, package-src-fs::
 Builds the JAR file holding all the classes that are found in the distributable JAR for the
component. '''package-src''' compiles classes as required, '''package-src-fs''' (from scratch)
first deletes old compilation results and recompiles all classes.
 Note that the resulting JAR is not exactly the same as in our distributions. The distribution
JARs are built by Maven and have a different Manifest. Also, the distribution JARs are signed.

 package-addon, package-addon-fs::
 Builds a JAR file holding examples and code contributions which are distributed as source
only. '''package-addon''' compiles classes as required, '''package-addon-fs''' (from scratch)
first deletes old compilation results and recompiles all classes.

 javadoc-src, javadoc-addon::
 Builds Java''''''Docs for the component. '''javadoc-src''' builds Java''''''Docs for the
classes that are found in the distributable JAR for the component. '''javadoc-addon''' builds
combined Java''''''Docs for the classes in the distributable JAR, the examples and the code
contributions. Java''''''Docs are always built from scratch.

 run-tests, run-tests-fs::
 Builds and runs the unit tests for the component. '''run-tests''' compiles test classes as
required. '''run-tests-fs''' (from scratch) first deletes previously compiled test classes
and recompiles all tests.
 '''run-tests''' expects that the classes to be tested are already compiled, for example by
a previous execution of the '''package-src''' target. '''run-tests-fs''' compiles classes
of the '-src' group as required. 

 Rebuilds all '-src' and '-tests' classes with Clover instrumentation and runs the unit tests
to determine test coverage. This target has an external dependency on Clover. A licensed version
of Clover for use with Jakarta classes is available to Jakarta committers.

Here are some cleanup targets which have no external dependencies in any component:

 * '''clean-build''' -
 Removes all intermediate build results, like compiled classes and test coverage reports.
This does not remove final build targets like packaged JARs or Java''''''Docs.

 * '''clean-dist''' -
 Removes all final build results, like packaged JARs and generated Java''''''Docs (in their
default location).

 * '''clean-dist-api''' -
 Removes generated Java''''''Docs. This target will delete the Java''''''Docs even if they
are not in their default location.

=== External Dependencies ===

''This is work in progress.''

 * Really external dependencies vs. HttpComponent inter-dependencies with a default location
based on the directory structure.
 * external dependencies/properties to be set, where to find them in the build files
 * location of build.properties file adjustable
 * {{{ant echo-properties}}} to verify settings

=== Customization ===

''This is work in progress.''

 * where to find proberties to override
 * example: Java''''''Doc locations

To unsubscribe, e-mail: httpclient-dev-unsubscribe@jakarta.apache.org
For additional commands, e-mail: httpclient-dev-help@jakarta.apache.org

View raw message