diff options
Diffstat (limited to 'documentation/getting-started/getting-started-environment.asciidoc')
| -rw-r--r-- | documentation/getting-started/getting-started-environment.asciidoc | 238 |
1 files changed, 238 insertions, 0 deletions
diff --git a/documentation/getting-started/getting-started-environment.asciidoc b/documentation/getting-started/getting-started-environment.asciidoc new file mode 100644 index 0000000000..118742be38 --- /dev/null +++ b/documentation/getting-started/getting-started-environment.asciidoc @@ -0,0 +1,238 @@ +--- +title: Setting up the Development Environment +order: 2 +layout: page +--- + +[[getting-started.environment]] += Setting up the Development Environment + +This section guides you step-by-step in setting up a reference development +environment. Vaadin supports a wide variety of tools, so you can use any IDE for +writing the code, almost any Java web server for deploying the application, most +web browsers for using it, and any operating system platform supported by Java. + +In this example, we use the following toolchain: + +* Windows, Linux, or Mac OS X +* link:http://www.oracle.com/technetwork/java/javase/downloads/index.html[Oracle Java SE 8] (Java 6 or newer is required) +* link:http://www.eclipse.org/downloads/[Eclipse IDE for Java EE Developers] +* link:http://tomcat.apache.org/[Apache Tomcat 8.0 (Core)] +* link:http://www.getfirefox.com/[Mozilla Firefox] browser +* link:http://www.getfirebug.com/[Firebug] debug tool (optional) +* link:http://vaadin.com/download/[Vaadin Framework] + +The above reference toolchain is a good choice of tools, but you can use almost +any tools you are comfortable with. + +We recommend using Java 8 for Vaadin development, but you need to make sure that +your entire toolchain supports it. A server supporting Servlet 3.0 is +recommended. It is required for using Vaadin CDI, for which also a CDI container +is required, a standard feature in Java EE 6 or newer servers. It is also +required by the Vaadin Spring add-on. Server push can benefit from using +communication modes, such as WebSocket, enabled by features in some latest +servers. For Java EE containers, at least Wildfly, Glassfish, and Apache TomEE +Web Profile are recommended. + +[[figure.toolchain]] +.Development Toolchain and Process +image::img/toolchain-hi.png[] + +<<figure.toolchain>> illustrates the development toolchain. You develop your +application as an Eclipse project. The project must include, in addition to your +source code, the Vaadin libraries. It can also include project-specific themes. + +You need to compile and deploy a project to a web container before you can use +it. You can deploy a project through the Web Tools Platform (WTP) for Eclipse +(included in the Eclipse EE package), which allows automatic deployment of web +applications from Eclipse. You can also deploy a project manually, by creating a +web application archive (WAR) and deploying it to the web container. + +[[getting-started.environment.java]] +== Installing Java SDK + +Java SDK is required by Vaadin and also by the Eclipse IDE. Vaadin is compatible +with Java 1.6 and later editions. Java EE 7 is required for proper server push +support with WebSockets. + +[[getting-started.environment.java.windows]] +=== Windows + +. Download Oracle Java SE 8.0 from +link:http://www.oracle.com/technetwork/java/javase/downloads/index.html[http://www.oracle.com/technetwork/java/javase/downloads/index.html] + +. Install the Java SDK by running the installer. The default options are fine. + + + +[[getting-started.environment.linux]] +=== Linux / UNIX + +Most Linux systems either have JDK preinstalled or allow installing it through a +package management system. Notice however that they have OpenJDK as the default +Java implementation. While it is known to have worked with Vaadin and possibly +also with the development toolchain, we do not especially support it. + +Regarding OS X, notice that JDK 1.6 or newer is included in OS X 10.6 and newer. + +Otherwise: + +. Download Oracle Java SE 8.0 from +link:http://www.oracle.com/technetwork/java/javase/downloads/index.html[http://www.oracle.com/technetwork/java/javase/downloads/] + +. Decompress it under a suitable base directory, such as [filename]#/opt#. For +example, for Java SDK, enter (either as root or with [command]#sudo# in Linux): + + ++ +[subs="normal"] +---- +[prompt]#+++#+++# [command]#cd# [replaceable]#/opt# +[prompt]#+++#+++# [command]#sh# [replaceable]#(path-to-installation-package)/jdk-8u20-linux-x64.bin# +---- ++ +and follow the instructions in the installer. + +. Set up the [literal]#++JAVA_HOME++# environment variable to point to the Java +installation directory. Also, include the [literal]#++$JAVA_HOME/bin++# in the +[literal]#++PATH++#. How you do that varies by the UNIX variant. For example, in +Linux and using the Bash shell, you would add lines such as the following to the +[filename]#.bashrc# or [filename]#.profile# script in your home directory: + + ++ +---- +export JAVA_HOME=/opt/jdk1.8.0_20 +export PATH=$PATH:$HOME/bin:$JAVA_HOME/bin +---- ++ +You could also make the setting system-wide in a file such as +[filename]#/etc/bash.bashrc#, [filename]#/etc/profile#, or an equivalent file. +If you install Apache Ant or Maven, you may also want to set up those in the +path. + ++ +Settings done in a [filename]#bashrc# file require that you open a new shell +window. Settings done in a [filename]#profile# file require that you log in into +the system. You can, of course, also give the commands in the current shell. + + + + +[[getting-started.environment.eclipse]] +== Installing Eclipse IDE + +=== Windows + +. Download the Eclipse IDE for Java EE Developers from +link:http://www.eclipse.org/downloads/[http://www.eclipse.org/downloads/] + +. Decompress the Eclipse IDE package to a suitable directory. You are free to +select any directory and to use any ZIP decompressor, but in this example we +decompress the ZIP file by just double-clicking it and selecting "Extract all +files" task from Windows compressed folder task. In our installation example, we +use [filename]#C:\dev# as the target directory. + + +Eclipse is now installed in [filename]#C:\dev\eclipse# and can be started from +there (by double clicking eclipse.exe). + + +=== Linux / OS X / UNIX + +We recommend that you install Eclipse manually in Linux and other UNIX variants +as follows. + +. Download Eclipse IDE for Java EE Developers from +link:http://www.eclipse.org/downloads/[http://www.eclipse.org/downloads/] + +. Decompress the Eclipse package into a suitable base directory. It is important +to make sure that there is no old Eclipse installation in the target directory. +Installing a new version on top of an old one probably renders Eclipse unusable. + +. Eclipse should normally be installed as a regular user, as this makes +installation of plugins easier. Eclipse also stores some user settings in the +installation directory. To install the package, enter: + + ++ +[subs="normal"] +---- +[prompt]#$# [command]#tar# zxf [replaceable]#(path-to-installation-package)/eclipse-jee-ganymede-SR2-linux-gtk.tar.gz# +---- ++ +This will extract the package to a subdirectory with the name +[filename]#eclipse#. + +. If you wish to enable starting Eclipse from command-line, you need to add the +Eclipse installation directory to your system or user PATH, or make a symbolic +link or script to point to the executable. + + +An alternative to the above procedure would be to use an Eclipse version +available through the package management system of your operating system. It is, +however, __not recommended__, because you will need write access to the Eclipse +installation directory to install Eclipse plugins, and you may face +incompatibility issues with Eclipse plugins installed by the package management +of the operating system. + + + +[[getting-started.environment.tomcat]] +== Installing Apache Tomcat + +Apache Tomcat is a lightweight Java web server suitable for both development and +production. There are many ways to install it, but here we simply decompress the +installation package. + +__Apache Tomcat should be installed with user permissions.__ During development, +you will be running Eclipse or some other IDE with user permissions, but +deploying web applications to a Tomcat server that is installed system-wide +requires administrator or root permissions. + +. Download the installation package: + ++ +Apache Tomcat 8.0 (Core Binary Distribution) from http://tomcat.apache.org/ + +. Decompress Apache Tomcat package to a suitable target directory, such as +[filename]#C:\dev# (Windows) or [filename]#/opt# (Linux or Mac OS X). The Apache +Tomcat home directory will be [filename]#C:\dev\apache-tomcat-8.0.x# or +[filename]#/opt/apache-tomcat-8.0.x#, respectively. + + + +[[getting-started.environment.firefox]] +== Firefox and Firebug + +Vaadin supports many web browsers and you can use any of them for development. +If you plan to create a custom theme, customized layouts, or create new +components, we recommend that you use either Firefox together with Firebug or +Google Chrome, which has built-in developer tools similar to Firebug. + +[[getting-started.environment.firefox.firebug]] +=== Using Firebug with Vaadin + +After installing Firefox, use it to open +link:http://www.getfirebug.com/[http://www.getfirebug.com/]. Follow the +instructions on the site to install the latest stable version of Firebug +available for the browser. You may need to allow Firefox to install the plugin +by clicking the yellow warning bar at the top of the browser window. + +After Firebug is installed, it can be enabled at any time from the Firefox +toolbar. <<figure.firebug.calc>> shows Firebug in action. + +[[figure.firebug.calc]] +.Firebug Debugger for Firefox +image::img/firebug.png[] + +The most important feature in Firebug is inspecting HTML elements. Right-click +on an element and select [guilabel]#Inspect Element with Firebug# to inspect it. +In addition to HTML tree, it also shows the CSS rules matching the element, +which you can use for building themes. You can even edit the CSS styles live, to +experiment with styling. + + + + + |