From a1b265c318dbda4a213cec930785b81e4c0f7d2b Mon Sep 17 00:00:00 2001 From: elmot Date: Fri, 25 Sep 2015 16:40:44 +0300 Subject: Framework documentation IN Change-Id: I767477c1fc3745f9e1f58075fe30c9ac8da63581 --- .../getting-started/getting-started-maven.asciidoc | 133 +++++++++++++++++++++ 1 file changed, 133 insertions(+) create mode 100644 documentation/getting-started/getting-started-maven.asciidoc (limited to 'documentation/getting-started/getting-started-maven.asciidoc') diff --git a/documentation/getting-started/getting-started-maven.asciidoc b/documentation/getting-started/getting-started-maven.asciidoc new file mode 100644 index 0000000000..3914e973aa --- /dev/null +++ b/documentation/getting-started/getting-started-maven.asciidoc @@ -0,0 +1,133 @@ +--- +title: Using Vaadin with Maven +order: 6 +layout: page +--- + +[[getting-started.maven]] += Using Vaadin with Maven + +((("Maven", "creating a project", id="term.maven.creating", range="startofrange"))) + + +Maven is a commonly used build and dependency management system. The Vaadin core +library and all Vaadin add-ons are available through Maven. You can use a Maven +with a front-end from Eclipse or NetBeans, or by using the command-line as +described in this section. + +In addition to regular Maven, you can use any Maven-compatible build or +dependency management system, such as Ivy or Gradle. For Gradle, see the +link:https://github.com/johndevs/gradle-vaadin-plugin[Gradle Vaadin Plugin]. +Vaadin Plugin for Eclipse uses Ivy for resolving dependencies in Vaadin +projects, and it should provide you with the basic Ivy configuration. + +[[getting-started.maven.command-line]] +== Working from Command-Line + +You can create a new Maven project with the following command (given in one +line): + +[subs="normal"] +---- +[prompt]#$# [command]#mvn# archetype:generate \ + -DarchetypeGroupId=com.vaadin \ + -DarchetypeArtifactId=[parameter]#vaadin-archetype-application# \ + -DarchetypeVersion=[replaceable]#7.x.x# \ + -DgroupId=[replaceable]#your.company# \ + -DartifactId=[replaceable]#project-name# \ + -Dversion=[replaceable]#0.1# \ + -Dpackaging=war +---- +The parameters are as follows: + +[parameter]#archetypeGroupId#:: The group ID of the archetype is [literal]#++com.vaadin++# for Vaadin +archetypes. + +[parameter]#archetypeArtifactId#:: The archetype ID. Vaadin 7 currently supports +[literal]#++vaadin-archetype-application++# archetype for server-side +applications and [literal]#++vaadin-archetype-widget++# for client-side widget +development projects. + ++ +//TODO Vaadin 7: Not all these archetypes are supported ++ +//// +<itemizedlist> <listitem> <literal>vaadin-archetype-clean</literal> is a new project with a barebone skeleton for a regular Vaadin application. The <filename>pom.xml</filename> includes out-commented definitions for additional widgets. </listitem> </itemizedlist> <itemizedlist> <listitem> <literal>vaadin-archetype-widget</literal> is a skeleton for a project with custom widgets. </listitem> </itemizedlist> <itemizedlist> <listitem> <literal>vaadin-archetype-sample</literal> is also for a project with custom widgets, but the skeleton includes the Color Picker example used in <xref linkend="gwt"/>. </listitem> </itemizedlist> <itemizedlist> <listitem> <literal>vaadin-archetype-addon</literal> is for Vaadin add-on projects. It packages the add-on so that it can be published in Vaadin Directory. The archetype is for server-side add-ons and does not include definitions needed for building a widget set. If your add-on includes or requires other than the widgets in the Vaadin core library, you need to copy the required definitions from a POM of a <literal>vaadin-archetype-clean</literal> project. </listitem> </itemizedlist> <itemizedlist> <listitem> <literal>vaadin-archetype-touchkit</literal> is for projects using Vaadin TouchKit, described in <xref linkend="mobile"/>. Notice that this archetype uses the AGPL-licensed version of TouchKit, which requires that your project must also be licensed under the AGPL license. </listitem> </itemizedlist> +//// +[parameter]#archetypeVersion#:: Version of the archetype to use. This should be [literal]#++LATEST++# for normal +Vaadin releases. For prerelease versions it should be the exact version number, +such as [literal]#++7.5.3++#. + +[parameter]#groupId#:: A Maven group ID for your project. It is normally your organization domain name +in reverse order, such as com.example. The group ID is also used as a prefix for +the Java package in the sources, so it should be Java compatible - only +alphanumerics and an underscore. + +[parameter]#artifactId#:: Identifier of the artifact, that is, your project. The identifier may contain +alphanumerics, minus, and underscore. It is appended to the group ID to obtain +the Java package name for the sources. For example, if the group ID is +com.example and artifact ID is myproject, the project sources would be placed in +com.example.myproject package. + +[parameter]#version#:: Initial version number of your application. The number must obey the Maven +version numbering format. + +[parameter]#packaging#:: How will the project be packaged. It is normally [literal]#++war++#. + + + +Creating a project can take a while as Maven fetches all the dependencies. The +created project structure is shown in +<>. + +[[figure.getting-started.maven.archetype.created]] +.A New Vaadin Project with Maven +image::img/maven-project-created.png[] + + +[[getting-started.maven.compiling]] +== Compiling and Running the Application + +((("Maven", "compiling", id="term.maven.compiling", range="startofrange"))) + + +Before the application can be deployed, it must be compiled and packaged as a +WAR package. You can do this with the [literal]#++package++# goal as follows: + +[subs="normal"] +---- +[prompt]#$# [command]#mvn# package +---- +The location of the resulting WAR package should be displayed in the command +output. You can then deploy it to your favorite application server. + +The easiest way to run Vaadin applications with Maven is to use the light-weight +Jetty web server. After compiling the package, all you need to do is type: + +[subs="normal"] +---- +[prompt]#$# [command]#mvn# jetty:run +---- +The special goal starts the Jetty server in port 8080 and deploys the +application. You can then open it in a web browser at +http://localhost:8080/project-name. + +(((range="endofrange", startref="term.maven.compiling"))) + +[[getting-started.maven.addons]] +== Using Add-ons and Custom Widget Sets + +((("Maven", "using add-ons", id="term.maven.addons", range="startofrange"))) + + +If you use Vaadin add-ons that include a widget set or make your custom widgets, +you need to enable widget set compilation in the POM. The required configuration +is described in +<>. + + +(((range="endofrange", startref="term.maven.addons"))) +(((range="endofrange", startref="term.maven.creating"))) + + -- cgit v1.2.3