Liferay Portal 4 - Development in the Extension Environment

The following instructions will help you get your development environment ready for working with the source code. These instructions are specific to setting up for deployment to Orion server and Tomcat 5.5 developing with Java JDK 1.5. Liferay Portal is compatible with Java 1.4 also and a wide array of application servers and containers. You will need to adjust your development environment according to your platform.

Before we can get started, the following conponents must be installed on your machine.

The extension environment can be built from the sources of Liferay Portal. You can opt to download the sources of the latest version from Sourceforge and unzip them to a clean directory or to obtain the latest version using subversion as explained in the previous section.

Go to the root directory of the Liferay Portal sources and create a file called release.${user.name}.properties where ${user.name} is the name of the user in your computer. Be sure to write it in the proper letter cases (even in Windows). Set the property lp.ext.dir to the directory where you would like to create the directory (make sure that it does not exist yet). If you expect to be using eclipse add also a property called lp.eclipse.project.name with the desired name of the project: For example:

lp.ext.dir=D:/Projects/liferay/portal/ext
lp.eclipse.project.name=liferay-ext

After creating the file execute the following ant targets to build the sources and create the extension directory structure:

$ ant start
$ ant build-ext

You can now go to the directory specified and see the directory structure that has been created. If you use some type of version control repository such as CVS or Subversion you can upload the directory to it. In the next steps you'll be creating build products that should not be uploaded to the version control repository.

The rest of the document will be referring to the root directory where the extension environment has been download as /ext.

The extension environment is build around a set of ant build scripts that are highly configurable through properties files and build scripts. You should create customized versions of the properties files by creating a version with the same name than the original one but inserting your user name before the extension. The two most important files that should be customized are:

The ext environment supports most of the application servers supported by Liferay Portal. The open source ones are supported by using the bundle that is automatically downloaded from sourceforge, for the proprietary ones it contains the basic configuration needed to make them work using an standard distribution.

The default configuration installs all the application servers in the /ext/servers subdirectory. This can be changed for any application server by setting a custom location in the file app.server.${user.name}.properties. You can also set the path to the Sourceforge mirror that you want to use for downloads or set it to point to a local mirror if you want to avoid external connections for each of the developers. For example to choose an european mirror and install tomcat outside of the ext environment you could use the following configuration:

app.server.type=tomcat
app.server.tomcat.dir=D:/Java/tomcat-5.5.17
sourceforge.mirror=http://belnet.dl.sourceforge.net/sourceforge/lportal

Once you are ready follow the following instructions specific for each application server:

It is possible install several application servers in the ext environment. Just make sure to set the value of the app.server.type property in app.server.${user.name}.properties to the application server that you are using in any specific moment of time.

	Note
	Be aware that when updating to certain new Liferay Portal version you may need to also upgrade the version of the application server or do other manual changes. Check the upgrade documentation specific to that version for more information.

After working with the extension environment it is some times needed to upgrade it to a new version of Liferay Portal. The process is very similar to the one performed for creating the environment the first time:

Is the root directory. From this directory you can build and deploy the whole application to the application server by running ant deploy. You should not need to place any extra files here.

Is the directory where you'll place downloads that will be used by the ant scripts.

Contains the Liferay Portal build artifacts upon which the environment is based. The modules subdirectory contains the file of a Liferay Portal ear unzipped.

Run ant deploy from /ext/ext-ear to deploy your custom EAR to your specified application server (see /ext/app.server.properties). Your custom EAR utilizes the Liferay Portal JARs and WARs contained in /ext/ext-ear/modules. This allows you to easily upgrade Liferay Portal because all the functionality is packed into archives.

This is the folder that will contain all your sources and configuration files (except those related to the web application). Upon creating of the ext environment several important files will be placed in its subdirectories. The most significant are:

Run ant deploy from /ext/ext-ejb to compile your source and to deploy your classes to the expanded EAR in your specified application server's deployment directory.

Place any extra dependent libraries in here. They will be copied over to the deployment directory when you run ant deploy from /ext.

This directory will contain your JSPs, HTMLs, images and all the web application related files inside the docroot subdirectory. Here are some of the most common activities you'll be performing from this directory:

	Note
	It is strongly suggested that you place all you JSPs and accompanying files inside the subdirectory /ext/ext-web/docroot/html. This directory will be assumed to exist in certain operations, for example when forwarding to a JSP referenced from struts-config.xml or tiles-defs.xml.

	Tip
	It is possible to override the JSPs that ship with Liferay Portal by placing them in /ext/ext-web/docroot/html and keeping the exact same path than the original version. When running ant deploy these files will be copied to /ext/ext-web/tmp and will override the original ones. Be aware that you'll have to review any changed JSPs when you upgrade to a new version of Liferay Portal.

This directory contains all of the portal's deployment time dependent libraries and compile time dependent libraries. It contains the following subdirectories:

Portlets placed in this directory will be automatically deployed to the application server when running the ant deploy target from the /ext directory.

Contains the targets used to manage the supported application servers and will also contain the installed application servers unless the default paths are changed.

This directory contains all of the portal's database scripts. Read the Liferay Portal 4 - Installation Guide for more information about using them to prepare a database for Liferay Portal and to configure the application server being used to run against it.

There are also two files named test.properties and test.script that are copied over to your specified application server's bin directory when you run ant deploy from /ext. The two files are used by Hypersonic and contain a snapshot of the portal's default data.

All the files in /ext/web-sites/liferay.com-web/docroot are copied to the deployment directory when you run ant deploy from /ext or /ext/ext-web.

By default, /ext/web-sites/liferay.com-web/docroot/index.html forwards the user to http://localhost/c. You can replace this file to pretty up the default page or change the default behavior.