Alfresco SVN Development Environment

From AlfrescoWiki

Jump to: navigation, search


Back to Developer Guide
See also: Developer Runtime Configuration

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

This is the development environment used by Alfresco engineers.

Contents

[edit] Extracting and Building

Ensure the following software is installed:


If you're using Tomcat, you'll need to install two separate installations, one for Alfresco and one for virtualization.

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; it's required for virtualization)

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 favorite 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 svn://svn.alfresco.com/alfresco/HEAD

If you are working with version 2.0 or previous version, navigate into the root/common folder 

cd HEAD/root/common

If you're working with version 2.1 or higher, navigate to root instead 

cd HEAD/root

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 executes the Tomcat startup 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 startup script
ant test runs unit tests for the entire project

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.

[edit] Subversion Repository Access

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

Contributions are also welcome.

[edit] Eclipse Projects

Each folder below the projects folder contains an Eclipse project that can be imported:

  • File > Import
  • General > Existing Projects Into Workspace > Next
  • Browse and select a subdirectory of projects
  • Finish

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

The projects can be imported in the following order:

  • 3rd-party - contains all 3rd party libraries (i.e. jars) that Alfresco depends on e.g. Spring, Hibernate. Some of them are for build purposes only.
  • core - contains low-level generic helper and utility classes e.g. configuration, error handling, i18n
  • MBean - seen as "mbeans" in the SVN server.
  • Deployment -
  • 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 etc. 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 WS 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 etc.
  • Installer - contains the installer scripts for windows & 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 e.g. Firefox, PHP
  • Netbios - a DLL that may be used by Alfresco's CIFS implementation for tight windows integration; implemented in C; it's very unlikely you'll need to view the contents of this project
  • SDK ... - SDKs and example projects that demonstrate how to develop different types of Alfresco extension

New in 2.1:

  • 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 the Catalina-virtual project - so you need to import this first, before importing link-validation

[edit] Running Ant From Eclipse

You can run the Ant targets mentioned above from within Eclipse, but there's a little setup you have to do.

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 expanaded to c:\alfresco you need to browse to c:\alfresco\common, select build.xml and press 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 TOMCAT_HOME etc are not defined then you can define them via Window > Preferences > And > Runtime > Properties and add env.TOMCAT_HOME etc.

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.

[edit] Developer Runtime Configuration

Before running Alfresco you may want to check the following common configuration options

[edit] Windows NetBios DLLs for CIFS Server

If you are running on Windows and want to use CFIS 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

Retrieved from "http://wiki.alfresco.com/wiki/Alfresco_SVN_Development_Environment"