Added bin, src-conf, and repurposed etc directory
authorlajoie <lajoie@ab3bd59b-922f-494d-bb5f-6f0a3c29deca>
Mon, 11 Jul 2005 10:18:25 +0000 (10:18 +0000)
committerlajoie <lajoie@ab3bd59b-922f-494d-bb5f-6f0a3c29deca>
Mon, 11 Jul 2005 10:18:25 +0000 (10:18 +0000)
Added expansion of $IDP_HOME$ and $SP_HOME$ in etc and src-conf files
Cleaned up interface between build and extension-build files a bit
Updated documentation to reflect changes

git-svn-id: https://subversion.switch.ch/svn/shibboleth/java-idp/trunk@1709 ab3bd59b-922f-494d-bb5f-6f0a3c29deca

build.xml
custom/README.txt
custom/extension-build.properties
custom/extension-build.xml

index 3b116dc..491e8b7 100755 (executable)
--- a/build.xml
+++ b/build.xml
@@ -86,8 +86,9 @@
                </copy>
 
                <!-- Build extensions -->
                </copy>
 
                <!-- Build extensions -->
-               <antcall target="build-exts">
+               <antcall target="ext-invoke">
                        <param name="exts.dir" value="${custom}"/>
                        <param name="exts.dir" value="${custom}"/>
+            <param name="ext.build.function" value="ext-build"/>      
                </antcall>
        </target>
 
                </antcall>
        </target>
 
                <delete dir="${build}" />
                <delete dir="${custom.libs}"/>
                <delete dir="${custom.webapges}"/>
                <delete dir="${build}" />
                <delete dir="${custom.libs}"/>
                <delete dir="${custom.webapges}"/>
-           <antcall target="ext-clean">
+           <antcall target="ext-invoke">
                <param name="exts.dir" value="${custom}"/>
                <param name="exts.dir" value="${custom}"/>
+            <param name="ext.build.function" value="ext-clean"/>   
            </antcall>
        </target>
        <target name="clean-test">
            </antcall>
        </target>
        <target name="clean-test">
                                <antcall target="install.idp.filesystem.config" />
                        </then>
                </if>
                                <antcall target="install.idp.filesystem.config" />
                        </then>
                </if>
+
+        <antcall target="ext-invoke">
+            <param name="exts.dir" value="${custom}"/>
+            <param name="ext.build.function" value="ext-install-filesystem"/>
+            <param name="ext.filesystem.home" value="${idp.home}"/>
+            <param name="ext.home.token" value="$IDP_HOME$"/>
+        </antcall>   
        </target>
 
        <!-- Install Shibboleth SP to filesystem using the properties in build.properties -->
        </target>
 
        <!-- Install Shibboleth SP to filesystem using the properties in build.properties -->
                                <antcall target="install.sp.filesystem.config" />
                        </then>
                </if>
                                <antcall target="install.sp.filesystem.config" />
                        </then>
                </if>
+
+        <antcall target="ext-invoke">
+            <param name="exts.dir" value="${custom}"/>
+            <param name="ext.build.function" value="${ext-install-filesystem}"/>
+            <param name="ext.filesystem.home" value="${sp.home}"/>
+            <param name="ext.home.token" value="$SP_HOME$"/>
+        </antcall>      
        </target>
 
 
        </target>
 
 
index e375cf7..2683081 100644 (file)
@@ -22,10 +22,21 @@ structure, so that the extension build file knows where to find everything.  The
 root directory of you extension can be named anything you with, but it must contain
 the following directories
     your-extension-directory/
 root directory of you extension can be named anything you with, but it must contain
 the following directories
     your-extension-directory/
