If you are interested in understanding the internals of Google Web Toolkit (GWT), building from source, or contributing ideas or modifications to the project, then this document is for you.
To start with the basics, why does GWT exist in the first place? The short answer is that GWT exists to make the web better for users. We've infused a slightly longer answer into our mission statement:
GWT's mission is to radically improve the web experience for users by enabling developers to use existing Java tools to build no-compromise AJAX for any modern browser.
We spent a lot of time on that sentence and really tried to pack it with meaning. So, if you'll indulge us, let's explain why our mission statement is formulated the way that it is:
to radically improve
the web experience
for users
by enabling developers
existing Java tools
no-compromise AJAX
any modern browser
So that's what GWT is all about. It's also useful to say what kinds of things GWT isn't about...
All GWT source and pre-built binaries are provided under the Apache 2.0 license.
A good first question is, "Why wasn't GWT open source to begin with?" Since GWT's release in May 2006 at JavaOne, we've tried to stay totally focused on lowering the barrier for building AJAX apps. We weren't quite ready to open source the whole thing immediately because we knew we had plans for major infrastructure work (like Mac OS X hosted mode), and we really wanted to encourage everyone to focus on the idea of the product itself and how to write apps instead of creating distractions having to do with GWT's open sourceness.
GWT took off much faster than we expected, and it quickly became clear that the most sensible way to advance GWT would be to open it sooner rather than later. While we've never actually felt particularly stingy about keeping the source closed, now all code for the GWT Java to JavaScript compiler, the hosted mode browser, and so on can progress before your eyes. We're very much looking forward to contributions of ideas, bug reports, and patches.
We adopted these on February 17, 2006.
The GWT community exists primarily through mailing lists, the issue tracker and, to a lesser extent, the source control repository. You are definitely encouraged to contribute to the discussion and you can also help us to keep the effectiveness of the groups high by following and promoting the guidelines listed here.
Showing courtesy and respect to others is a vital part of the Google culture, and we strongly encourage everyone participating in GWT development to join us in accepting nothing less. Of course, being courteous is not the same as failing to constructively disagree with each other, but it does mean that we should be respectful of each other when enumerating the 42 technical reasons that a particular proposal may not be the best choice. There's never a reason to be antagonistic or dismissive toward anyone who is sincerely trying to contribute to a discussion.
Sure, web development is serious business and all that, but it's also a lot of fun. Let's keep it that way. Let's strive to be one of the friendliest communities in all of open source.
As always, discuss using GWT in the official Google Web Toolkit (GWT) developer discussion group. There is an additional group for people to discuss any of the stuff in this document (e.g. how to build, how to submit patches) called GWT Contributors. You don't have to actually submit code in order to sign up. Your participation itself is a valuable contribution.
If you want to get your hands dirty with the code inside GWT, this is the section for you.
Checking out the GWT source is most useful if you plan to compile GWT yourself. The pre-built GWT distribution already contains all the Java source, so you don't actually need to check it out from the repository just to debug through it. Just tweak your IDE to read source from the GWT jars.
GWT is hosted on Google Code project hosting, so you check out the source for GWT using a Subversion client as you would for any other project hosted on Google Code:
svn checkout http://google-web-toolkit.googlecode.com/svn/trunk/ trunk
The project source code access page has additional instructions for browsing the source online or getting a Subversion client if you don't already have one.
Other than a few native libs, everything is Java source that can be built on any supported platform with the included GWT Ant build files. At the moment, you can only build the native code binaries on Linux, and even then with a bit of effort that is currently beyond the scope of this document. To keep things simple, we've checked in pre-built native binaries. (Yes, we know that's unusual. But the source and makefiles are all there...it's just a pain to doc all that and make it build in a cross-platform way.)
|
ant command is in
your path.~/gwt$ svn checkout http://google-web-toolkit.googlecode.com/svn/tools/ tools
~/gwt$ svn checkout http://google-web-toolkit.googlecode.com/svn/trunk/ trunk
tools directory is a sibling of the GWT source
directory, you don't have to specify GWT_TOOLS.) In this
example, you executed the previous command from the directory ~/gwt,
so you'd type:~/gwt$ export GWT_TOOLS=~/gwt/tools
~/gwt/trunk.
Make sure you're in that directory... ~/gwt$ cd ~/gwt/trunkthen just invoke Ant
ant
build/dist
subdirectory of the source root directory. In this example, the
distributions would be in ~/gwt/trunk/build.
Testing is very important to maintaining the quality of GWT.
Unit Tests should be written for any new code, and
changes should be verified to not break existing tests before they
are submitted for review. To perform the tests, simply run ant test
and verify that there are no failures.
There is a problem, detailed at ant.apache.org, where ant cannot find the JUnit classes. The simple workaround is to either:
/usr/share/ant/lib/)Now that GWT is open source, we're excited that it is now easier for our users to fix bugs and create new features, and we hope to get great patches from the community. Before you fire up your favorite IDE and begin hammering away at that new feature, though, please take the time to read this section and understand the process. While it seems rigorous, we want to keep a high standard of quality in the code base. Also, please be aware that we code contributors must sign a Contributor License Agreement before we can accept any code.
To keep the source consistent, readable, diffable and easy to merge, we use a fairly rigid coding style, and all patches will be expected to conform to the style outlined here. To keep things as simple as possible, many of these style rules will be automatically verified by the GWT build; style issues that can't be caught by the build system should be addressed during code review.
In general, the GWT style is based on the standard Java conventions, except for the differences spelled out below.
For the record, we know that coding style is often a controversial topic. We acknowledge that plenty of great approaches exist out there. We're simply trying to pick one that is at least somewhat consistent with Sun's Java coding conventions, codify it well, and stick to it.
Every file should have an Apache license header at the top, prefaced with a copyright notice. A package statement and import statements should follow, each block separated by a blank line. Next is the class or interface declaration. In the Javadoc comments, describe what the class or interface does.
/*
* Copyright 2006 Google Inc.
*
* Licensed under the Apache License, Version 2.0 (the "License"); you may not
* use this file except in compliance with the License. You may obtain a copy of
* the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
* WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
* License for the specific language governing permissions and limitations under
* the License.
*/
package com.google.foo;
import com.google.bar.Blah;
import com.google.bar.Yada;
import java.sql.ResultSet;
import java.sql.SQLException;
/**
* Does X and Y and provides an abstraction for Z.
*/
public class Foo {
...
}
Java types should have the following member order:
Members that fall into the same category (e.g. static methods) should also be sorted in this order based on visibility:
All methods should be sorted alphabetically. Sorting is optional but recommended for fields. For example, the following class excerpt is correctly sorted:
public abstract class Foo {
// Type declarations.
public class FooBaz {
}
private class FooBar {
}
// Static field declarations.
// Remember, fields do NOT need to be sorted.
static String B;
static String A;
// Static initializer declarations.
static {
}
// Static methods declarations.
// Remember, methods do need to be sorted.
static void aStatic() {
}
static void bStatic() {
}
// Instance field declaration.
String bField;
String aField;
// Instance Initializer declarations.
{
}
// Constructors declaration.
public Foo() {
}
protected Foo(String s) {
}
Foo(int i) {
}
private Foo(boolean b) {
}
// Instance method declaration.
public void b() {
}
public void c() {
}
protected void a() {
}
protected void d() {
}
protected void e() {
}
protected void f() {
}
String h() {
}
// The "abstract" keyword does not modify the position of the method.
abstract String i();
void j() {
}
private void g() {
}
}
We use 2-space indents for blocks. No tabs at all, anywhere.
We use 4-space indents after line wraps, including function calls and assignments. For example, this is correct (4 spaces after the newline):
Instrument i =
new Instrument();
and this is not correct (2 spaces after the newline):
Instrument i = new Instrument();
The ordering of import statements is:
To exactly match the IDE settings, the imports should be:
Each line of text in your code should be at most 80 characters long. Use linefeed characters to break lines (Unix-style). There are some exceptions:
Treat acronyms and abbreviations as words. The names are much more readable:
| Good | Bad |
|---|---|
XmlHttpRequest |
XMLHTTPRequest |
getCustomerId |
getCustomerID |
This style rule also applies when an acronym or abbreviation is the entire name:
| Good | Bad |
|---|---|
class Html |
class HTML |
String url; |
String URL; |
long id; |
long ID; |
Note that this is a reversal of an earlier, regretted decision, and much code in GWT violates this rule. While it's not worth breaking existing APIs for stylistic concerns, all new code should treat acronyms as words.
For further justifications of this style rule, see Effective Java Item 56 (Item 38 in 1st edition) and Java Puzzlers Number 68.
Parameterized type names should be one capital letter. However, if readability demands longer names (particularly due to having multiple parameters), the name should be capitalized and have suffix "T". In a nutshell, prefer <T> or <K, V>, and devolve to <KeyT, ValueT> if necessary.
| Good | Bad | Tolerable |
|---|---|---|
Foo<T> |
Foo<FooClientType> |
|
Bar<K, V> |
Bar<KeyType, ValueType> |
|
Baz<V, E, X> |
Baz<EventType, ErrorType, ExpressionType> |
Baz<EventT, ErrorT, ExpressionT> |
Unit tests are very important, and we strongly encourage submissions that include them, adding new unit tests for new functionality or updating existing unit tests for bug fixes.
Tests for Java classes should be placed in a parallel source tree
under test and the test class name should be suffixed with
Test. For example:
src/com/google/gwt/core/client/EntryPoint.java test/com/google/gwt/core/client/EntryPointTest.java
The use of the parallel test tree has two major advantages:
tests
subpackage).Note that there is a problem using JUnit tests with ant — a workaround is described above.
Please do submit code. Here's what you need to do:
svn diff).The current members of the GWT engineering team are the only committers at present. In the great tradition of eating one's own dogfood, we will be requiring each new GWT engineering team member to earn the right to become a committer by following the procedures in this document, writing consistently great code, and demonstrating repeatedly that he or she truly gets the zen of GWT.
Before we can accept a patch from you, you must sign a Contributor License Agreement (CLA). The CLA protects you and us.
Follow either of the two links above to access the appropriate CLA and instructions for how to sign and return it.