diff options
Diffstat (limited to 'README.md')
| -rw-r--r-- | README.md | 115 |
1 files changed, 44 insertions, 71 deletions
@@ -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. Install IvyDE, including Ant Tasks, if needed (http://www.apache.org/dist/ant/ivyde/updatesite) +1. Import the project into Eclipse +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* + +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*. + -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 - -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 -  -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* - -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 - - - -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*. - - 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/<UI class name>?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/<UI class name>?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). |