Slew of documentation and minor functionality changes addresing those listed here
[java-idp.git] / custom / extension-build.xml
1 <!-- 
2   This file is imported in to the main Shibboleth build.xml file and 
3   contains all targets used for building IdP and SP extensions.  These
4   targets are not designed to be called by anything other than the main
5   Shibboleth build file.
6   
7   Chad La Joie
8   July 25, 2005
9 -->
10 <project name="Shibboleth-Extensions" default="ext-invoke" basedir=".">
11
12     <!-- Loops through all the extension directories and executes a particular operation on them -->
13     <target name="ext-invoke" description="Invoke operation extensions">
14         <for keepgoing="true" param="module-path">
15             <dirset dir="${exts.dir}">
16                 <include name="*" />
17                 <exclude name="lib" />
18                 <exclude name="web" />
19             </dirset>
20             <sequential>
21                 <antcall target="${ext.build.function}">
22                     <param name="ext.root" value="@{module-path}" />
23                 </antcall>
24             </sequential>
25         </for>
26     </target>
27
28     <!-- Builds a single extension -->
29     <target name="ext-build" depends="ext-build-init" description="Builds the extension">
30         <echo message="--- Starting to build module ${ext.name} in ${ext.root}" />
31
32         <!-- Compile the source -->
33         <antcall target="ext-compile" />
34         
35         <!-- Generate Javadocs -->
36         <antcall target="ext-gen-docs" />
37
38         <!-- Copy over non-source files -->
39         <antcall target="ext-copy-src-conf" />
40
41         <!-- Run unit tests if we're supposed to -->
42         <antcall target="ext-test" />
43
44         <!-- Put the libraries where the IdP and SP packaging can pick them up -->
45         <antcall target="ext-copy-libs" />
46
47         <!-- Put the webpages where the IdP and SP packaging can pick them up -->
48         <antcall target="ext-copy-webpages" />
49
50         <echo message="--- Extension ${ext.name} built" />
51     </target>
52
53     <target name="ext-load-properties" description="Loads property files needed by build process">
54         <!-- Load extension specific properties. -->
55         <if>
56             <not>
57                 <available file="${ext.root}/build.properties" />
58             </not>
59             <then>
60                 <fail message="No build.properties file found for extension in ${ext.root}; this file is required." />
61             </then>
62         </if>
63         <property file="${ext.root}/build.properties" />
64
65         <!-- Load default properties -->
66         <property file="${exts.dir}/extension-build.properties" />
67
68         <fail unless="ext.name" message="The extension ${ext.root} does not contain the required (ext.name) property in its build.properties file." />
69     </target>
70
71     <!-- Initialize everything we need. -->
72     <!-- The properties loaded here are scoped to this particular extension build -->
73     <target name="ext-build-init"  depends="ext-load-properties" description="Sets up everything to prepare for the build">
74
75         <!-- Create needed directories -->
76         <mkdir dir="${ext.dist}" />
77         <mkdir dir="${ext.build}" />
78         <mkdir dir="${ext.classes}" />
79         <mkdir dir="${ext.docs}" />
80     </target>
81
82     <!-- Compiles the extension -->
83     <target name="ext-compile" description="Compiles an extension">
84         <!-- Compile any source that might be out there -->
85         <if>
86             <available file="${ext.src}" />
87             <then>
88                 <echo message="Compiling extension source" />
89                 <javac srcdir="${ext.src}" destdir="${ext.classes}" includes="**/*.java" debug="on" source="1.4" deprecation="true">
90                     <!-- Shibboleth Libraries -->
91                     <classpath refid="build.path" />
92
93                     <!-- Shibboleth Classes -->
94                     <classpath>
95                         <pathelement location="${build}" />
96                     </classpath>
97
98                     <!-- Extension libraries -->
99                     <classpath>
100                         <fileset dir="${ext.lib}">
101                             <include name="**/*.jar" />
102                         </fileset>
103                     </classpath>
104                 </javac>
105             </then>
106         </if>
107     </target>
108
109     <!-- Copies files from etc directory to dist directory to be bundled with extension jar -->
110     <target name="ext-copy-src-conf" description="Copys non-source files to place where they will be added to jar">
111         <!-- Copy any extra stuff that needs to be on the classpath -->
112         <if>
113             <available file="${ext.src.conf}" />
114             <then>
115                 <echo message="Detected files in the extensions 'src-conf' directory, ensuring they are bundled with the extension's jar." />
116                 <copy todir="${ext.classes}">
117                     <fileset dir="${ext.src.conf}">
118                         <include name="**" />
119                     </fileset>
120                 </copy>
121             </then>
122         </if>
123     </target>
124
125     <!-- Move third party libraries to be picked up by the war -->
126     <target name="ext-copy-libs" description="Moves third party libraries to be picked up by the war">
127         <if>
128             <available file="${ext.lib}" />
129             <then>
130                 <copy todir="${exts.dir}/lib">
131                     <fileset dir="${ext.lib}" includes="*.jar" />
132                 </copy>
133             </then>
134         </if>
135     </target>
136
137     <!-- Move web resources to be picked up by the war -->
138     <target name="ext-copy-webpages" description="Moves web resources to be picked up by the war">
139         <if>
140             <available file="${ext.webpages}" />
141             <then>
142                 <copy todir="${exts.dir}/web">
143                     <fileset dir="${ext.webpages}" />
144                 </copy>
145             </then>
146         </if>
147     </target>
148
149
150     <!-- Run any unit tests for the extension -->
151     <target name="ext-test" description="Runs extension unit test">
152         <if>
153             <equals arg1="${test.ext}" arg2="true" />
154             <then>
155                 <if>
156                     <available file="${ext.test.src}" />
157                     <then>
158                         <echo message="Running tests cases for extension ${ext.name}" />
159                         <junit printsummary="no" fork="yes" haltonerror="true" haltonfailure="true" jvm="${ext.root}">
160                             <jvmarg value="-Djava.endorsed.dirs=${endorsed}" />
161                             <formatter type="plain" />
162                             <batchtest>
163                                 <fileset dir="${ext.test.src}" />
164                             </batchtest>
165                         </junit>
166                     </then>
167                 </if>
168             </then>
169         </if>
170
171     </target>
172
173     <!-- Generates the Javadocs for the extension -->
174     <target name="ext-gen-docs" description="Generates Javadocs for extension">
175         <if>
176             <equals arg1="${gen.ext.docs}" arg2="true" />
177             <then>
178                 <if>
179                     <available file="${ext.src}" />
180                     <then>
181                         <echo message="Generating javadocs for extension ${ext.name}" />
182                         <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">
183                             <classpath refid="build.path" />
184                             <link href="http://java.sun.com/j2se/1.5.0/docs/api/" />
185                         </javadoc>
186                     </then>
187                 </if>
188             </then>
189         </if>
190     </target>
191
192     <!-- Jars up the extension -->
193     <!-- 
194         Required parameters
195             exts.dir - the root directory of the extensions (contains all the individual extension directories)
196             ext.filesystem.home - the path on the filesystem that the extension will be installed
197                 expected subdirectories are 'bin, 'etc', and 'lib'
198             ext.home.token - the token, in config files, to replace with the path to the IdP/SP home
199     -->
200     <target name="ext-package" depends="ext-load-properties" description="Packages up the extension">
201         <if>
202             <available file="${ext.classes}" />
203             <then>
204                 <replace dir="${ext.classes}" token="${ext.home.token}" value="${ext.filesystem.home}" excludes="*.class" />
205                 <replace dir="${ext.classes}" token="$EXTENSION_NAME$" value="${ext.name}" excludes="*.class" />
206                 <jar jarfile="${ext.dist}/${ext.name}.jar" basedir="${ext.classes}" />
207                 <copy file="${ext.dist}/${ext.name}.jar" todir="${exts.dir}/lib" />
208             </then>
209         </if>
210     </target>
211
212     <!-- Install extension files (configuration, scripts, etc) on to the filesystem -->
213     <!--
214         Required Paramter
215             ext.filesystem.home - the path on the filesystem that the extension will be installed
216                 expected subdirectories are 'bin, 'etc', and 'lib'
217             ext.home.token - the token that represents the extensions installation point within
218                 the various configuration files (those in the extensions 'etc' and 'src-conf' directories)
219     -->
220     <target name="ext-install-filesystem" depends="ext-build-init" description="Installs extension files on to the filesystem">
221         <echo message="Installing extension ${ext.name} to ${ext.filesystem.home}" />
222
223         <!-- Copy anything in the etc directory to the extension's installation point etc directory -->
224         <if>
225             <available file="${ext.etc}" />
226             <then>
227                 <if>
228                     <available file="${ext.filesystem.home}/etc/${ext.name}" />
229                     <then>
230                         <echo>--------------------------------------------------------------------------------------</echo>
231                         <echo>---</echo>
232                         <echo>---   NOTE:  Existing Shibboleth extension module configuration at ${line.separator}---   ${ext.filesystem.home}/etc/${ext.name} will not be overwritten.</echo>
233                         <echo>---</echo>
234                         <echo>--------------------------------------------------------------------------------------</echo>
235                     </then>
236                     <else>
237                         <mkdir dir="${ext.filesystem.home}/etc/${ext.name}" />
238                         <copy todir="${ext.filesystem.home}/etc/${ext.name}">
239                             <fileset dir="${ext.etc}">
240                                 <include name="**" />
241                             </fileset>
242                         </copy>
243                         <replace dir="${ext.filesystem.home}/etc/${ext.name}" token="${ext.home.token}" value="${ext.filesystem.home}" />
244                         <replace dir="${ext.filesystem.home}/etc/${ext.name}" token="$EXTENSION_NAME$" value="${ext.name}" />
245                     </else>
246                 </if>
247             </then>
248         </if>
249
250         <!-- Copy anything in the bin directory to the extension's installation point bin directory -->
251         <if>
252             <available file="${ext.bin}" />
253             <then>
254                 <copy todir="${ext.filesystem.home}/bin">
255                     <fileset dir="${ext.bin}">
256                         <include name="*" />
257                     </fileset>
258                 </copy>
259                 <chmod dir="${ext.filesystem.home}/bin" perm="ug+rx" includes="**/*" />
260             </then>
261         </if>
262
263         <!-- Copy anything in the lib directory to the extension's installation point lib directory -->
264         <if>
265             <available file="${ext.lib}" />
266             <then>
267                 <copy todir="${ext.filesystem.home}/lib">
268                     <fileset dir="${ext.lib}">
269                         <include name="*" />
270                     </fileset>
271                 </copy>
272             </then>
273         </if>
274
275         <!-- Copy the extension jar to the extension's installation point lib directory -->
276         <if>
277             <available file="${ext.dist}/${ext.name}.jar" />
278             <then>
279                 <copy file="${ext.dist}/${ext.name}.jar" todir="${ext.filesystem.home}/lib" />
280             </then>
281         </if>
282     </target>
283
284     <!-- Cleans up classes files -->
285     <target name="ext-clean-build" depends="ext-load-properties" description="Cleans up any build created resources">
286         <delete dir="${ext.build}" failonerror="false" />
287     </target>
288
289     <!-- Cleans up java docs -->
290     <target name="ext-clean-javadocs" depends="ext-load-properties" description="Deletes generated javadocs">
291         <delete dir="${ext.docs}" failonerror="false" />
292     </target>
293
294     <!-- Cleans up distribution files -->
295     <target name="ext-clean-dist" depends="ext-load-properties" description="Deletes distribution generated files">
296         <delete dir="${ext.dist}" failonerror="false" />
297     </target>
298 </project>