Liferay Contributor Development Environment Setup
Table of Contents [-]
Liferay Contributor Development Environment Setup #
So you want to be a Liferay contributor. The first thing you need to do is get your development environment set up.
This wiki page will walk you through all of the necessary steps for an environment best suited for contributing to the Liferay portal core.
The wiki page makes the following assumptions:
- You are familiar with Eclipse in general.
- You will be using the Liferay IDE as your development platform.
- You have some experience with Liferay and how the core project is organized.
- You're setting up a development environment on a Windows platform. Note that these instructions should pretty much work for other platforms, but you'll have to manage the various paths yourself.
Set Up a Working Directory #
In order to keep the paths as simple as possible, use C:\liferay as the base path for your development environment. You can choose a different path, of course, but you'll need to modify the instructions below as appropriate.
Within the C:\liferay directory, create the subdirectories "trunk", "workspace", and "bundles". Your directory tree should look like:
Get the Latest Liferay IDE #
We're going to set up a clean Liferay IDE (separate from whatever other development projects you've got). This will ensure that any changes you make to either the portal or the plugins SDK do not leak out to other projects.
You can download the IDE from here: http://www.liferay.com/downloads/liferay-projects/liferay-ide. It's probably easier to grab the "Eclipse + Liferay IDE" bundle for your platform as it should be complete and ready to go.
To keep everything together, extract the eclipse bundle you've downloaded to the C:\liferay directory.
Start up Eclipse. When it starts you need to select a workspace, use C:\liferay\workspace for the default workspace directory.
After Eclipse starts, the EGit plugin needs to be installed. From the Help menu, select Install New Software....
Choose to work with all available sites, then expand the Collaboration item and check the Eclipse EGit plugin. Install the plugin, then restart Eclipse.
Create Your Github.com Account #
Liferay is now using http://www.github.com for the source repository. The following should be performed to set up your GIT account.
Go to http://www.github.com and create a free account there.
Go to https://help.github.com/articles/set-up-git and follow the instructions for installing GIT and setting up the local GIT config.
Go to https://help.github.com/articles/generating-ssh-keys and follow the instructions for setting up the SSH key for your account. Be sure to complete the test mentioned in step 5 to ensure everything is working correctly.
Fork the Portal and Plugins Repositories #
The /liferay/liferay-portal repository holds the portal core, and the /liferay/liferay-plugins repository holds the Plugins SDK. We will be copying both so we can modify the core and build plugins to test the modifications.
In the upper right corner of https://github.com, enter /liferay into the search box to search for Liferay projects. In the results list, find and click on the /liferay/liferay-portal project.
At the top of the page, click on the Fork image to fork a copy of the liferay-portal repository to your own repository. This fork is your own fork and will be your primary repository.
Repeat the steps above for the liferay-plugins repository.
Cloning Repositories to Local System #
Next step is to clone the repositories to your local system. While this is possible to do directly within the Liferay IDE, the projects are so large that Eclipse may run out of memory during the import. Using the Git Bash shell is the preferred way to do the import.
Start a Git Bash shell in the C:\liferay\trunk directory. Enter the following commands, replacing the <your GIT account> with your GIT account name:
$ git clone firstname.lastname@example.org:<your GIT account>/liferay-portal.git portal $ cd portal $ git remote add upstream email@example.com:liferay/liferay-portal.git $ git fetch upstream $ cd .. $ git clone firstname.lastname@example.org:<your GIT account>/liferay-plugins.git plugins $ cd plugins $ git remote add upstream email@example.com:liferay/liferay-plugins.git $ git fetch upstream $ cd ..
Note: The projects are quite large and will take some time to download.
Importing Projects Into the Liferay IDE #
Now that the GIT projects have been cloned and updated, they can be pulled into the Liferay IDE.
Start up the Liferay IDE and open the Git Repository Exploring perspective. If you get a message about the HOME environment variable not being defined, check the checkbox to use as the default and click OK.
Use the Add an existing local Git Repository to this view button. In the window that comes up, use C:\liferay\trunk\portal for the directory and select the portal repository, then click on Finish. Repeat the same steps using C:\liferay\trunk\plugins to import the plugins repository.
Right click on the portal repository and choose Import Projects.... Use Import existing projects and the selected working directory and click Next >. Make sure portal-trunk is checked, then click Finish.
The Liferay IDE will take some time to import and build the project. Switch to the Liferay perspective to see the project.
You may or may not want to import the plugins repository in the same way. The plugins repository contains not just the plugins SDK, but also all of the sample plugin projects that are in the plugins repository.
Setup and Test the Project #
So the Liferay IDE now has the portal project loaded and built, but we should do some configuration before we start anything particular.
Create an app.server.<username>.properties file (replace <username> with your windows username) and set the contents as such:
This will use our C:\liferay\bundles directory for the app server(s) built during the build process.
Expand the portal project, right-click on the build-dist.xml file and choose Run As -> Ant Build.... In the Targets tab, un-select the dist target, and select the unzip-tomcat target, then click on Run.
This step will download the targetted version of Tomcat and expand it into the C:\liferay\bundles directory in preparation of the full build process.
If you don't want to do this in the Liferay IDE you can open a command prompt in the C:\liferay\trunk\portal directory and execute the command:
> ant -f build-dist.xml unzip-tomcat
After Tomcat is ready, the next step is to build the portal. In the Liferay IDE, right-click on the build.xml and choose Run As -> Ant Build.... In the Targets tab, un-select the compile target and select the all target, then click on Run.
This step will completely build the Liferay environment from the ground up, with the final step of updating the C:\liferay\bundles\tomcat-7.0.25\webapps\ROOT with the compiled portal.
The final step is to launch Tomcat and see if the build works. Open a command prompt in the C:\liferay\bundles\tomcat-7.0.25\bin directory and issue the following command:
> .\catalina.bat run
The Tomcat server will start using your freshly compiled Liferay environment, and IE will open showing the new portal wizard.
NOTE: Since this is a build from the master repository, you should not assume that you're going to have a working environment. The GIT repository should always be considered a work in progress, and not release-ready code.