Alfresco on Eclipse

[resplin]

{{Obsolete}}

NOTE - This page refers to an SDK which is now deprecated and might be dropped in the future. The official developer documentation for Alfresco 5.0 is here: http://docs.alfresco.com/5.0/concepts/dev-for-developers.html

Table of Contents

• 1 On Windows
  
  
  
  • 1.1 The application stack
    
    
    
    • 1.1.1 Java JDK
    
    
    • 1.1.2 MySQL
    
    
    • 1.1.3 Tomcat
      
      
      
      • 1.1.3.1 VS Tomcat
      
      
    
    
    • 1.1.4 ImageMagick
    
    
    • 1.1.5 SWFTools
    
    
  
  
  • 1.2 The development environment
    
    
    
    • 1.2.1 HeidiSQL
    
    
    • 1.2.2 Eclipse
    
    
    • 1.2.3 Install Eclipse and Subversion Plugin
    
    
    • 1.2.4 Increase Java heap space for Tomcat
    
    
    • 1.2.5 Configure Ant
    
    
    • 1.2.6 Check out the Alfresco source code using Subclipse
    
    
    • 1.2.7 Import the Alfresco projects
    
    
    • 1.2.8 Create Ant project
    
    
  
  


• 2 On Linux (Ubuntu 8.04)
  
  
  
  • 2.1 The application stack
    
    
    
    • 2.1.1 Java, MySQL, Ant, Subversion, ImageMagic, SWFTools
    
    
    • 2.1.2 Tomcat
    
    
  
  
  • 2.2 The development environment
    
    
    
    • 2.2.1 MySQL GUI
    
    
    • 2.2.2 Install Eclipse and Subversion Plugin
    
    
    • 2.2.3 Configure Ant
    
    
    • 2.2.4 Check out the Alfresco source code using Subclipse
    
    
    • 2.2.5 Import the Alfresco projects
    
    
  
  


• 3 Other tools
  
  
  
  • 3.1 Install STS (Spring Tool Suite)
  
  


• 4 On Mac


• 5 References

On Windows

The application stack

Java JDK

Install the Java 5 JDK (or Java 6 JDK for versions 3.3+)

http://java.sun.com/javase/downloads/index_jdk5.jsp

MySQL

use MySQL Essentials

http://dev.mysql.com/downloads/mysql/4.1.html

Tomcat

We're not going to use the Tomcat installer. Just download the Tomcat v6.x zip file. Create the directory C:\tomcat and unzip.

VS Tomcat

Very few developers will need to build the WCM virtual server.

However if you do want to build it from source you will need a copy of Tomcat 5.5

Its probably easiest to download the VS from the alfresco download page to get you started.

ImageMagick

Download ImageMagick and run the installer. Test that it is in your path by typing convert at a command prompt:

You should get a version number and a bunch of helpful information.

Find the convert executable file in your ImageMagick directory (e.g.: for Vista x64 C:\Program Files (x86)\ImageMagick-6.4.2-Q16) and rename it to imconvert.

Note: There are other ways to to address this within the build configuration. I'll add the instructions soon.

SWFTools

Download and install swftools. Add the install folder to the PATH variable.

This is a little more involved than it looks.  You need to pay attention to the dependencies on this swftools page: http://www.swftools.org/faq.html which mention two other packages you have to install first.  For one of them, pay attention to the help on that page in item #5 so you install the libraries and header files as well.

So you need to:

• Install jpeglib
  
• Install freetype - this can be a hassle as it cares what distribution of *NIX you have.  You really need to check out the documentation in the /docs folder of the install.
  
