Easier instructions thanks to GWT dependency (#13616)

Change-Id: I42034e50e314c13282614d5a7ab64368daca1b31

1 files changed, 44 insertions, 71 deletions

diff --git a/README.md b/README.md
index 7f9c1fdabc..6e8820bec8 100644
--- a/README.md
+++ b/README.md
@@ -11,34 +11,32 @@ for general instructions and requirements for contributing code to the Vaadin fr
 Instructions on how to set up a working environment for developing the Vaadin
 framework follow below.
 
-Cloning the project repositories
+Quick Setup
 ======
+1. <code>git clone https://github.com/vaadin/vaadin.git</code>
+1. Import the project into Eclipse
+1. Install IvyDE if needed (http://www.apache.org/dist/ant/ivyde/updatesite)
+1. Run build/ide.xml in Eclipse
 
-Vaadin 7 consists of three separate repositories
-* https://github.com/vaadin/vaadin.git
-* https://github.com/vaadin/gwt.git
-* https://github.com/vaadin/gwt-tools.git
-
-Start by cloning these repositories **into the same folder**:
-<pre><code>git clone https://github.com/vaadin/vaadin.git
-git clone https://github.com/vaadin/gwt.git
-git clone https://github.com/vaadin/gwt-tools.git</code></pre>
+For more details, see below
 
-The *vaadin* and *gwt* repositories contain project code. The *gwt-tools* project only contain dependency jars used by the other projects.
+Cloning the project repositories
+======
+The Vaadin repository can be cloned using
+<pre><code>git clone https://github.com/vaadin/vaadin.git</code></pre>
 
-Do not rename the repositories as the rest of this document relies on using the standard naming.
+or using your favorite Git tool
 
 Setting up Eclipse to Develop Vaadin 7
 =========
-Assuming you have cloned the repositories as described in “Cloning the project repositories” above, you can import the *vaadin* and *gwt* projects into Eclipse as follows:
 
 Start Eclipse
 -------------
-Start Eclipse and **use the root checkout folder** (the one containing the *vaadin*, *gwt* and *gwt-tools* folders) **as the workspace folder**
+Start Eclipse with the workspace you would like to use. It is usually a good idea to use the parent folder of the Git repository as the workspace folder.
 
 Install IvyDE
 ---------
-You'll need the Apache Ivy plug-in for Eclipse to build the project later on, in “Compiling the Default Widget Set and Themes”.
+You'll need the Apache Ivy plug-in for Eclipse to build the project:
 
 1. Go to *Help* -> *Install New Software...*
 1. Enter `http://www.apache.org/dist/ant/ivyde/updatesite` in the "Work with:" text field
@@ -49,25 +47,35 @@ If you have installed IvyDE via the Eclipse Marketplace previously, **make sure*
 1. Go to *Help* -> *Install New Software...*
 1. Click the hyperlink in the "What is already installed?" sentence near the bottom right-hand corner
 1. Verify that the list includes *Apache Ivy Ant Tasks*
+1. If it isn't included, follow the installation process above, but select only *Apache Ivy library* > *Apache Ivy Ant Tasks*
+
+
+Import the Project into the Workspace
+------------
+1. Do *File* -> *Import* -> *General* -> *Existing Projects into Workspace*
+![ImportProject](http://f.cl.ly/items/0G361519182v1z2T1o1O/Import.png "Import project")
+1. Select the *vaadin* folder (where you cloned the project)
+1. Ensure the *vaadin* project is checked
+1. Click “finish” to complete the import of Vaadin Framework
+
+The project should compile without further configuration. If the project does not compile without errors, choose *Ivy* -> *Resolve* from the vaadin project popup menu to ensure all dependencies have been resolved.
 
-If it isn't included, follow the installation process above, but select only *Apache Ivy library* > *Apache Ivy Ant Tasks*
+Note that the first compilation takes a while to finish as Ivy downloads dependencies used in the projects.
+
+Compiling the Default Widget Set and Themes
+--------
+Compile the default widget set by executing the default target in build/ide.xml in the vaadin project.
+In Eclipse this is done by opening build/ide.xml, right clicking on it and choosing *Run As* -> *Ant Build*.
+![CompileWidgetSet](http://cl.ly/image/1R43162b282e/build.png "Compiling the Widget Set")
 
-Set up the Workspace and define required variables for projects
+Set up extra workspace preferences
 --------
+The following preferences need to be set to keep the project consistent. You need to do this especially to be able to contribute changes to the project.
+
 1. Open *Window* -> *Preferences* (Windows) or *Eclipse* -> *Preferences* (Mac)
 1. Go to *General* ->  *Workspace*
  1. Set *Text file encoding* to *UTF-8*
  1. Set *New text file line delimiter* to *Unix*
-1. Go to *General* ->  *Workspace* -> *Linked Resources*
-1. Add a new Path Variable **GWT_ROOT** referring to the gwt folder containing the gwt project
-![GWT_ROOT](http://f.cl.ly/items/430q0H0z3t362Z1A1n3L/LinkedResources.png "Defining GWT_ROOT")
-1. Go to *Java* -> *Build Path* -> *Classpath Variables*
-1. Add two new variables
-  1. GWT_TOOLS referring to the gwt-tools folder containing the dependency jars
-  1. JDK_HOME referring to your jdk installation directory
-     ![GWT_TOOLS](http://f.cl.ly/items/1k2Z1n2v0p0y3l0X0D1G/ClasspathVars.png "Defining GWT_TOOLS")
-1. Go to Java -> Compiler
-  1. Check that the compliance level has been set to 1.6
 1. Go to XML -> XML Files -> Editor
  1. Ensure the settings are follows:
 <pre><code>Line width: 72
@@ -78,61 +86,26 @@ Indent-using spaces: true
 Indentation size: 4
 </code></pre>
 
-Import the Projects into the Workspace
-------------
-1. Do *File* -> *Import* -> *General* -> *Existing Projects into Workspace*
-![ImportProject](http://f.cl.ly/items/0G361519182v1z2T1o1O/Import.png "Import project")
-1. Select the workspace folder as root directory
-1. Click “deselect all” and select
-  1. gwt-dev
-  2. gwt-user
-1. Click “finish” to complete the import of GWT
-1. Then repeat by doing *File* -> *Import* -> *General* -> *Existing Projects into Workspace*
-1. Select the workspace folder as root directory
-1. Click “deselect all” and select
-  1. vaadin
-1. Click “finish” to complete the import of Vaadin Framework
-
-![FinishImportProject](http://cl.ly/image/2W3S0P2c2p1t/Import2.png "Finishing Project Import")
-
-You should now have three projects in your workspace. If the vaadin project does not compile without errors, choose *Ivy* -> *Resolve* from the vaadin project popup menu. Now all projects should compile without errors (there might be warnings).
-
-Note that the first compilation takes a while to finish as Ivy downloads dependencies used in the projects.
-
-Compiling the Default Widget Set and Themes
---------
-Compile the default widget set by executing the default target in build/ide.xml in the vaadin project.
-In Eclipse this is done by opening build/ide.xml, right clicking on it and choosing *Run As* -> *Ant Build*.
-![CompileWidgetSet](http://cl.ly/image/1R43162b282e/build.png "Compiling the Widget Set")
-
 Running a UI test
 ------
-The *vaadin* project includes an embedded Jetty which is used for running the UI tests.
-It is a standard Java application: *com.vaadin.launcher.DevelopmentServerLauncher*.
-Launch it in debug mode in Eclipse by right clicking on it and selecting *Debug As* -> *Java Application*.
+The *vaadin* project includes an embedded Jetty (*com.vaadin.launcher.DevelopmentServerLauncher*) which is used for running the UI tests.
+In Eclipse you can launch it using the included launch configuration: Right click on *eclipse/Development Server (vaadin).launch" and select *Debug As* -> *Development Server (vaadin)*.
 
-This launches a Jetty on port 8888 which allows you to run any UI class in the project by opening http://localhost:8888/run/&lt;UI class name&gt;?restartApplication in your browser, e.g. [http://localhost:8888/run/com.vaadin.tests.components.label.LabelModes?restartApplication](http://localhost:8888/run/com.vaadin.tests.components.label.LabelModes?restartApplication) (Add ?restartApplication to ensure).
+This launches a Jetty on port 8888 which allows you to run any UI class in the project by opening http://localhost:8888/run/&lt;UI class name&gt;?restartApplication in your browser, e.g. [http://localhost:8888/run/com.vaadin.tests.components.label.LabelModes?restartApplication](http://localhost:8888/run/com.vaadin.tests.components.label.LabelModes?restartApplication) (Use ?restartApplication to ensure the correct UI is shown).
 
 Running JUnit tests
 =====
-The JUnit tests for the projects can be run using
+The unit tests for the projects can be run using
 <pre><code>ant test</code></pre>
 
-Running this in the *gwt* directory will run the GWT JUnit tests.
-Running it in the *vaadin* directory will run the Vaadin JUnit tests.
-
-Note that the included Vaadin TestBench (browser) tests currently requires access to a TestBench cluster, which is currently only available internally at Vaadin Ltd.
+Note that the included Vaadin TestBench (browser) tests require access to a TestBench cluster, currently only available internally at Vaadin Ltd.
 
 Building a package
 =====
-The distribution files can be built in a few steps. First build the *gwt* project by running
-<pre><code>ant</code></pre>
-in the *gwt* directory. The elemental package needs to be built separately:
-<pre><code>ant elemental</code></pre>
-Building the elemental package is not possible on Windows as it requires gcc.
+The distribution files can be built in two steps. 
 
-Move to the *vaadin* project directory and unpack the previously built gwt jars
+1. Unpack required gwt jars into the project
 <pre><code>ant -f gwt-files.xml unpack.gwt</code></pre>
-Then build the *vaadin* project by running
+2. Build the project by running
 <pre><code>ant</code></pre>
-in the *vaadin* directory.
+in the project root directory (add -Dvaadin.version=1.2.3 to use a specific version number).