Shibboleth Developers

[Chad La Joie <>]

Tom Scavo wrote:
> On 7/5/05, Chad La Joie 
> <>
>  wrote:
>
> > Each custom extension (or groups of extensions) would create a directory
> > within the "custom" directory. These extension directories would have
> > the following directory structure
> >
> >  <extension_directory>
> >     etc/
> >     lib/
> >     src/
> >     test/
> >     build.properties
>
>
> Do you mean tests/ (plural) for consistency?

Yep, "tests".

> > The "src" directory would contains your java sources for the extensions.
> > The "test" directory would contain any unit tests for them. The "etc"
> > directory would contain any number of directories that would simply be
> > copied in to the resulting extension jar, you would put any non-source
> > files that you wanted available on the class path in here (config files,
> > XML schemas, etc). 
>
>
> Instead of an etc/ directory, wouldn't an include file be more
> flexible?  Then the paths could be relative or absolute.  (Absolute
> paths are an important requirement, at least for the extension I have
> in mind.)

No, no path is absolute when the stuff is included in the class path. 
This directory is only for the stuff that will be sucked up in to the 
jar.  It's works the same as the "conf" and "schema" directories in the 
regular shib source tree.  If you want to bundle example config files 
that sit on the filesystem some where and are read in to your class then 
you can put it in another directory and include directions on the 
configuration of installation on where to put the files.

An alternative to that would be to put the config files where the shib 
config files that go on the filesystem are placed.

> > The "lib" directory would contain any 3rd party
> > libraries you need for your stuff.  Additional directories can be
> > included (documentation, config files that go somewhere else, etc) and
> > they'll just be ignored.  The build.properties file would contain a
> > single property; the name of the resulting jar.
>
>
> What would be the name of this property and would it be okay to have
> other properties in the build.properties file?  For example, is it
> okay to override idp.deployment.descriptor and/or
> sp.deployment.descriptor in the extension build.properties file?

No, the compilation of an extension does not change or overwrite the 
descriptor file.  The property name is extension.name.

> > When the IdP or SP was built it would compile each extension in turn
>
>
> In what order?  What if one extension depends upon another?

There is no implied order.  While I agree that this could be helpful in 
the future, it's a HUGE pain to do and just not going to happen right 
now.  You have to go outside Ant and use something like IVY or Maven to 
manage this and we're trying to get the "low hanging fruit" with this.

> > (ensuring all the Shib and 3rd party extension classes/libs are on the
> > classpath) and place the resulting extension jar, and all 3rd party jars
> > (those in extension_directory/lib) into a lib directory in the "custom"
> > directory.  Then, when the WARs were built for the IdP and SP, these jar
> > would be scooped up and put in the appropriate place.  A by product of
> > this approach is a greatly simplified means of including custom
> > extension; compiling them in some fashion and just placing the resulting
> > jar(s) in the custom/lib directory.
>
>
> What is done with the unit tests in tests/?

I should have been more specific.  The unit tests will need to be JUnit 
test cases, and they will be run after compile just like the IdP does 
during it's build process.  The build isn't going to try anything other 
than to run the test, if it fails the module fails to build.

> > Two issues with this approach.  First, if different extensions use
> > different versions of the same 3rd party jar you'll get class conflicts.
> > This would be true whether the Shib build did any of this special stuff
> > or not.  Second, extension authors are locked in to this source-tree
> > structure.  For most extensions this is probably just fine, for more
> > complicated extensions this may not be good.  I had discussed with a
> > couple people some idea for making this more flexible but ultimately we
> > decided that the additional complexity for everything BUT the extension
> > (and probably even for the extension) just wasn't worth it.  So, for
> > these special extensions, they can create their own build process and
> > just place their jar(s) in the custom/lib directory.
>
>
> Don't know if I'm in the latter category, but two things come to mind:
>
> 1) What if the extension wanted to supply a custom user ARP?

Extensions don't supply this stuff.  This is something people do when 
they configure a shibboleth instance which occurs after the build.  If 
your extension provides some special ARP functionality than people need 
to be aware of this when they install your extension.

> 2) How will the extension pre-process configuration files?  For
> example, what if the extension needed to do a custom variable
> substitution (similar to $SHIB_HOME$)?  

Currently I don't have support for attribute expansion.  We may choose 
to expand a specific attribute, like SHIB_HOME, but there is no way 
we're going to be able to create a mechanism that would allow people to 
expand an arbitrary attribute to an arbitrary value inside any given 
extension.

> (By the way, $SHIB_HOME$ needs
> to be changed to $IDP_HOME$ or $SP_HOME$ so that it agrees with the
> new property names in build.properties.)

Yeah, this is probably true.  I'd log this one as a separate bug.
--
Chad La Joie             315Q St. Mary's Hall
Project Sentinel         202.687.0124