Grouper Developers Forum

[Kathryn Huxtable <>]

Hi all,

I've done a major refactoring of the build environment for ldappc and  
I mentioned in the conference call that I would summarize the changes  
and the future directions.

In the past week I converted ldappc's build environment from ant to  
maven, and embedded Apache DS 1.0.2 for unit testing purposes. It is  
now possible to run unit testing without an external LDAP server. At  
the moment, this is hard-coded, but I'll move it into configuration  
shortly.

As many of you know, ant is sort of a successor to the venerable UN*X  
make command. It is a significant improvement over make, but is still  
procedural and requires lots of coding for even small projects. For  
large projects, the amount of effort involved in maintaining the  
build.xml and build.properties files can be enormous. Further, reading  
an ant build.xml file is a bit like reading spaghetti code, in that  
there are many "come froms" that need to be followed.

Maven was developed by the Apache project to take a more life-cycle  
approach to project builds. Maven takes the attitude that 95% of all  
builds are the same and the rest is largely similar. This is similar  
to the Ruby on Rails philosophy of assuming standards unless there's a  
good reason to do otherwise.

The maven pom.xml file (Project Object Model) file is descriptive  
rather than procedural. The assumption is that your code layout  
follows the maven standards. In the POM you describe the artifacts  
(usually jars) that your project depends on and the scope (e.g.  
compile, runtime, test, etc.), you describe the deliverables, which  
may involve some packing instructions, and you describe the reporting  
desired. Maven then can compile, test, and package your deliverable,  
and generate site documentation with extremely minimal effort.

So for ldappc, I had to move the project source and test data to  
specific directories. I didn't want to break the current CVS  
repository, so I copied the ldappc project to a new project called  
ldappc-mvn and then manually moved the directory structure around,  
preserving file revision history, since the source was not changing.  
When we're ready to release ldappc 1.2.0 we will rename the original  
ldappc project to ldappc-ant or ldappc-old, and rename ldappc-mvn to  
simply ldappc. Currently the internal documentation does not reflect  
this change.

Maven uses a local repository in a directory on the developer's hard  
drive (or account on multiple user systems) to store the artifacts  
(jars) needed by projects the user has built. When an artifact is  
required that is not present in the user's local repository it will be  
downloaded from one or more remote repositories. The web site http://repo1.maven.org/maven2 
 is the central repository, containing jars for most open source or  
freely re-distributable artifacts. Maven handles transitive  
dependencies, so if ldappc depends upon grouper and grouper depends  
upon a particular version of hibernate, that version of hibernate will  
be included automatically, provided that it can be obtained from a  
repository listed in the POM file, or the central repository.

Since the I2MI artifacts required by ldappc (the grouper, signet, and  
subject APIs) are not in the central repository, and a few other  
artifacts required by grouper are also not in the central repository,  
they must be supplied in another fashion. If Internet2 had a Maven  
repository we could publish the artifacts there and download them from  
there, but Internet2 does not. So I am included the jars and  
constructed POM files for each jar in a lib directory with the ldappc  
project. The README.txt file in that directory contains instructions  
for installing these artifacts into your local repository, after which  
Maven can build ldappc.

There are two main commands to build ldappc:

        mvn package
        mvn site

Since my new signet integration isn't working as yet and the tests  
will fail you will also (currently) need to add the option "- 
Dmaven.test.failure.ignore=true" to each command.

The first command compiles the source, runs the JUnit tests, and  
builds both source and binary distributions in both zip and tar.gz  
formats. The second command generates the project documentation. This  
involves running the test suite again and performing Cobertura  
coverage analysis, as well as building the javadocs.

You should run the site generator first, then the package, if you want  
to create a source distribution because then the source distribution  
will contain a doc directory containing the project documentation.

The binary distribution contains the doc directory if you have  
previously generated site documentation, a lib directory containing  
all the required jars, including the ldappc jar, a conf directory with  
sample configuration files, and scripts to run the program.

To install maven, go to http://maven.apache.org and follow the  
download instructions. Recent versions are included by default on Mac  
OS X and are available for Windows and common Linux distributions. I  
have never had to build Maven from source on any of these operating  
systems.

-K