This wiki does not contain official documentation and is currently deprecated and read only. Please try reading the documentation on the Liferay Developer Network, the new site dedicated to Liferay documentation. DISCOVER Build your web site, collaborate with your colleagues, manage your content, and more. DEVELOP Build applications that run inside Liferay, extend the features provided out of the box with Liferay's APIs. DISTRIBUTE Let the world know about your app by publishing it in Liferay's marketplace. PARTICIPATE Become a part of Liferay's community, meet other Liferay users, and get involved in the open source project. Setting up the Extension Environment
This article explains how to set up an Extension Environment that allows you to customize Liferay for your own purposes, but allows to easily upgrade to future releases of Liferay.
Two popular development environments are the Eclipse IDE and Netbeans IDE.
Requirements #
- Java 5.0+
- Ant 1.8 or later
- SVN client (TortoiseSVN, kdesvn, SmartSVN, command line tool or an integrated IDE that supports SVN).
- Liferay Portal source code
- Web Server (Tomcat, Resin, etc.)
Set up #
Set JAVA_HOME to your Java directory. Set ANT_HOME to your Ant directory. Add JAVA_HOME\bin and ANT_HOME\bin to System Path.
Building and deploying #
First make your base Liferay directory (ex: c:\Liferay). From now on, we will call this directory {Liferay}.
Unzip the portal source code to {Liferay}\portal.
Configuring your application server properties#
Documentation warning: The documentation says that the application server properties should be configured after doing the ant build (ant start), but the ant build will fail if the app server properties are not set beforehand.
Copy the file app.server.properties, located in {Liferay}/portal, to app.server.{user name}.properties file in the same directory, where {user name} is your system login name.
cp app.server.properties app.server.$(whoami).properties
The default application server is Tomcat-5.5, as indicated by the app.server.type property. You may select a different server type. According to the server selected, set the corresponding directory. For instance, for Tomcat you may set the property as follows: app.server.tomcat.dir=c:/portal/tomcat
Configuring your compiler#
In Liferay-5 the default Java compiler is the Sun Java compiler, because in Liferay 5 and higher development was switched to JDK 5. In older versions, the Jikes compiler is assumed to be the default. If you plan to use the Jikes compiler, be aware that different JDK versions require different versions of Jikes. Please see the Jikes article for more details. To use the Sun Java compiler, set the javac.compiler property in {Liferay}/portal/build.properties to modern.
Copy the file build.properties, to build.{user name}.properties file in the same directory, where {user name} is your system login name.
cp build.properties build.$(whoami).properties
In this file you will notice that, by default, the javac.fork property is set to true. If set to false, this may lead to java.lang.OutOfMemoryError: Java heap space while building, even if your system has lots of free memory. To fix this, set javac.fork=true and make sure javac.memoryMaximumSize is large enough (the default 512m should do fine).
Ant build#
To build liferay go to {Liferay}\portal and execute:
ant clean start
The start target will build all the modules in the appropriate order to make sure everything goes ok. You should run this target every time there are changes to code inside portal\. This includes when you make changes or when you update some changes from the Subversion repository.
Unzip Tomcat bundle to {Liferay}\tomcat if you do not already have tomcat installed.
Configuring the release properties for ext environment#
Go to {Liferay}\portal and create a release.{user name}.properties file, where {user name} is your system login name. Be aware that the user name is case sensitive, even in Windows.
Add the line: lp.ext.dir={Liferay}/portal/ext
On nix systems, the following command will do this, once you are in {Liferay}\portal
echo "lp.ext.dir=$(pwd)/ext" > release.$(whoami).properties
This directory may not yet exist if you are building the Extension Environment for the first time. You will notice that this property is a full path and may look like D:/Projects/liferay/portal/ext. Linux users can also set the property to a relative path like: lp.ext.dir=ext.
Execute the following from {Liferay}\portal:
ant build-ext
Verify that EXT Environment is being built in your {Liferay}/portal/ext.
Move or copy the following properties files to the extension environment: {Liferay}\portal\ext.
- {Liferay}\portal\build.{user name}.properties (Document error??? There is no "build.{user name}.properties" you can copy/move from. If you copied the build.properties to {Liferay}\portal\ext, you would not be able to deploy the ext. I assume the author means "release.{user name}.properties"?)
- {Liferay}\portal\app.server.{user name}.properties
Developing #
You are now ready to use the EXT environment to customize Liferay. Do not write portlets in the EXT environment if you can possibly avoid it. Use the Plugins SDK instead.
It is advised to never modify core Liferay source code directly, but instead copy the code to the extension environment. This is to prevent conflicts from future upgrades, as well as keeping a backup of core code.
If you wish to change some of Liferay's code, copy the directory structure into the extension environment. For example, the bookmark portlet is in: {Liferay}/portal/portal-impl/src/com/liferay/portlet/bookmarks. To change this code, copy the file to {Liferay}/portal/ext/ext-impl/src/com/liferay/portlet/bookmarks and edit away!.
Note for Liferay 4.2: In Liferay 4.2 portal-impl is named portal-ejb and ext-impl is ext-ejb
To deploy to web server, run the following from {Liferay}/portal/ext:
ant deploy
Notes (for Tomcat 5.5 and Liferay 4.3.1) #
The "ant deploy" does not copy {Liferay}/ext/servers/conf/Catalina/localhost/ROOT.xml to the Tomcat directory. You'll need to edit this file to define your datasource and manually copy it to the Tomcat server at {Tomcat}/conf/Catalina/localhost/ROOT.xml.
Also, the jars copied to {Tomcat}/common/lib/ext do not get picked up since Tomcat does not include the 'ext' directory in its classloader definitions (see {Tomcat}/conf/catalina.properties). To solve this, you can symlink or copy all the jars in {Tomcat}/common/lib/ext to {Tomcat}/common/lib. Or edit the {Tomcat}/conf/catalina.properties and add {Tomcat}/common/lib/ext/.jar to the 'common.loader' path.
Related Articles #
