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 macros $EXTENSION_NAME$ and $IDP_HOME$ or
  28                $SP_HOME$ will be exapanded for all files in this directory.
  29        etc/ - [Optional] This directory contains any configuration files that need to
  30                be installed on the filesystem under the IdP or SP home etc directory.  This
  31                            can include subdirectories.  All files will be installed into a subdirectory
  32                            named after the extension module.  The macros $EXTENSION_NAME$ and $IDP_HOME$ or
  33                $SP_HOME$ will be exapanded for all files in this directory.
  34        lib/ - [REQUIRED if 'src' is present] any third party jars your extension needs
  35        src/ - [Optional] your extension's source
  36        src-conf/ - [Optional] This directory contains any files which are not java source
  37                files but still need to be included in the extension jar (and hence be
  38                available on the classpath).  This can include subdirectories.  The macros
  39                $EXTENSION_NAME$ and $IDP_HOME$ or $SP_HOME$ will be exapanded for all files
  40                in this directory.
  41        tests/ - [Optional] Your extension's JUnit test case source. Test case files MUST
  42                 end with "Test.java" (i.e. the name must match *Test.java).  Resources other
  43                 than Java source files placed in this directory are added to the unit testing
  44                 classpath (e.g. if you have "conf/foo.xml" in the tests directory it will appear
  45                 on the classpath under /conf/foo.xml").
  46
  47        web/ - [Optional] Any web pages, images, JSPs, etc. that should be included with the war
  48        build.properties - [REQUIRED] build properties for your extension
  49                             (see below for required and optional properties)
  50
  51 The following directories are created, and destroyed, by the extension build process and as
  52 such developers should never rely on them: build, dist, doc/api.  Any other directory may be
  53 created and bundled with the extension, the build process will simply ignore them.
  54
  55 The macro $IDP_HOME$ is only expanded during an IdP install and $SP_HOME$ is only
  56 expanded during an SP install.
  57
  58 2.1 Steps for Using the Extensions Build Process
  59 I.  Create a directory under the custom directory with the structure mentioned above.  Any
  60 extra directories will be ignored so it is safe to bundle additional information with your
  61 extension such as documentation.
  62
  63 II. Place your code and other resources in the directory structure you just set up
  64
  65 III. Compile and deploy Shibboleth as normal.
  66
  67 2.2 Build File Properties
  68   The build file supports the following properties on a per-extension basis.
  69     ext.name - [REQUIRED] The name of your resulting extension jar file (.jar will be appended to the name)
  70     gen.ext.docs - [Optional] This controls whether Java docs will be generated for your
  71                    extension.  A value of "true" will result in them being generated, any other
  72                    value will result in them not being generated, if this property is missing
  73                    the default value of "true" is used.
  74     test.ext - [Optional] This controls whether the JUnit tests for your extension are run.
  75                    A value of "true" will result in them being run, any other value will result
  76                    in them not being skipped, if this property is missing the default value of
  77                    "true" is used.
  78
  79 3. Cautionary Note
  80 DO NOT include libraries, with your extension, that are included with the Shibboleth
  81 IdP or SP.  If you do, and there are version mismatches between the two jars, you will get
  82 unexpected exceptions during runtime as class versions conflict.
  83
  84 4. Common Errors
  85 4.1 /path/to/extension/lib not found
  86   This error occurs because Ant is unable to ignore references to directories of jars that don't
  87   exist.  Simply create a 'lib' directory in your extension directory structure, you do not have
  88   to place anything in it.
  89
  90 4.2 Duplicate web resources
  91   If Ant encounters more than one web resource, like a JSP page, with the same name in the same
  92   destination in the war it will place N copies of that file in the war (per the zip spec), one
  93   for each time it encounters the file.  The contents of ALL files will be the contents of the
  94   last file with that name that it encountered.  So, if you attempt to override the login.jsp file
  95   in your extension, for example, your war will have two login.jsp files and both will contain the
  96   contents of your extension's log in jsp (because it's encountered after the main shib one).
  97