• Install swftools (grab a nightly build as the last stable release doesn't do all alfresco needs)
  
• Add the install folder to the PATH variable, perhaps putting something like this in alfresco.sh:
  

PATH = /path/to/swf/tools/:$PATH
export PATH

That path to swf tools will probably by /usr/local/bin but if you intentionally put those files elsewhere, then they will be there.  Just look for wherever pdf2swf ended up.

The development environment

HeidiSQL

HeidiSQL is an excellent graphical front-end to MySQL Server. This step is optional excepting the part about creating the database. You may forgo HeidiSQL and enter the SQL commands at a MySQL prompt using the command line.

Start HeidiSQL and log in as the root user. Once logged in select the SQL Query tab and paste in the following:

create database alfresco;
grant all on alfresco.* to alfresco@localhost identified by 'alfresco';
grant all on alfresco.* to alfresco@localhost.localdomain identified by 'alfresco';

Hit F9 to execute the script. You may wish to add the line 'drop database if exists alfresco;' to the query and save it as a snippet. You'll use it a lot.

---

Eclipse

Install Eclipse and Subversion Plugin

As of September 2008, the latest Eclipse (3.4.x = Ganymede) has a choice of compatible subversion plugins. These include Subversive, Subclipse and Collabnet desktop. Take your pick!

Increase Java heap space for Tomcat

In Eclipse, choose Window > Preferences > Tomcat > JVM Settings

Add the following to the JVM Parameters section

-Xms256m -Xmx512m

Configure Ant

In the Eclipse toolbar select Window > Preferences > Ant > Runtime > Properties

By clicking the 'Add Property...' button add the following names / values:

env.TOMCAT_HOME = C:\tomcat

env.APP_TOMCAT_HOME = C:\tomcat

env.VIRTUAL_TOMCAT_HOME = C:\virtual-tomcat

Check out the Alfresco source code using Subclipse

Warning: ensure that your eclipse workspace directory does not have a space in its name, e.g. 'C:\Documents and Settings\...'. This is because your workspace directory will be used for your SVN checkouts and the build doesn't like paths with spaces in their names.

In the Eclipse toolbar choose File > New > Project. In the SVN directory choose 'Checkout Projects with Subversion'. Making sure 'Create a new repository location' is selected click Next. Enter svn://svn.alfresco.com as the URL. Select the alfresco folder and click Next. Select 'Check out as project in the workspace'. You may choose a revision here if you would like.

Import the Alfresco projects

Before importing these projects, make sure that Eclipse's JDK compiler compliance level is set to 5.0 or greater within the Java > Compiler section of the Preferences screen.

1. Click File > Import.
   
2. Click General > Existing Projects Into Workspace > Next.
   
3. Click Browse and select the HEAD\root\projects directory.
   
4. Warning: there are currently some SDK projects with duplicate names defined in multiple .project files. Eclipse requires each of the projects in your workspace to have a unique name and won't like this. Deselect at least one of each of the duplicated projects before continuing.
   
5. Click Finish.
   

Create Ant project

1. Select New > Project in the Eclipse toolbar. Under 'General' choose 'Project'.
   
2. Right-click the project and choose New > File
   
3. When the new file dialog box appears click the Advanced button and select 'Link to file in the file system'.
   
4. Browse to the build.xml file located in the HEAD\root directory.
   

Warning: compiler errors in jlan related with sun.security.auth can occur, if java-6-openjdk JRE is selected in Preferences > Java > Installed JREs. Selecting java-6-sun JRE solves the problem.

On Linux (Ubuntu 8.04)

The application stack

Java, MySQL, Ant, Subversion, ImageMagic, SWFTools

Use the apt-get command to install the needed packages.

sudo apt-get install sun-java5-jdk ant subversion imagemagick mysql-server swftools

Add a symbolic link for ImageMagick.

sudo ln -s /usr/bin/convert /usr/bin/imconvert

Tomcat

sudo mkdir /usr/local/tomcat
sudo mkdir /usr/local/virtual-tomcat

Extract a copy of tomcat into each folder. The bin folder should now be just inside the folders that you've created.

The default heap size allocated by Tomcat for Java is less than Alfresco requires. Increase the heap size by editing the catalina.sh file in the tomcat/bin and virtual-tomcat/bin folder and adding the following line:

JAVA_OPTS='-Xms256m -Xmx512m'

Set up the environment variables

The environment variables may be different for the normal user and root. As you will be running the ant build as root, those variables need to be set for the root user. Add the variables at the terminal as root, using the export command.

sudo su
export JAVA_HOME=/usr/lib/jvm/java-1.5.0-sun-1.5.0.15/
export TOMCAT_HOME=/usr/local/tomcat/
export APP_TOMCAT_HOME=/usr/local/tomcat/
export VIRTUAL_TOMCAT_HOME=/usr/local/virtual-tomcat/

You may check that your variables are properly set by using the echo command like so:

echo $TOMCAT_HOME

You should see:

/usr/local/tomcat/

The development environment

MySQL GUI

MySQL may be managed from the cli. However, in a development environment a graphical user interface is often desirable. Ubuntu offers a fine GUI in the mysql-admin package.

sudo apt-get install mysql-admin

Install Eclipse and Subversion Plugin

Download Eclipse Ganymede for Java in the Linux flavor and extract it somewhere. I prefer the home folder. You can launch Eclipse by clicking the executable. You can also create a launcher for Eclipse and point it to the executable.

Eclipse Ganymede has a choice of compatible subversion plugins. These include Subversive, Subclipse and Collabnet desktop. Take your pick!

Configure Ant

In the Eclipse toolbar select Window > Preferences > Ant > Runtime > Properties

By clicking the 'Add Property...' button add the following names / values:

env.TOMCAT_HOME = /usr/local/tomcat/

env.APP_TOMCAT_HOME = /usr/local/tomcat/

env.VIRTUAL_TOMCAT_HOME = /usr/local/virtual-tomcat/

Check out the Alfresco source code using Subclipse

In the Eclipse toolbar choose File > New > Project. In the SVN directory choose 'Checkout Projects with Subversion'. Making sure 'Create a new repository location' is selected click Next.
Enter http://svn.alfresco.com/repos/alfresco-open-mirror as the URL.
Select the alfresco folder and click Next. Select 'Check out as project in the workspace'. You may choose a revision here if you would like.

Import the Alfresco projects

Before importing these projects, make sure that Eclipse's JDK compiler compliance level is set to 5.0 or greater within the Java > Compiler section of the Preferences screen.

1. Click File > Import.
   
2. Click General > Existing Projects Into Workspace > Next.
   
3. Click Browse and select the HEAD\root\projects directory.
   
4. Warning: there are currently some SDK projects with duplicate names defined in multiple .project files. Eclipse requires each of the projects in your workspace to have a unique name and won't like this. Deselect at least one of each of the duplicated projects before continuing.
   
5. Click Finish.
   

Other tools

Install STS (Spring Tool Suite)

Installing STS is a convenient way of working with surf and eclipse and STS is an IDE for eclipse 3.5/3.6 (Helios), whatever you prefer. It can be advised to use the 32-bit installer for STS with Eclipse 3.6 (Helios) on windows, since that makes JBoss Tools integration possible.

Download STS: http://www.springsource.com/products/springsource-download-center

Note: versions possible are 2.3.2 and 2.3.3. For surf development with the roo add-on, choose the 2.3.2 (Release) and not the 2.3.3 (Milestone).
Note: go to http://www.jboss.org/tools/download/ for the plugins for JBoss Tools

You should be aware that you should install the Subversion components. After installing STS, just go to Help > Install new software and select the appropriate Eclipse update site (Helios,Ganymede etc) and check the 'Collaboration' checkbox. Install and follow the instructions. 

STS is shipped with tc Server (tomcat) and is fully integrated for development ease.

Note: if you have an existing tomcat server and you want to control that from STS, just go to the server pane and right click. Select 'Add new server' and follow instructions to enable your local tomcat server. STS uses a wtpwebapps directory, it is advisable to leave that as it is.

Finally, follow instructions below on how to set up the tomcat server and Alfresco SVN project.

On Mac

1. Install Xcode and MacPorts.
   
2. Install various ports:
   

sudo port install swftools imagemagick apache-ant subversion

TBC

References

1. Alfresco development environment with Tomcat and Eclipse
   

[lipsa]

I am stuck in this step: "Click Browse and select the HEAD\root\projects directory."

While performing this I am getting an error that "No projects are found".

What to do now?

[resplin]

This page is marked as obsolete, and only exists for historical reference. You are better off referencing the SDK documentation at http://docs.alfresco.com