From a1b265c318dbda4a213cec930785b81e4c0f7d2b Mon Sep 17 00:00:00 2001
From: elmot <elmot@vaadin.com>
Date: Fri, 25 Sep 2015 16:40:44 +0300
Subject: Framework documentation IN

Change-Id: I767477c1fc3745f9e1f58075fe30c9ac8da63581
---
 .../getting-started-environment.asciidoc           | 238 +++++++++++++++++++++
 1 file changed, 238 insertions(+)
 create mode 100644 documentation/getting-started/getting-started-environment.asciidoc

(limited to 'documentation/getting-started/getting-started-environment.asciidoc')

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.
+
+
+
+
+
-- 
cgit v1.2.3

