Alfresco SVN Development Environment

[resplin]

1. REDIRECT Source Code
   

Obsolete Pages{{Obsolete}}

The official documentation is at: http://docs.alfresco.com

Source ControlContributing

Back to Developer Guide

See also: Developer Runtime Configuration

This page outlines the steps required to checkout the Alfresco Subversion Repository.  This allows for the re-build of Alfresco which is useful when extending or bug fixing the Alfresco product itself.

Table of Contents

• 1 Subversion repository access
  
  
  
  • 1.1 Extracting and building
    
    
    
    • 1.1.1 Building Alfresco 3.x or 4.x with Ant
    
    
    • 1.1.2 Building Alfresco 5.x with Maven
    
    
    • 1.1.3 Post-Build
    
    
  
  
  • 1.2 Development Environment
  
  
  • 1.3 Alfresco Projects
  
  
  • 1.4 Running Ant from Eclipse (Alfresco 3.x and 4.x only)
  
  
  • 1.5 Running Maven from Eclipse (Alfresco 5.x only)
  
  
  • 1.6 Developer Runtime Configuration
  
  
  • 1.7 Windows NetBios DLLs for CIFS Server
  
  

Subversion repository access

Public read-only access to the Alfresco Subversion repository is available from the web site.

• Install Subversion or Subeclipse and ensure that svn is on the path
  
• Checkout the HEAD of the code stream:
  
  • Port 80  : svn co http://svn.alfresco.com/repos/alfresco-open-mirror/alfresco/HEAD
    
• Keep up to date by issuing the command: svn update
  

Access to the Alfresco Enterprise Branches are available for Alfresco Network Members.  Contact Alfresco support for access.

• https://svn.alfresco.com/repos/alfresco-enterprise-mirror
  

Contributions are also welcome.

This is the development environment used by Alfresco engineers.

Extracting and building

Ensure the following software is installed:

• Java 1.7
  
• Ant 1.7.1 or higher
  
• Maven 2.2 or higher
  
• Subversion
  
• MySQL 5.5.x
  
• Tomcat 7.0 Note that Tomcat 5.5 is also required for the wcm virtualization server.
  
• SWF Tools 0.9.2 We use the latest Beta development build as it allows us to convert into SWF 9 format allowing us better control over the document when displayed in the 3.0 client. You need to add the location of pdf2swf to the PATH.
  
• Image Magick To convert images. Look here for installation instructions http://wiki.alfresco.com/wiki/ImageMagick_Configuration
  

If you are using Tomcat, you will need to install two separate installations, one for Alfresco and one for the WCM/AVM virtualization server.

Create the following environment variables to point to the appropriate folder:

• JAVA_HOME
  
• TOMCAT_HOME            (can be used to host the Alfresco webapp)
  
• APP_TOMCAT_HOME        (can be used to host the Slingshot webapp)
  
• JBOSS_HOME             (can be used to host the Alfresco webapp)
  
• VIRTUAL_TOMCAT_HOME    (NOTE: this must be a totally separate installation of Tomcat 5.5; it is required for wcm virtualization server)
  

You should also make sure that your [ANT]/bin directory and [Subversion]/bin directory are in your PATH.

Next, open a command window and execute the following commands (windows versions used, substitute your favourite shell if appropriate). 

Create the MySQL database and user required to run the application:

mysqladmin -u root create alfresco
mysql -u root -e 'grant all on alfresco.* to 'alfresco'@'localhost.localdomain' identified by 'alfresco' with grant option;'
mysql -u root -e 'grant all on alfresco.* to 'alfresco'@'localhost' identified by 'alfresco' with grant option;'

Create a new directory for Alfresco:

mkdir Alfresco
cd Alfresco

Use Subversion to transfer the Alfresco source archive to your local disk, as per the instructions in the next section:

svn co http://svn.alfresco.com/repos/alfresco-open-mirror/alfresco/HEAD

Navigate to root

cd HEAD/root

Building Alfresco 3.x or 4.x with Ant

All targets for building Alfresco are within build.xml. You can use ant -projecthelp to see all the available options. Here are a few of the common commands:

ant build-tomcat	builds and deploys Alfresco for Tomcat
ant incremental-tomcat	incrementally builds and deploys Alfresco for Tomcat
ant start-tomcat-application	executes the Tomcat start up script
ant build-jboss	builds and deploys Alfresco for JBoss
ant incremental-jboss	incrementally builds and deploys Alfresco for JBoss
ant start-jboss	executes the JBoss start up script
ant test	runs unit tests for the entire project

Building Alfresco 5.x with Maven

Alfresco 5.0 moved to using Maven for the build

The main targets you will want are:

mvn install	builds and runs all tests for Alfresco and Share
mvn install -DskipTests=true	quicker build, which skips all testing
mvn test	runs unit tests for the entire project. Use mvn install if you want to both test and package Alfresco and Share
????	builds and deploys Alfresco for Tomcat Maven target details needed
????	incrementally builds and deploys Alfresco for Tomcat Maven target details needed
????	executes the Tomcat start up script Maven target details needed

