HOW TO START DEVELOPMENT (Toolkit 5)
This article gives instructions for starting development of IT Mill Toolkit by checking it out from the repository. (Instructions for developing web applications with IT Mill Toolkit are given in the Manual.)
Summary:
- Download and install Eclipse IDE for Java EE Developers.
- Install the Subclipse plugin to you Eclipse to use Subversion directly from Eclipse.
- Check out repository trunk.
- Create a Dynamic Web Project with the Project wizard.
- Extract platform-specific GWT package(s) to build/gwt/ directory and link (or on Windows rename) the extracted directory to build/gwt/gwt.
- Add GWT, Jetty, Portlet, and Google Maps libraries to your Java build path.
- Compile GWT files with the build/bin/compile_gwt_components script (or the .bat file on Windows).
- Let Eclipse compile the library and demos.
- Launch Tomcat
- Toolkit 5 should now be up and running (usually at http://localhost:8080/tk-trunk, but this will depend on the configuration of your Tomcat installation and the context name of the Eclipse project).
Extra steps:
- Disable JSF, XML and DTD validators (unless working on documetation). HTML validator is good to be on.
- Use existing launch configurations to run hosted mode browser (client side debugging environment).
Requirements
- Java SDK, 1.4 or higher (required)
- Eclipse (recommended)
- A web contained supported by Eclipse such as Apache Tomcat (recommended)
- Subclipse, the Subversion front-end for Eclipse (optional)
- Google Web Toolkit 1.4.62 or higher (required)
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 trunk
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. However, because of the current synchronization problems with the repository, we recommend the command-line checkout.
Check out with command-line
Check out the [Subversion Subversion repository].
svn co http://dev.itmill.com/svn/trunk/
Notice: Our Trac synchronization causes problems with the Subversion repository so the checkout may fail. If it fails before you get anything, just redo the checkout. If it fails during the checkout, you can continue simply by doing an update:
cd trunk svn update
Check out with Subclipse
Warning: Because of the synchronization problem mentioned above, we recommend that you do not check out the Subversion repository with Eclipse/Subclipse, as it may not handle the error situation properly.
If you nevertheless choose to use Subclipse:
- Switch to the Subversion perspective and add location https://svn.itmill.com/svn/itmill-toolkit.
- Use the Check out as a project configured using the New Project Wizard option.
4. Create the Toolkit Project in Eclipse
To develop IT Mill Toolkit in Eclipse, you need to create a project for it.
- Select File -> New -> Project...
- Select Web -> Dynamic Web Project and click Next.
- Enter a project name, such as tk-trunk
- In Project contents, deselect Use default and using the Browse, select the directory where up checked out the trunk from Subversion.
- For Target runtime, select the Tomcat version you have installed. Click Next.
- In the Project facets view, set version 1.4 for the Java facet. You may have to lower the version for the Dynamic Web Module to 2.4. Click Next.
- In the Web Module view, you can set a more convenient context root than the default, such at tk.
- Click Finish.
The IT Mill Toolkit is now created in Eclipse.
5. Install Google Web Toolkit (GWT)
Most of the required libraries and tools needed for building IT Mill Toolkit are included in the repository. The only exception is GWT. The latest release used with IT Mill Toolkit development is GWT 1.4.62.
Get GWT from Google, or from here: http://dev.itmill.com/svn/gwt/. You need the GWT package for each platform for which you intend to compile IT Mill Toolkit. Normally, if you are just doing development under Eclipse, you just need the package for your platform.
You need to extract GWT under build/gwt directory, e.g. as shown below.
For a single platform (for example ant package-linux):
magi@ungoliant:~/itmill/trunk$ ls -l build/gwt/ yhteensä 95848 drwxr-xr-x 5 magi magi 4096 2008-05-15 12:35 gwt-linux-1.4.62 lrwxrwxrwx 1 magi magi 16 2008-05-15 12:36 linux -> gwt-linux-1.4.62 lrwxrwxrwx 1 magi magi 5 2008-05-15 12:37 gwt -> linux
If you want to build for all platforms (ant package-all):
magi@ungoliant:~/itmill/trunk$ ls -l build/gwt/ yhteensä 95848 drwxr-xr-x 5 magi magi 4096 2008-05-15 12:35 gwt-linux-1.4.62 drwxr-xr-x 5 magi magi 4096 2008-05-15 12:36 gwt-mac-1.4.62 drwxr-xr-x 5 magi magi 4096 2008-05-15 12:35 gwt-mac-1.4.62_leopard drwxr-xr-x 4 magi magi 4096 2008-03-06 09:41 gwt-windows-1.4.62 lrwxrwxrwx 1 magi magi 5 2008-05-15 12:37 gwt -> linux lrwxrwxrwx 1 magi magi 16 2008-05-15 12:36 linux -> gwt-linux-1.4.62 lrwxrwxrwx 1 magi magi 14 2008-05-15 12:36 mac -> gwt-mac-1.4.62 lrwxrwxrwx 1 magi magi 22 2008-05-15 12:37 mac_leopard -> gwt-mac-1.4.62_leopard lrwxrwxrwx 1 magi magi 18 2008-05-15 12:37 windows -> gwt-windows-1.4.62
As done above, you need to make symbolic links from linux, mac, mac_leopard, and windows targets to the corresponding GWT installation directories. These are required by the build.xml script. The compile-gwt-components script also requires a symbolic link from gwt to the gwt installation for your local computer.
Notice that when you uncompress the gwt-leopard package, it is uncompressed under the exactly same directory, gwt-mac-x.x.x, as the gwt-mac is. You should rename the directory as has been done in the directory listing above.
6. Set the build path
You need to include some libraries in the project build path.
- Right-mouse-click on the project to open the context menu and select Properties (or press Alt+Enter when the project is selected).
- Select Java Build Path and select the Libraries tab.
- Click Add JARs... and from the tk-trunk folder, select the following libraries:
- build/gwt/gwt/gwt-dev-linux.jar
- build/gwt/gwt/gwt-servlet.jar
- build/gwt/gwt/gwt-user.jar
- lib/reservr/googlemaps_gwt.jar
- lib/jetty/jetty-x.x.x.jar
- lib/jetty/jetty-util-x.x.x.jar
- lib/jetty/servlet-api-x.x.x.jar
- lib/portlet/portal-kernel.jar
- lib/portlet/portal-service.jar
- lib/portlet/portlet.jar
Click Ok in the JAR Selection window and observe that the JARs are added in the build path.
- Click OK to exit the Properties window.
7. Compile widget sets
Eclipse does not compile the widget sets, i.e., the Client-Side Engine of IT Mill Toolkit, which must be compiled with the GWT Compiler before you can compile IT Mill Toolkit under Eclipse.
You must compile the widget sets (the Client-Side Engine) every time after you or a Subversion update modifies the client-side code. (Unless you use the GWT Hosted-Mode Browser.)
Compiling the widget sets is currently done with the build.xml Ant script in the build directory. In Mac/Linux:
$ cd build
$ ant widgetsets
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.itmill.toolkit.demo.reservation.gwt.ReservationWidgetSet
compile-widgetset-default:
[echo] Compiling src (client-side)
[echo] com.itmill.toolkit.terminal.gwt.DefaultWidgetSet
[java] Output will be written into ./WebContent/ITMILL/widgetsets/com.itmill.toolkit.terminal.gwt.DefaultWidgetSet
[java] Compilation succeeded
[echo] Compiled DefaultWidgetSet
compile-widgetset-colorpicker:
[echo] com.itmill.toolkit.demo.colorpicker.gwt.ColorPickerWidgetSet
[java] Output will be written into ./WebContent/ITMILL/widgetsets/com.itmill.toolkit.demo.reservation.gwt.ReservationWidgetSet
[java] Output will be written into ./WebContent/ITMILL/widgetsets/com.itmill.toolkit.demo.colorpicker.gwt.ColorPickerWidgetSet
[java] Compilation succeeded
[echo] Compiled ColorPickerWidgetSet
[java] Copying all files found on public path
[java] Compilation succeeded
[echo] Compiled ReservationWidgetSet
The build script compiles all the three widget sets included in IT Mill Toolkit: the default widget set and the widget sets for the Color Picker and Reservation demos. If you wish to compile another widget set or avoid building the demo widget sets, just make a custom compilation script.
As you may notice from the example above, the output may be a bit messed up because the script builds the widgetsets in parallel on multicore or multiprocessor systems.
To compile only a specific widgetset, give "ant widgetset-default", "ant widgetset-reserver", or "ant widgetset-colorpicker", as shown in the example below:
$ ant widgetset-default
Buildfile: build.xml
init-platform:
init-nonpackage:
[echo] We are on linux platform, using build/gwt/linux/gwt-dev-linux.jar.
compile-widgetset-default:
[echo] Compiling src (client-side)
[echo] com.itmill.toolkit.terminal.gwt.DefaultWidgetSet
[java] Output will be written into ./WebContent/ITMILL/widgetsets/com.itmill.toolkit.terminal.gwt.DefaultWidgetSet
[java] Copying all files found on public path
[java] Compilation succeeded
[echo] Compiled DefaultWidgetSet
widgetset-default:
BUILD SUCCESSFUL
Total time: 5 seconds
8. Compile IT Mill Toolkit 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).
9. Configure and start Apache Tomcat
You need to add the Toolkit project to the Tomcat service as follows:
- Select the Servers tab in the main window.
- Right-click the Tomcat server and select Add and Remove Projects.
- Select tk-trunk (or whatever you named the project), click Add >, and click Finish.
The project is now added under the Tomcat server. You need to start Tomcat from the start button or select Start from the right-mouse-button context menu.
If you need to restart Tomcat for some reason, just select Restart. If you wish to run it in debug mode, stop it and start it with Debug.
10. Run the demos and tests in your browser
You can now open your browser at http://localhost:8080/tk-trunk/ or what ever your project name is. If you set a different context name above, such as tk, you should use that.
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.
11. Coding conventions
If you intend to develop the IT Mill Toolkit itself and submit code to the community repository, your code must conform to our Coding Conventions.
You should also be able the build the installation package with no warnings or errors. The package is compiled with Java SDK 1.4 compatibility.
12. 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:
- Right-mouse-click on the project to open the context menu and select Properties (or press Alt+Enter when the project is selected).
- Select Validation.
- Select the Override validation preferences.
- 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.
- 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 IT Mill Toolkit installation package
To compile IT Mill Toolkit installation package from the repository, you just run build.xml with ant.
If you have extracted GWT for all platforms (Linux, Mac, and Windows) as instructed above, you can compile Toolkit for all the platforms just by changing to the build directory and running "ant <enter>".
Another solution is to extract only e.g. Windows GWT under build/gwt/windows folder and compile Toolkit release only for the Windows platform by running "ant package-windows <enter>".
Debugging with the Hosted Mode Browser
The Hosted Mode Browser of Google Web Toolkit allows you to debug cliend-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).
13. Troubleshooting
The first things to do if you ever experience any trouble are:
- Run the ant widgetsets (if any client-side code has changed)
- Refresh the project (F5) (if any files have changed outside Eclipse - such as the widget sets)
- Restart Tomcat (if there are "certain kinds of changes")
Restarting Tomcat is necessary, for example, if you edit the web.xml file.
How to get help?
If you have problems with compiling IT Mill Toolkit from the source repository, ask help from http://forum.itmill.com