-       etc/ - [Optional] This directory contains anything that isn't Java source but still needs 
-              to be on the classpath.  This can include subdirectories, and can be excluded.
+       bin/ - [Optional] This directory contains any binary or script files that need to 
+               be installed on the filesystem in the IdP or SP home bin directory.  This 
+               can include subdirectories.  The string's $IDP_HOME$ and $SP_HOME$ will be 
+               exapanded to the system path that the IdP or SP is installed (depending on 
+               which you're installing).
+       etc/ - [Optional] This directory contains any configuration files that need to 
+               be installed on the filesystem in the IdP or SP home etc directory.  This 
+               can include subdirectories.  The string's $IDP_HOME$ and $SP_HOME$ will be 
+               exapanded to the system path that the IdP or SP is installed (depending on 
+               which you're installing).
        lib/ - [REQUIRED if 'src' is present] any third party jars your extension needs
        src/ - [Optional] your extension's source
        lib/ - [REQUIRED if 'src' is present] any third party jars your extension needs
        src/ - [Optional] your extension's source
+       src-conf/ - [Optional] This directory contains any files which are not java source
+               files but still need to be included in the extension jar (and hence be 
+               available on the classpath).  This can include subdirectories.
        tests/ - [Optional] Your extension's JUnit test case source.
        web/ - [Optional] Any web pages, images, JSPs, etc. that should be included with the war
        build.properties - [REQUIRED] build properties for your extension 
        tests/ - [Optional] Your extension's JUnit test case source.
        web/ - [Optional] Any web pages, images, JSPs, etc. that should be included with the war
        build.properties - [REQUIRED] build properties for your extension 
@@ -43,6 +54,8 @@ III. Compile and deploy Shibboleth as normal.
 2.2 Build File Properties
   The build file supports the following properties on a per-extension basis.
     ext.name - [REQUIRED] The name of your resulting extension jar file (.jar will be appended to the name)
 2.2 Build File Properties
   The build file supports the following properties on a per-extension basis.
     ext.name - [REQUIRED] The name of your resulting extension jar file (.jar will be appended to the name)
+    ext.install.etc - [Optional] Set to 'true' if you want the files in the 'etc' directory copied
+                   to the IDP_HOME/etc or SP_HOME/etc directory.  This will overwrite existing files.
     gen.ext.docs - [Optional] This controls whether Java docs will be generated for your
                    extension.  A value of "true" will result in them being generated, any other 
                    value will result in them not being generated, if this property is missing 
     gen.ext.docs - [Optional] This controls whether Java docs will be generated for your
                    extension.  A value of "true" will result in them being generated, any other 
                    value will result in them not being generated, if this property is missing 
@@ -69,4 +82,10 @@ unexpected exceptions during runtime as class versions conflict.
   for each time it encounters the file.  The contents of ALL files will be the contents of the 
   last file with that name that it encountered.  So, if you attempt to override the login.jsp file
   in your extension, for example, your war will have two login.jsp files and both will contain the 
   for each time it encounters the file.  The contents of ALL files will be the contents of the 
   last file with that name that it encountered.  So, if you attempt to override the login.jsp file
   in your extension, for example, your war will have two login.jsp files and both will contain the 
-  contents of your extension's log in jsp (because it's encountered after the main shib one).
\ No newline at end of file
+  contents of your extension's log in jsp (because it's encountered after the main shib one).
+  
+4.3 The files in the etc directory are not being copied to IDP_HOME/etc or SP_HOME etc
+  The default behavior is NOT to copy these files so as to not overwrite existing configuration
+  files.  To enable this function set the build property ext.install.etc, however be sure to set 
+  it back to false afterwords so that you don't overwrite your configuration files during subsequent
+  builds.
\ No newline at end of file
index 5f4ba9e..e894ba1 100644 (file)
@@ -1,8 +1,10 @@
 # DO NOT EDIT THIS FILE
 
 # DO NOT EDIT THIS FILE
 
-ext.lib=${ext.root}/lib
+ext.bin=${ext.root}/bin
 ext.etc=${ext.root}/etc
 ext.etc=${ext.root}/etc
+ext.lib=${ext.root}/lib
 ext.src=${ext.root}/src
 ext.src=${ext.root}/src
+ext.src.conf=${ext.root}/src-conf
 ext.test-src=${ext.root}/tests
 ext.webpages=${ext.root}/web
 ext.dist=${ext.root}/dist
 ext.test-src=${ext.root}/tests
 ext.webpages=${ext.root}/web
 ext.dist=${ext.root}/dist
@@ -11,4 +13,5 @@ ext.docs=${ext.dist}/docs
 
 # Properties controlling build behavior
 gen.ext.docs=true
 
 # Properties controlling build behavior
 gen.ext.docs=true
-test.ext=true
\ No newline at end of file
+test.ext=true
+ext.install.etc=true
\ No newline at end of file
index 22391ab..37c1925 100644 (file)
@@ -5,10 +5,17 @@
   Chad La Joie
   July 6, 2005
 -->
   Chad La Joie
   July 6, 2005
 -->
