DevDocs/StartingDevelopment

HOW TO START DEVELOPMENT (Vaadin 6)

This article gives instructions for starting development of Vaadin by checking it out from the repository. (Instructions for developing web applications with Vaadin are given in the Book of Vaadin.)

This is updated to reflect what is required for developing Vaadin 6.3 and newer. For older versions some items may not apply.

Summary:

  1. Download and install Eclipse IDE for Java EE Developers (Galileo SR-2 currently used for consistent formatting).
  2. Install the Subclipse plugin to you Eclipse to use Subversion directly from Eclipse.
  3. Check out repository trunk.
  4. Add required libraries to your Java build path.
  5. Compile the widgetset using the build/build.xml ANT script target widgetsets.
  6. Let Eclipse compile the library and demos.
  7. Configure and start Apache Tomcat
  8. Vaadin should now be up and running (usually at  http://localhost:8080/vaadin, but this will depend on the configuration of your Tomcat installation and the context name of the Eclipse project).
  9. Coding conventions.
  10. Optional steps.
  • Disable JSF, XML and DTD validators. HTML validator is good to be on.
  • Use existing launch configurations to run hosted mode browser (client side debugging environment).

Requirements

  • Java SDK 5 (required)
  • Eclipse (recommended)
  • A web contained supported by Eclipse such as Apache Tomcat (recommended)
  • Subclipse, the Subversion front-end for Eclipse (optional)

The installation of these required development tools is described below, except for the Java SDK.

1. Install Eclipse

Install Eclipse IDE for Java EE Developers from  http://www.eclipse.org/downloads/. You should normally install it as a user and not as a superuser, as it makes installation of plugins easier.

This package contains the WTP tools for Eclipse. They allow, for example, integration with Apache Tomcat and many other web containers, so that when you modify your code, it is immediately loaded to the container.

2. Install Subclipse plugin for Eclipse (optional)

The  Subclipse plugin is a front-end for Subversion that allows you to control it easily from Eclipse. Subclipse is not mandatory and using Subversion from command line or with some other tool can be just as easy. The Subversion commands given in these instructions are for command line use.

You should install the Subclipse plugin with the update feature of Eclipse. See the  installation instructions for details.

3. Check out the latest version

You can check out the project repository with the command-line Subversion tools or with some graphical front-end, such as the Subclipse plugin for Eclipse. The latest version can be found in http://dev.vaadin.com/svn/versions/x.y where x.y is the version number.

Check out with Subclipse

To check out the sources using Subclipse do the following:

  1. Switch to the Subversion perspective and add location such as http://dev.vaadin.com/svn/versions/6.3.
  1. Right click the version you want and select "Checkout...".
  1. Select the Check out as a project configured using the New Project Wizard option.
  1. Check out the project as a Dynamic Web Project.
  1. Enter a project name, such as vaadin
  1. For Target runtime, select the Tomcat version you have installed. Click Next.
  1. In the Web Module view, you can set a more convenient context root than the default, such at tk.
  1. Click Finish.

The Vaadin project is now created in Eclipse.

Check out with command-line

See Subversion repository.

4. Set the build path

By default only the src folder is included in the build path. This folder contains the core Vaadin files. To also build demos and tests, in addition to the core, you need to add these folders as source folders:

  1. Open project properties (right-click on project -> properties)
  2. Select Java Build Path -> Source.
  3. Click "Add folder" and add "demo/src" and "tests/src" as source folders

You also need to add some libraries to the project build path.

  1. Right-mouse-click on the project to open the context menu and select Properties (or press Alt+Enter when the project is selected).
  1. Select Java Build Path -> Libraries.
  1. Click Add JARs... and select the following libraries from your checked out project:
  • lib/core/**/*.jar (include all jars found under lib/core. Note! From the gwt folder you should only add gwt-dev.jar and gwt-user.jar to avoid conflicts.)
  • lib/demo/**/*.jar (include all jars found under lib/demo, only needed for compiling demos)
  • lib/tests/**/*.jar (include all jars found under lib/tests, only needed for compiling tests)
  1. Click Ok in the JAR Selection window and observe that the JARs are added in the build path.
  1. Click OK to exit the Properties window.

5. Compile widget sets

Eclipse does not automatically compile the widget sets, i.e., the Vaadin Client-Side Engine. It must be compiled with the GWT Compiler before you can use Vaadin. A recompilation is needed whenever you or a Subversion update make changes to any client side class (by convention named V* e.g., VTextField, VOptionGroup).

The widget sets are compiled using the build.xml Ant script in the build directory. Using Eclipse: Right click on the build/build.xml file and select "Run as" -> "Ant Build...". Select the target depending on what you want to compile (typically widgetsets).

The output should be something like (not necessarily up-to-date): 

Buildfile: build.xml

init-platform:

init-nonpackage:
     [echo] We are on linux platform, using build/gwt/linux/gwt-dev-linux.jar.

compile-client-side:

compile-widgetset-reserver:
     [echo] com.vaadin.demo.reservation.gwt.ReservationWidgetSet

[..]

compile-widgetset-default:
     [echo] Compiling src (client-side)
     [echo] com.vaadin.terminal.gwt.DefaultWidgetSet
     [java] Compiling module com.vaadin.terminal.gwt.DefaultWidgetSet
     [java]    Compiling 6 permutations
     [java]    Worker permutation 0 of 6
     [java]       Creating Split Point Map file for SOYC
     [java]          Done
     [java] Permutation took 5328 ms
[..]

The "widgetsets" target in the build script compiles all the widget sets included in Vaadin. To compile only a specific widgetset, use "ant widgetset-<xxx>", e.g. "ant widgetset-default".

If you use command line ant you would do: 

$ cd build
$ ant widgetsets-default

6. Compile Vaadin under Eclipse

Eclipse compiles all the source code immediately when you modify it. If you have modified files externally, such as after a Subversion update from command-line, you must refresh the project. Select the project and press F5 (or select Refresh from the right-mouse-button context menu). If you have modified the widget sets (the Client-Side Engine), you need to (re-)compile the widget sets (and then do the refresh).

7. Configure and start Apache Tomcat

You can run the Vaadin project using an installed Tomcat server as follows:

  1. Right-click the project and select Debug As -> Debug on Server.
  1. Select the server you want to run it one (e.g., Apache Tomcat you have earlier installed) and click Finish.
  1. The project will now be added to the server, the server will be started and an internal Eclipse browser will be opened automatically with the url:  http://localhost:8080/<project name>

To control the server later on, use the controls in the Server view in Eclipse. Stop, Restart and Debug are the most useful. Most of the time you will want to run the server in debug mode so you can use breakpoints.

8. Run the demos and tests in your browser

You can now point your own browser to the url http://localhost:8080/<project name>/ e.g., http://localhost:8080/vaadin/ and you will see the demo index page.

Different demo and test applications are under the base context. You can run some of the demos from the index page. See the WebContent/WEB-INF/web.xml for the up-to-date list of configured demo and test applications.

9. Coding conventions

If you intend to develop the Vaadin itself and submit code to the community repository, your code must conform to our Coding Conventions.

You should also be able to build the installation package with no warnings or errors. The package is compiled with Java SDK 1.5 compatibility.

10. Optional steps

Suspending validation (optional)

Eclipse by default tries to validate various types of files in the project. This takes a lot of time and actually causes invalid errors especially in the GWT and documentation tool folders.

You can suspend the validators by doing the following:

  1. Right-mouse-click on the project to open the context menu and select Properties (or press Alt+Enter when the project is selected).
  1. Select Validation.
  1. Select the Override validation preferences.
  1. Disable the JSF, XML and DTD validators (unless working on documetation). The HTML validator may be good to have on, although it too may cause many invalid errors. You could also just select Disable all without losing very much.
  1. Click OK.

You may encounter a problem that Eclipse does not apply the changes to validation immediately, but many errors and warnings remain. Closing the project and quitting and restarting Eclipse may help, or even deleting (without deleting the contents) and importing the project again.

Building Vaadin installation package

To compile Vaadin installation package from the repository, you just run the build.xml with ant: 

$ cd build
$ ant

or in Eclipse using right click on build.xml -> "Run as" -> "Ant Build...".

Debugging with the Hosted Mode Browser

The Hosted Mode Browser of Google Web Toolkit allows you to debug client-side widgets.

Please follow the instructions given in the Manual. The repository does not contains any launch configurations for running the Hosted Mode Browser (GWTShell), but you can easily copy them from the installation package (they are generated during the package build process).

Troubleshooting

The first things to do if you ever experience any trouble are:

  1. Recompile the widget sets ant widgetsets (if any client-side code has changed)
  1. Refresh the project (F5) (if any files have changed outside Eclipse - such as the widget sets)
  1. Restart Tomcat (if there are "certain kinds of changes").

Restarting Tomcat is necessary, for example, if you edit the web.xml file. Tomcat also sometimes "forgets" to publish/unpublish files so you might need to remove the project from the server and publish it again to clean up things.

How to get help?

If you have problems with compiling Vaadin from the source repository, ask help from  http://vaadin.com/forum