Skip to content

Latest commit

 

History

History
185 lines (145 loc) · 10.7 KB

README-DEV.md

File metadata and controls

185 lines (145 loc) · 10.7 KB
Raw

Development Instructions

To contribute, first refer to Contributing Code for general instructions and requirements for contributing code to the Vaadin framework.

We appreciate all contributors and want to make submitting changes as easy as possible. If you find any mistakes, unclear parts or out-of-date instructions, please let us know by submitting an issue or a pull request.

Table of Contents

  1. Building a package
  2. About committing changes
  3. Eclipse quick setup
  4. IntelliJ IDEA quick setup

Building a package

The distribution files can be built by running the standard Maven goal mvn install in the project root.

About committing changes

Despite our best efforts the formatting options aren't always entirely consistent between different development environments, and sometimes we miss inconsistent formatting during code review. When you commit your changes for a pull request, try to make sure that the commit only contains changes that are relevant to your patch, or at least closely affiliated with the relevant changes. Random formatting changes all over the changed file(s) make it difficult to grasp the main purpose of your patch.

Eclipse quick setup

For IntelliJ IDEA users, see IntelliJ IDEA Quick Setup.

  1. Decide where you would like your Eclipse workspace to be located.
    • This project contains multiple modules and uses configurations that might clash with your existing projects, using a separate workspace is recommended.
    • Eclipse Oxygen is recommended, different versions may treat formatting rules differently.
    • If you are using Windows, you may wish to keep the workspace path reasonably short (e.g. C:\dev\<workspaceName>) to avoid problems with too long file paths.
  2. Start Eclipse with your chosen workspace and set up workspace preferences.
  3. Clone the repository within your selected workspace using Eclipse's clone wizard, using your favorite Git tool, or in command-line running git clone https://github.com/vaadin/framework.git command.
    • Eclipse's clone wizard can be found within Git perspective (Window -> Perspectives -> Open Perspective -> Git). Only clone the project at this stage, do not let the clone wizard import projects as well.
    • If using Windows, you might also want to add these Git settings: core.autocrlf=false and core.fileMode=false. You can do this in Eclipse by right-clicking the repository in Git perspective, clicking Properties, then Add Entry... and using key core.autocrlf and value false etc.
    • If too long file paths become a problem you may also need core.longpaths=true.
  4. Import the project into Eclipse as a Maven project. Use File -> Import -> Maven -> Existing Maven Projects.
  5. Select the framework folder (where you cloned the project).
    • It is not necessary to import all the modules, but it is recommended to include at least the root module, vaadin-uitest module, and any modules you may wish to make changes to. You can import more modules when needed by repeating these last steps.
  6. Click “Finish” to complete the import of Vaadin Framework.

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.

General

  1. Open Window -> Preferences (Windows) or Eclipse -> Preferences (Mac)
  2. Go to General -> Workspace
    • Set Text file encoding to UTF-8
    • Set New text file line delimiter to Unix
  3. Go to XML -> XML Files -> Editor
    • Ensure the settings are follows:
      • Line width: 72
      • Format comments: true
      • Join lines: true
      • Insert whitespace before closing empty end-tags: true
      • Indent-using spaces: true
      • Indentation size: 4
  4. Go to Java -> Compiler -> Errors
    • Switch Serializable class without serialVersionUID to Ignore
  5. Go to Java -> Installed JREs
    • Select a Java 8 JDK as the default

Configuration files

  1. Open Window -> Preferences (Windows) or Eclipse -> Preferences (Mac)
  2. Go to Java -> Code Style -> Clean Up
  3. Go to Java -> Code Style -> Formatter

Save actions

  1. Open Window -> Preferences (Windows) or Eclipse -> Preferences (Mac)
  2. Go to Java -> Editor -> Save Actions
    • Check Perform the selected actions on save
      • Check Format source code
        • Select Format edited lines
    • Check Organize imports
    • Check Additional actions
    • Click Configure
      1. In tab Code Organizing
        • Check Remove trailing whitespace
          • Select All lines
        • Uncheck everything else
      2. In tab Code Style
        • Check Use blocks in if/while/for/do statements
          • Select Always
        • Uncheck everything else
      3. In tab Member Accesses
        • Check Use 'this' qualifier for field accesses
          • Select Only if necessary
        • Check Use 'this' qualifier for method accesses
          • Select Only if necessary
        • Uncheck everything else
      4. In tab Missing Code
        • Check Add missing Annotations
          • Check '@Override'
            • Check Implementations of interface methods (1.6 or higher)
          • Check '@Deprecated'
      5. In tab Unnecessary Code
        • Check Remove unused imports and Remove unnecessary casts, uncheck everything else.
      6. Click OK