-<project name="Shibboleth-Extensions" default="build-exts" basedir=".">
+<project name="Shibboleth-Extensions" default="ext-invoke" basedir=".">
 
 
-    <!-- Builds the extensions; loops through all the extension directories and builds them -->
-    <target name="build-exts" description="Compiles IdP and/or SP extensions">
+    <!-- Loops through all the extension directories and executes a particular operation on them -->
+    <!-- 
+        Required parameters
+            exts.dir - the root directory of the extensions (contains all the individual extension directories)
+            ext.build.function - the particular extension build function to invoke, acceptable values
+                   ext-invoke, ext-clean, ext-install-filesystem 
+               (some functions may require additional paramters, see documentation for each function)
+    -->
+    <target name="ext-invoke" description="Invoke operation extensions">
         <for keepgoing="true" param="module-path">
             <dirset dir="${exts.dir}">
                 <include name="*" />
         <for keepgoing="true" param="module-path">
             <dirset dir="${exts.dir}">
                 <include name="*" />
@@ -16,7 +23,7 @@
                 <exclude name="web" />
             </dirset>
             <sequential>
                 <exclude name="web" />
             </dirset>
             <sequential>
-                <antcall target="ext-build">
+                <antcall target="${ext.build.function}">
                     <param name="ext.root" value="@{module-path}" />
                 </antcall>
             </sequential>
                     <param name="ext.root" value="@{module-path}" />
                 </antcall>
             </sequential>
@@ -31,7 +38,7 @@
         <antcall target="ext-compile" />
 
         <!-- Copy over non-source files -->
         <antcall target="ext-compile" />
 
         <!-- Copy over non-source files -->
-        <antcall target="ext-copy-etc" />
+        <antcall target="ext-copy-src-conf" />
 
         <!-- Generate the java docs if we're supposed to -->
         <antcall target="ext-gen-docs" />
 
         <!-- Generate the java docs if we're supposed to -->
         <antcall target="ext-gen-docs" />
         <antcall target="ext-package" />
 
         <!-- Put the libraries where the IdP and SP packaging can pick them up -->
         <antcall target="ext-package" />
 
         <!-- Put the libraries where the IdP and SP packaging can pick them up -->
-        <antcall target="ext-copy-libs"/>
+        <antcall target="ext-copy-libs" />
 
         <!-- Put the webpages where the IdP and SP packaging can pick them up -->
 
         <!-- Put the webpages where the IdP and SP packaging can pick them up -->
-        <antcall target="ext-copy-webpages"/>
-        
+        <antcall target="ext-copy-webpages" />
+
         <echo message="--- Extension ${ext.name} built" />
     </target>
 
     <!-- Initialize everything we need. -->
     <!-- The properties loaded here are scoped to this particular extension build -->
         <echo message="--- Extension ${ext.name} built" />
     </target>
 
     <!-- Initialize everything we need. -->
     <!-- The properties loaded here are scoped to this particular extension build -->
-       <target name="ext-build-init" description="Sets up everything to prepare for the build">
-               <echo message="Loading build property files" />
-               <!-- 
+    <target name="ext-build-init" description="Sets up everything to prepare for the build">
+        <echo message="Loading build property files" />
+        <!-- 
                Load extension specific properties if available. We can not set the extension's build.properties 
                file name in the extension-build.properties file because if we read that file first the extension 
                build properties won't be able to override properties in it as properties are immutable once set.
                -->
                Load extension specific properties if available. We can not set the extension's build.properties 
                file name in the extension-build.properties file because if we read that file first the extension 
                build properties won't be able to override properties in it as properties are immutable once set.
                -->
