Added bin, src-conf, and repurposed etc directory
[java-idp.git] / custom / README.txt
1 The custom directory contains the information necessary to build 
2 extension for the Shibboleth IdP and SP at the same time they are built, and
3 have these extensions bundled with their respective war file.
4
5 1. Directory Structure
6     custom
7       /lib - this directory is where an extension and its 
8              libraries are placed after they are built
9       /web - this directory is where an extension's web pages
10              are placed after the extension is built
11       extension-build.properties - this contains default properties 
12                                  needed for the extension build process
13                                  !!! DO NOT EDIT THIS FILE !!!
14       extension-build.xml - the ant build file for building extensions
15                                  !!! DO NOT EDIT THIS FILE !!!
16       README.txt - this document
17                                
18
19 2. Using the Extension Build Process
20 The extension build process depends on an extension having a specific directory
21 structure, so that the extension build file knows where to find everything.  The 
22 root directory of you extension can be named anything you with, but it must contain
23 the following directories
24     your-extension-directory/
25        bin/ - [Optional] This directory contains any binary or script files that need to 
26                be installed on the filesystem in the IdP or SP home bin directory.  This 
27                can include subdirectories.  The string's $IDP_HOME$ and $SP_HOME$ will be 
28                exapanded to the system path that the IdP or SP is installed (depending on 
29                which you're installing).
30        etc/ - [Optional] This directory contains any configuration files that need to 
31                be installed on the filesystem in the IdP or SP home etc directory.  This 
32                can include subdirectories.  The string's $IDP_HOME$ and $SP_HOME$ will be 
33                exapanded to the system path that the IdP or SP is installed (depending on 
34                which you're installing).
35        lib/ - [REQUIRED if 'src' is present] any third party jars your extension needs
36        src/ - [Optional] your extension's source
37        src-conf/ - [Optional] This directory contains any files which are not java source
38                files but still need to be included in the extension jar (and hence be 
39                available on the classpath).  This can include subdirectories.
40        tests/ - [Optional] Your extension's JUnit test case source.
41        web/ - [Optional] Any web pages, images, JSPs, etc. that should be included with the war
42        build.properties - [REQUIRED] build properties for your extension 
43                             (see below for required and optional properties)
44   
45 2.1 Steps for Using the Extensions Build Process
46 I.  Create a directory under the custom directory with the structure mentioned above.  Any 
47 extra directories will be ignored so it is safe to bundle additional information with your 
48 extension such as documentation.
49
50 II. Place your code and other resources in the directory structure you just set up
51
52 III. Compile and deploy Shibboleth as normal.
53
54 2.2 Build File Properties
55   The build file supports the following properties on a per-extension basis.
56     ext.name - [REQUIRED] The name of your resulting extension jar file (.jar will be appended to the name)
57     ext.install.etc - [Optional] Set to 'true' if you want the files in the 'etc' directory copied
58                    to the IDP_HOME/etc or SP_HOME/etc directory.  This will overwrite existing files.
59     gen.ext.docs - [Optional] This controls whether Java docs will be generated for your
60                    extension.  A value of "true" will result in them being generated, any other 
61                    value will result in them not being generated, if this property is missing 
62                    the default value of "true" is used.
63     test.ext - [Optional] This controls whether the JUnit tests for your extension are run.
64                    A value of "true" will result in them being run, any other value will result 
65                    in them not being skipped, if this property is missing the default value of 
66                    "true" is used.
67
68 3. Cautionary Note
69 DO NOT include libraries, with your extension, that are included with the Shibboleth
70 IdP or SP.  If you do, and there are version mismatches between the two jars, you will get 
71 unexpected exceptions during runtime as class versions conflict.
72
73 4. Common Errors
74 4.1 /path/to/extension/lib not found
75   This error occurs because Ant is unable to ignore references to directories of jars that don't
76   exist.  Simply create a 'lib' directory in your extension directory structure, you do not have 
77   to place anything in it.
78   
79 4.2 Duplicate web resources
80   If Ant encounters more than one web resource, like a JSP page, with the same name in the same 
81   destination in the war it will place N copies of that file in the war (per the zip spec), one 
82   for each time it encounters the file.  The contents of ALL files will be the contents of the 
83   last file with that name that it encountered.  So, if you attempt to override the login.jsp file
84   in your extension, for example, your war will have two login.jsp files and both will contain the 
85   contents of your extension's log in jsp (because it's encountered after the main shib one).
86   
87 4.3 The files in the etc directory are not being copied to IDP_HOME/etc or SP_HOME etc
88   The default behavior is NOT to copy these files so as to not overwrite existing configuration
89   files.  To enable this function set the build property ext.install.etc, however be sure to set 
90   it back to false afterwords so that you don't overwrite your configuration files during subsequent
91   builds.