diff options
Diffstat (limited to 'documentation/getting-started/getting-started-environment.asciidoc')
| -rw-r--r-- | documentation/getting-started/getting-started-environment.asciidoc | 226 |
1 files changed, 0 insertions, 226 deletions
diff --git a/documentation/getting-started/getting-started-environment.asciidoc b/documentation/getting-started/getting-started-environment.asciidoc deleted file mode 100644 index 457cf524ab..0000000000 --- a/documentation/getting-started/getting-started-environment.asciidoc +++ /dev/null @@ -1,226 +0,0 @@ ---- -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>##/jdk-[replaceable]##<version>##.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_31 -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#. -You can start it from there by double clicking [filename]#eclipse.exe#. - -=== Linux / OS X / UNIX - -We recommend that you install Eclipse manually in Linux and other UNIX variants. -They may have it available from a package repository, but using such an installation may cause problems with installing plug-ins. - -You can install Eclipse 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, which makes installation of plug-ins easier. -Eclipse also stores some user settings in the installation directory. -+ -To install the package, enter: -+ -[subs="normal"] ----- -[prompt]#$# [command]#tar# zxf [replaceable]##<path>##/eclipse-jee-[replaceable]##<version>##.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. |