After that is done, you should have 9 of 28 save actions activated and listed as such:

  • Remove 'this' qualifier for non static field accesses
  • Remove 'this' qualifier for non static method accesses
  • Convert control statement bodies to block
  • Remove unused imports
  • Add missing '@Override' annotations
  • Add missing '@Override' annotations to implementations of interface methods
  • Add missing '@Deprecated' annotations
  • Remove unnecessary casts
  • Remove trailing white spaces on all lines

Getting started

Run the install maven goal for the project root to get started. In Eclipse this is done by right-clicking on the project root in Project Explorer and choosing Run As -> Maven Build.... If you choose to skip tests you may need to run the install maven goal for vaadin-uitest project separately.

  • Note that the first compilation takes a while to finish as Maven downloads dependencies used in the projects.

Now the project should compile without further configuration.

Compiling the default widgetset and themes

  • Compile the default widgetset by running install maven goal in vaadin-client-compiled module root. In Eclipse this is done by right clicking on vaadin-client-compiled project in Project Explorer and choosing Run As -> Maven Build.... You don't need to do this separately if you have already run install for the root project after your latest changes.
  • Compile the default themes by running install maven goal in vaadin-themes module root. In Eclipse this is done by right clicking on vaadin-themes project in Project Explorer and choosing Run As -> Maven Build.... You don't need to do this separately if you have already run install for the root project after your latest changes.

Running a UI test

Using DevelopmentServerLauncher (recommended)

  1. In a Project Explorer navigate to vaadin-uitest/src/main/java/com/vaadin/launcher
  2. Right-click file DevelopmentServerLauncher.java
  3. Open Run As -> Java Application
  4. Open URL http://localhost:8888/run/<testUI>

Using Jetty

  1. In a Project Explorer right-click vaadin-uitest
  2. Open Run As -> Maven build...
  3. Type in jetty:run-exploded into Goals and click Run
  4. Open URL http://localhost:8888/run/<testUI>

For full instructions please visit README-TESTS.md.

IntelliJ IDEA quick setup

For Eclipse users, see Eclipse Quick Setup.

  1. Install and run IDEA. Ultimate Edition is better but Community Edition should also work.
  2. Ensure if Git and Maven plugins are installed, properly configured and enabled.
  3. Clone the repository, using menu VCS -> Checkout from Version Control -> Git -> Git Repository URL -> https://github.com/vaadin/framework.git. When the repository is cloned, do NOT open it as a project.
    • If you are using Windows, you may wish to keep the workspace path reasonably short (e.g. C:\dev\<workspaceName>) to avoid problems with too long file paths.
  4. Open cloned repository as a maven object. Use File -> Open and choose root pom.xml file
  5. Have a coffee break while IDEA is loading dependencies and indexing the project
  6. Run Maven targets clean and install using Maven Projects tool window to compile the whole project

Unfortunately there is no easy way to replicate Eclipse workspace preferences in their entirety in IDEA, but you can use Eclipse Code Formatter plugin to import eclipse/VaadinCleanup.xml and eclipse/VaadinJavaConventions.xml as a starting point.

Running a specific UI test

  1. Open Maven Projects
  2. Open vaadin-uitest -> Plugins -> jetty -> jetty:run-exploded
  3. Open URL http://localhost:8888/run/<testUI>

For full instructions please visit README-TESTS.md.

Running a development server

  1. Open Run menu and click Edit Configurations
  2. Click green + sign at top left corner, select Maven from popup
  3. In the run configuration page, set any name for the configuration, select vaadin-uitest project folder as Working directory
  4. Type exec:exec@run-development-server into Command line and save the configuration
  5. Run the configuration and open URL http://localhost:8888/run/<testUI>

Running a development server in a debug mode

  1. Type exec:exec@debug-development-server into Command line and save the configuration
  2. In the same dialog, create new "Remote" debug configuration, using localhost and Port 5005
  3. Start both configurations and open URL http://localhost:8888/run/<testUI>