Documentation for a historical release of Infusion: 1.4
Please view the Infusion Documentation site for the latest documentation, or the Infusion 1.3. Documentation for the previous release.
If you're looking for Fluid Project coordination, design, communication, etc, try the Fluid Project Wiki.

Custom Infusion Builds With Ant

Owned by
Justin Obara
Last updated: Feb 24, 2014Version comment
6 min read

Creating an Infusion 1.4 Custom Build

You can create a custom build of the latest release of Infusion using the Infusion Builder. If you wish to create a custom build using the very latest version, you can do so manually, if you know a bit about ant and svn.

What you will need

  1. Apache Ant
  2. The optional Ant task 'Script'
  3. Fluid Infusion source and build scripts, available from github.

For instructions on setting up the tools listed above, see the section #Setting up the environment at the bottom of this page.

On This Page

Using the custom build scripts

The Infusion build scripts are typically run from a command line. You must be in the build-scripts directory to run the scripts.

The most typical use of the build scripts will be using the customBuild target with one or more of three optional parameters: 'include', 'exclude', and 'jsfilename'. (See the #Options section below for more information about these and other parameters.) The following example shows what this would look like.

ant -lib lib/rhino customBuild -Dinclude="<list of modules to include>" -Dexclude="<list of modules to exclude>" -Djsfilename="<desired file name>"

The values passed to 'include' and 'exclude' are comma separated lists of module names (see the list of #Modules below for supported module names). If you specify a module to include, all of the module's dependencies will also be included. By contrast, if you specify a module to exclude, only that module will be excluded - not its dependencies.

Use excludes with caution

If you exclude a module that is a required dependency, then it must be included in your website in another way for Infusion components to work.

Some examples:

ant -lib lib/rhino customBuild -Dinclude="pager" -Djsfilename="infusionPager.js"

This example will create a custom JavaScript file called infusionPager.js that includes only one Infusion Component: the Pager. The build will automatically include any and all Infusion framework files needed by the Pager, as well as any jQuery files.

ant -lib lib/rhino customBuild -Dinclude="uiOptions, tableOfContents" \
                -Dexclude="jQuery, jQueryUICore, jQueryUIWidgets" \
                -Djsfilename="MyCustomInfusion.js"

This example will create a custom JavaScript file called MyCustomInfusion.js that includes two Infusion Component (UI Options and the Table of Contents) and excludes jQuery files. The build will automatically include any and all Infusion framework files required by the two components.

A user might choose to exclude the jQuery files if they already have a copy of jQuery in use on their site.

ant -lib lib/rhino customBuild -Dinclude="framework, fss"

This example will create a custom JavaScript file with the default file name (MyInfusion.js) that includes the Infusion Framework files and the Fluid Skinning System (FSS) files as well as any other files required by these two modules. It will not include any of the Infusion components.

URL rewriting

Infusion builds include a single js file, InfusionAll.js, that includes the necessary dependency files. However, the HTML files are bundled with the <script> and <link> blocks all pointing at the individual files.

To create a build that comes with the references in the <head> rewritten to point at the single .js file:

In v1.1: Run the custom build scripts with the rewriteHead option set to "true":

ant -lib lib/rhino -DrewriteHead="true"

In v1.2: Run the infusionAllBuilds ant target:

ant -lib lib/rhino infusionAllBuilds

Warning

The infusionAllBuilds target (or the rewriteHead option in v1.1) is intended to be used alone. It will run without error if the same options as the customBuild target (e.g. include, exclude, etc.) are provided, however the HTML files will link to both the single concatenated file and the individual required files.

Rhino

Portions of the Infusion build system are written in JavaScript, and are connected with the Ant-based system using the Rhino engine.

If you'd rather not specify the -lib parameter every time you run a build, you can upgrade the copy of Rhino installed by Ant in your $ANT_HOME/lib directory with the newer version distributed in Infusion's build-scripts/lib/rhino directory. On Mac OS X:

sudo rm -rf /usr/share/ant/lib/js-1.6R7.jar
sudo cp lib/rhino/js.jar /usr/share/ant/lib/js-1.7R3.jar

Modules

Name

Notes

Component Modules:

 

inlineEdit

 

pager

 

progress

Included with the Uploader component by default

reorderer

 

tabs
(New in v1.4)

Included with the UI Options component by default

tableOfContents

Included with the UI Options component by default

tooltip
(New in v1.3)

Included with the Inline Edit component by default

uiOptions

 

undo

Included with the Inline Edit component by default

uploader

 

Framework Modules:

 

framework

Will automatically be included with any component module

renderer

Will automatically be included with any component module that requires it

fastXmlPull

Will automatically be included with the Renderer and any component that requires the Renderer

json

 

fss

Including the fss module will automatically include all of the specific FSS sub-modules (e.g. fssReset, fssLayout, etc).

fssReset
(New in v1.2)

 

fssLayout
(New in v1.2)

If you wish to exclude all of FSS, you will need to exclude all fss modules
explicitly: -Dexclude="fss, fssReset, fssLayout, fssText, fssThemes".

fssText
(New in v1.2)

 

fssThemes
(New in v1.2)

 

External libraries:

 

jQuery

Will automatically be included with any component module

jQuerybgiframePlugin
(New in v1.2)

Required by pager

jQueryDelegatePlugin
(New in v1.2)

Required by framework and uiOptions

jQueryUICore

 

jQueryUIWidgets

Required by uiOptions and reorderer

jQueryTooltipPlugin

Required by inlineEdit and pager

swfupload

Included with the Uploader component by default

swfobject

Included with the Uploader component by default

Options

Option

Description

Default

include

A comma-separated list of module names to be included in the output.

If unspecified, everything will be included.

exclude

A comma-separated list of module names to be excluded from the output.

If unspecified, no required dependencies will be excluded.

jsfilename

The desired name of the resulting JavaScript file containing all of the requested modules.

MyInfusion.js
InfusionAll.js if no parameters at all are specified.

New in v1.2:
noMinify

A boolean used to request that the output not be minified (Minification removes all comments and whitespace. The resulting file is smaller, but very difficult to read. If you wish to be able to ready the file, use -DnoMinify="true".)

false (i.e. output will be minified by default)

Removed as of v1.2:
rewriteHead

A boolean used to request that the <head> element of HTML files be rewritten to reference the single all-inclusive InfusionAll.js file. See #URL rewriting for more information.

false (i.e. HTML files will include references to individual files by default)

Custom build with no parameters

If you use custom build with no parameters, everything, except for the tests and samples, is included. In addition, the resulting build files in the products/dist and products/src-dist directories are named InfusionAll.js files, rather than MyInfusion.js.

Output

The Infusion build scripts produce two folders at the root level of the distribution (i.e. as siblings of the build-scripts folder):

  • build/: This is a working folder used by the scripts to assemble and process files.
  • products/: This is the destination for the final output of the scripts.

You will rarely need to look at the contents of the build folder, but the products folder will contain the files you're looking for.

Products in v1.2

The products folder will contain either one or two archive files, depending on what target what run.

Custom Build
If the customBuild target was used to create a custom Infusion package, a single archive will be created: infusion-1.2.zip. This file will contain:

  • The concatenated JavaScript file containing all the requested resources, minified (unless the noMinify flag was set);
  • a .war file suitable for deploying to a web server;
  • folders containing the individual files requested, minified (unless the noMinify flag was set)

Release Build
If the default target was used to create the release packages, two archives will be created: infusion-1.2.zip and infusion-1.2-src.zip. These files have the same content, save that the -src archive contains un-minified files.

  • The concatenated JavaScript file containing the entire Infusion library and all dependencies;
  • a .war file suitable for deploying to a web server;
  • folders containing the Infusion files

Products in v1.1

The products folder will contain two folders and two archives:

  • src-dist/: A folder containing unminified versions of all of the requested files, organized according to the Infusion source tree;
  • dist/: A folder containing minified versions of all of the requested files, organized according to the Infusion source tree
  • infusion-1.1.2-src.zip: An archive file containing
    • The concatenated JavaScript file containing the entire Infusion library and all dependencies;
    • a .war file suitable for deploying to a web server;
    • folders containing the Infusion files
  • infusion-1.1.2.zip: An archive file containing the items listed above, but minified.

Other targets

The Infusion build scripts include other ant targets that are generally intended for use by the Infusion development team, but may be of interest to others:

Target

Description

releaseBuild

In v1.1: The default target.
Creates a release-ready distrubution

In v1.2: releaseBuilds

The default target.
Creates a release-ready distrubution

In v1.2: infusionAllBuilds

Creates a release-ready distrubution with the HTML headers re-written to link to the single concatenated InfusionAll.js instead of individual required files.

validate

Runs JSLint on all source code in the source directory. To specify a single directory, use -Dlint="../some/folder"

Setting up the environment

What you will need

  1. Apache Ant
  2. The optional Ant task 'Script'
  3. Fluid Infusion source and build scripts

Getting and configuring Ant

  1. Download the latest full version of Ant from ant.apache.org
  2. Put it wherever you like. If you're on OS X and want to replace the default version, you'll put it in /usr/share with admin privileges.
  3. You may wish to check your installation according to the Ant installation instructions

Getting the optional Ant task 'Script'

  1. Inside your new ant directory, also with admin privileges (think "sudo" on Unix), run ant -f fetch.xml -Ddest=system

Getting the Fluid Infusion source and build scripts

  1. Clone Fluid Infusion from Github:
    git clone git://github.com/fluid-project/infusion.git