Post-Build

On Linux, you will need to install ImageMagick (http://www.imagemagick.org/script/binary-releases.php) and add a symbolic link, for example:

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

Once the server has started, open a browser and go to http://localhost:8080/alfresco if you are running Tomcat or http://localhost:8080/portal if you are running JBoss and click on the Alfresco link on the left.

For deploying, the environment variable TOMCAT_HOME is used.

Development Environment

Although in theory you can develop Alfresco with just a text editor such as vi or Notepad.   Most developers prefer a graphical GUI to work with the source code.  
Most developers use Eclipse, although there are other choices that will work equally well.

• Here is the guide for using Eclipse Alfresco_on_Eclipse.
  

• Here is the guide for using NetBeans  Alfresco_on_NetBeans
  

• Here is the guide for using IntelliJ Alfresco_on_IntelliJ
  

Alfresco Projects

The projects can be imported in the following order:

• 3rd-party - contains all 3rd party libraries (that is, jars) that Alfresco depends on, for example, Spring, Hibernate. Some of them are for build purposes only.
  

• core - contains low-level generic helper and utility classes, for example, configuration, error handling, i18n
  

• MBean - seen as mbeans in the SVN server.
  

• Deployment - the alfresco file system receiver FSR
  

• Alfresco JLAN - seen as alfresco-jlan in the SVN server.
  

• repository - contains the implementation of the Alfresco repository - the back-end services such as persistence, search, categorisation, transformation, and so on.  Also provides the Repository Java API. Configured via Spring.
  

• remote-api - contains Alfresco's Web Services API - again a façade on top of the repository; a war file can be built from this project which provides the Web Services API but not the Alfresco Web Client.
  

• web-service-client - contains client-side Web Service connection code and helpers.
  

• jndi-client - used by the web-client project.
  

• web-client - contains the implementation of the Alfresco Web Client - the front-end web browser application built with JSF; contains HTML, JSP, Javascript, images, backing beans, in-line editors, and so on.
  

• webscript-framework - used by remote-api and web-client.
  

• Installer - contains the installer scripts for windows and Linux plus readme and license files.
  

• lang-packs - contains language translations as contributed by the community in the form of resource bundles.
  

• Extensions - contains support for plugging Alfresco into different environments, for example, Firefox, PHP.
  

• Netbios - a DLL that may be used by Alfresco's CIFS implementation for tight windows integration; implemented in C; it is very unlikely you will need to view the contents of this project.
  

• SDK ... - SDKs and example projects that demonstrate how to develop different types of Alfresco extension.
  

• deployment - contains Alfresco Deployment Receiver - used by deployment service in WCM module.
  

• link-validation - contains service to perform link validation checks in WCM module. Note that this depends on the Catalina-virtual project, so you need to import this first, before importing link-validation.
  

Running Ant from Eclipse (Alfresco 3.x and 4.x only)

You can run the Ant targets mentioned above from within Eclipse. Firstly, you need to complete the following setup:

Create a new Simple Project (not a Java Project). I call mine Ant.

1. Right click on the Ant project and select New > File.
   
2. Click the Advanced button.
   
3. Select the option Link to file in the filesystem.
   
4. Browse for the build.xml file. If you expanded to c:\alfresco you need to browse to c:\alfresco\common, select build.xml and click the Open button.
   
5. Enter build.xml in the File name field.
   
6. Click Finish.
   

You should now see a link to build.xml in your Ant project. Double-click the file to see the contents. Eclipse also has several options to allow you to run targets in the file.

One way is to use the Outline window as it shows you all the targets in the project. Find the target you want to run and right click. Choose Run As > Ant build.

If you get errors because the environment variables, like TOMCAT_HOME, are not defined, then you can define them via Window > Preferences > Ant > Runtime > Properties and add env.TOMCAT_HOME.

If you really want to you can also debug the Ant script by placing a breakpoint in build.xml and choosing Debug As > Ant Build.

Running Maven from Eclipse (Alfresco 5.x only)

Before beginning, you will need the M2E Maven for Eclipse plugin installed

TODO Rest

Developer Runtime Configuration

Before running Alfresco you will almost certainly want to check the following common configuration options. Chances are that if you do not make the appropriate adjustments to the Tomcat startup script then it will fail to start properly and all sorts of strange things will happen.

Windows NetBios DLLs for CIFS Server

If you are running on Windows and want to use CIFS, you also need to copy Win32Utils.dll and Win32NetBIOS.dll into the env.TOMCAT_HOME/bin. The Alfresco installer, which contains a copy of Tomcat already, has these DLLs in place but if you have been following these instructions and have installed Tomcat yourself, they will not be present.

The correct versions of the DLLs to copy can be found in SVN.

HEAD\root\projects\alfresco-jlan\jni

Alfresco_on_NetBeans
Alfresco_on_Eclipse