-               <if>
-                       <not>
-                               <available file="${ext.root}/build.properties"/>
-                       </not>
-                       <then>
-                               <fail message="No build.properties file found for extension in ${ext.root}; this file is required."/>
-                       </then>
-               </if>
-               <property file="${ext.root}/build.properties" />
-
-               <!-- Load default properties -->
-               <echo message="Loading build property defaults ${exts.dir}/default-build.properties" />
-               <property file="${exts.dir}/extension-build.properties" />
-
-           <fail unless="ext.name" message="The extension ${ext.root} does not contain the required (ext.name) property in its build.properties file."/>
-
-               <!-- Create needed directories -->
-               <mkdir dir="${ext.dist}" />
-               <mkdir dir="${ext.classes}" />
-       </target>
+        <if>
+            <not>
+                <available file="${ext.root}/build.properties" />
+            </not>
+            <then>
+                <fail message="No build.properties file found for extension in ${ext.root}; this file is required." />
+            </then>
+        </if>
+        <property file="${ext.root}/build.properties" />
+
+        <!-- Load default properties -->
+        <echo message="Loading build property defaults ${exts.dir}/default-build.properties" />
+        <property file="${exts.dir}/extension-build.properties" />
+
+        <fail unless="ext.name" message="The extension ${ext.root} does not contain the required (ext.name) property in its build.properties file." />
+
+        <!-- Create needed directories -->
+        <mkdir dir="${ext.dist}" />
+        <mkdir dir="${ext.classes}" />
+    </target>
 
     <!-- Compiles the extension -->
     <target name="ext-compile" description="Compiles an extension">
 
     <!-- Compiles the extension -->
     <target name="ext-compile" description="Compiles an extension">
 
                     <!-- Shibboleth Classes -->
                     <classpath>
 
                     <!-- Shibboleth Classes -->
                     <classpath>
-                       <pathelement location="${build}"/>
+                        <pathelement location="${build}" />
                     </classpath>
                     </classpath>
-                    
+
                     <!-- Extension libraries -->
                     <classpath>
                         <fileset dir="${ext.lib}">
                     <!-- Extension libraries -->
                     <classpath>
                         <fileset dir="${ext.lib}">
     </target>
 
     <!-- Copies files from etc directory to dist directory to be bundled with extension jar -->
     </target>
 
     <!-- Copies files from etc directory to dist directory to be bundled with extension jar -->
-    <target name="ext-copy-etc" depends="ext-build-init" description="Copys non-source files to place where they will be added to jar">
+    <target name="ext-copy-src-conf" depends="ext-build-init" description="Copys non-source files to place where they will be added to jar">
         <!-- Copy any extra stuff that needs to be on the classpath -->
         <if>
         <!-- Copy any extra stuff that needs to be on the classpath -->
         <if>
-            <available file="${ext.etc}" />
+            <available file="${ext.src.conf}" />
             <then>
                 <echo message="Detected files in the extensions 'etc' directory, ensuring they are bundled with the extension's jar." />
                 <copy todir="${ext.classes}">
             <then>
                 <echo message="Detected files in the extensions 'etc' directory, ensuring they are bundled with the extension's jar." />
                 <copy todir="${ext.classes}">
-                    <fileset dir="${ext.etc}">
+                    <fileset dir="${ext.src.conf}">
                         <include name="**" />
                     </fileset>
                 </copy>
             </then>
         </if>
     </target>
                         <include name="**" />
                     </fileset>
                 </copy>
             </then>
         </if>
     </target>
-    
+
     <!-- Move third party libraries to be picked up by the war -->
     <target name="ext-copy-libs" depends="ext-compile" description="Moves third party libraries to be picked up by the war">
         <if>
     <!-- Move third party libraries to be picked up by the war -->
     <target name="ext-copy-libs" depends="ext-compile" description="Moves third party libraries to be picked up by the war">
         <if>
             <available file="${ext.webpages}" />
             <then>
                 <copy todir="${exts.dir}/web">
             <available file="${ext.webpages}" />
             <then>
                 <copy todir="${exts.dir}/web">
-                    <fileset dir="${ext.webpages}"/>    
+                    <fileset dir="${ext.webpages}" />
                 </copy>
             </then>
         </if>
     </target>
 
                 </copy>
             </then>
         </if>
     </target>
 
-    
+
     <!-- Run any unit tests for the extension -->
     <target name="ext-test" depends="ext-compile" description="Runs extension unit test">
         <if>
     <!-- Run any unit tests for the extension -->
     <target name="ext-test" depends="ext-compile" description="Runs extension unit test">
         <if>
                     <available file="${ext.src}" />
                     <then>
                         <echo message="Generating javadocs for extension ${ext.name}" />
                     <available file="${ext.src}" />
                     <then>
                         <echo message="Generating javadocs for extension ${ext.name}" />
-                        <javadoc sourcepath="${ext.src}" 
-                                 destdir="${ext.docs}" 
-                                 packagenames="*"
-                                 author="true"
-                                 version="true"
-                                 windowtitle="${ext.name} Shibboleth Extension Java API"
-                                 doctitle="${ext.name} Shibboleth Extension Java API"
-                                 failonerror="false">
+                        <javadoc sourcepath="${ext.src}" destdir="${ext.docs}" packagenames="*" author="true" version="true" windowtitle="${ext.name} Shibboleth Extension Java API" doctitle="${ext.name} Shibboleth Extension Java API" failonerror="false">
                             <classpath refid="build.path" />
                             <classpath refid="build.path" />
-                       </javadoc>
+                        </javadoc>
                     </then>
                 </if>
             </then>
                     </then>
                 </if>
             </then>
         <jar jarfile="${ext.dist}/${ext.name}.jar" basedir="${ext.classes}" excludes="${ext.name}.jar" />
     </target>
 
         <jar jarfile="${ext.dist}/${ext.name}.jar" basedir="${ext.classes}" excludes="${ext.name}.jar" />
     </target>
 
+    <!-- Install extension files (configuration, scripts, etc) on to the filesystem -->
+    <!--
+        Required Paramter
+            ext.filesystem.home - the path on the filesystem that the extension will be installed
+                expected subdirectories are 'bin, 'etc', and 'lib'
+            ext.home.token - the token that represents the extensions installation point within
+                the various configuration files (those in the extensions 'etc' and 'src-conf' directories)
+    -->
+    <target name="ext-install-filesystem" depends="ext-build-init" description="Installs extension files on to the filesystem">
+        <echo message="Installing extension ${ext.name} to ${ext.filesystem.home}"/>
+        
+        <!-- Copy anything in the etc directory to the extension's installation point etc directory -->
+        <if>
+            <and>
+                <available file="${ext.etc}" />
+                <or>
+                    <equals arg1="${ext.install.etc}" arg2="true" />
+                    <not>
+                        <available file="${ext.filesystem.home}/etc"/>
+                    </not>
+                </or>
+            </and>
+            <then>
+                <copy todir="${ext.filesystem.home}/etc">
+                    <fileset dir="${ext.etc}">
+                        <include name="*" />
+                    </fileset>
+                </copy>
+                <replace dir="${ext.filesystem.home}/etc" 
+                         token="${ext.home.token}" 
+                         value="${ext.filesystem.home}"/>
+            </then>
+        </if>
+
+        <!-- Copy anything in the bin directory to the extension's installation point bin directory -->
+        <if>
+            <available file="${ext.bin}" />
+            <then>
+                <copy todir="${ext.filesystem.home}/bin">
+                    <fileset dir="${ext.bin}">
+                        <include name="*" />
+                    </fileset>
+                </copy>
+                <chmod dir="${ext.filesystem.home}/bin" perm="ug+rx" includes="**/*"/>
+            </then>
+        </if>
+
+        <!-- Copy anything in the lib directory to the extension's installation point lib directory -->
+        <if>
+            <available file="${ext.lib}" />
+            <then>
+                <copy todir="${ext.filesystem.home}/lib">
+                    <fileset dir="${ext.lib}">
+                        <include name="*" />
+                    </fileset>
+                </copy>
+            </then>
+        </if>
+        
+        <!-- Copy the extension jar to the extension's installation point lib directory -->
+        <if>
+            <available file="${ext.dist}/${ext.name}.jar"/>
+            <then>
+                <copy file="${ext.dist}/${ext.name}.jar" todir="${ext.filesystem.home}/lib"/>
+            </then>
+        </if>
+    </target>
+
     <!-- Cleans up build generated resources -->
     <target name="ext-clean" description="Cleans up any build created resources">
     <!-- Cleans up build generated resources -->
     <target name="ext-clean" description="Cleans up any build created resources">
-        <!-- Clean up all the modules -->
-        <for keepgoing="true" param="module-path">
-            <dirset dir="${exts.dir}">
-                <include name="*" />
-                <exclude name="lib" />
-                <exclude name="web" />
-            </dirset>
-            <sequential>
-                <delete dir="@{module-path}/dist" failonerror="false"/>
-            </sequential>
-        </for>
+        <delete dir="${ext.root}/dist" failonerror="false" />
     </target>
     </target>
-
 </project>
 </project>