doc updates for getting started etc
diff --git a/IDE_USE.md b/IDE_USE.md
new file mode 100644
index 0000000..bd5bfae
--- /dev/null
+++ b/IDE_USE.md
@@ -0,0 +1,96 @@
+<!--
+ Licensed to the Apache Software Foundation (ASF) under one or more
+ contributor license agreements. See the NOTICE file distributed with
+ this work for additional information regarding copyright ownership.
+ The ASF licenses this file to You under the Apache License, Version 2.0
+ (the "License"); you may not use this file except in compliance with
+ the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+-->
+
+A maven-integrated IDE such as Eclipse or IntelliJ can easily be used
+to build the samples and the application template project.
+
+If your IDE lacks a maven integration see `samples/get-edgent-jars-project`
+for a tool to create a bundle containing the Edgent runtime jars. You can
+unpack the bundle and adjust the projects in your IDE to use them.
+
+
+# Using Eclipse
+
+The Edgent Git repository and samples source release bundle contains
+Maven project definitions for the samples.
+
+Once you import the Maven projects into your workspace, builds
+in Eclipse use the same artifacts as the Maven command line tooling.
+Like the command line tooling, the jars for dependent projects
+are automatically downloaded to the local maven repository
+and used.
+
+Note: Specifics may change depending on your version of Eclipse or the
+Eclipse Maven or Git Team Provider.
+
+# Download the samples
+
+1. Clone or download the samples as described in [README.md](README.md).
+
+# Import the samples
+
+1. From the Eclipse *File* menu, select *Import...*
+2. From the *Maven* folder, select *Existing Maven Projects* and click *Next*
+ + browse to the `samples` directory in the clone or source release directory
+ and select it. A hierarchy of samples projects / pom.xml files will be
+ listed and all selected.
+ + Verify the *Add project(s) to working set* checkbox is checked
+ + Click *Finish*. Eclipse starts the import process and builds the workspace.
+
+Top-level artifacts such as `README.md` are available under the
+`edgent-samples` project.
+
+# Run a sample
+
+Once the samples projects have been imported you can run them from
+Eclipse in the usual manner. E.g.,
+
+1. From the Eclipse *Navigate* menu, select *Open Type*
+ + enter type type name `HelloEdgent` and click *OK*
+2. right click on the `HelloEdgent` class name and from the context menu
+ + click on *Run As*, then *Java application*.
+ `HelloEdgent` runs and prints to the Console view.
+
+# Cloning the application template
+
+See [template/README.md](template/README.md) for general information.
+
+To clone the template project for your application project:
+
+1. Recursively copy the template folder into a new folder from the command line, e.g.,
+ from the unpacked samples folder
+ + cp -R template ~/myApp
+2. Import the new project into your Eclipse workspace
+ 1. from the Eclipse *File* menu, select *Import...*
+ 2. from the *Maven* folder, select *Existing Maven Projects* and click *Next*
+ + browse to the new folder and select it. The project's pom.xml file will be
+ listed and selected.
+ + click *Finish*. Eclipse starts the import process and builds the workspace.
+ Note, the new imported project's name will be `my-app`.
+ This can be renamed later.
+
+Verify you can run the imported template app:
+
+1. From the Eclipse *Navigate* menu, select *Open Type*
+ + enter type type name `TemplateApp` and click *OK*
+2. right click on the `TemplateApp` class name and from the context menu
+ + click on *Run As*, then *Java application*.
+ `TemplateApp` runs and prints to the Console view.
+
+You can then start adding your application's java code
+and adjusting the template's pom for your application's
+dependencies.
diff --git a/README.md b/README.md
index b1c115a..e1f671b 100644
--- a/README.md
+++ b/README.md
@@ -15,24 +15,44 @@
limitations under the License.
-->
+Getting started with the Edgent samples is a great way to start using
+Edgent and jump-start your Edgent application development.
+
+See [IDE Quickstart](IDE_USE.md) if you want use an IDE instead
+of the command line.
+
# Quickstart
-If you haven't already done so, download the samples from github:
+Convenience binaries (jars) for the Edgent runtime releases are distributed
+to the ASF Nexus Repository and the Maven Central Repository. You don't have
+to manually download the Edgent jars and there is no need to download the
+Edgent runtime sources and build them unless you want to.
+
+By default the samples depend on Java8. Download and install Java8 if needed.
+
+## Download the Edgent Samples
+
+Get the Edgent Samples either by cloning or downloading the [Edgent Samples GitHub repository](https://github.com/apache/incubator-edgent-samples):
```sh
git clone https://github.com/apache/incubator-edgent-samples
cd incubator-edgent-samples
git checkout develop
```
-
-You must have Java 8 installed on your system. Maven will be automatically
-downloaded and installed by the maven wrapper `mvnw`.
-
-Build the samples for Java 8
+or to download:
+ + Open the _Clone or download_ pulldown at the [Edgent Samples GitHub repository](https://github.com/apache/incubator-edgent-samples)
+ + Click on _Download ZIP_
+ + Unpack the downloaded ZIP
```sh
-./mvnw clean package
+ unzip incubator-edgent-samples-develop.zip
```
-Run the HelloEdgent sample
+## Build the Samples
+```sh
+cd <the cloned or unpacked samples folder>
+./mvnw clean package # build for Java8
+```
+
+## Run the HelloEdgent sample
```sh
cd topology
./run-sample.sh HelloEdgent # prints a hello message and terminates
@@ -43,16 +63,16 @@
# Overview
-The Edgent samples provide a starting point for jump starting your
-use of Edgent. See the _Samples Summary_ section for a list of the samples.
-
The Edgent samples are organized into a few categories (subdirectories)
and are a collection of maven projects. They can be built using maven
-or other maven-integrated tooling such as Eclipse.
+or other maven-integrated tooling such as Eclipse - see
+[IDE Quickstart](IDE_USE.md).
+
+See the _Samples Summary_ section for a list of the samples.
An Edgent application template maven project is supplied.
It may be a useful starting point to clone for your application.
-The template has a standalone maven project pom, rather than a
+The template has a standalone maven project pom rather than the
stylized one used by the rest of the samples.
See [template/README.md](template/README.md).
@@ -65,9 +85,9 @@
# Setup
-Once you have downloaded or cloned the the samples repository
-from https://github.com/apache/incubator-edgent-samples
-you need to download these additional development software tools.
+Once you have downloaded and unpacked the samples source bundle
+or cloned the the samples repository you need to download
+these additional development software tools.
* Java 8 - The development setup assumes Java 8
@@ -75,19 +95,13 @@
script (`mvwn` or `mvnw.bat`) is included.
The maven-wrapper automatically downloads and installs the
-correct Maven version and use it. Besides this, there is no
+correct Maven version and uses it. Besides this, there is no
difference between using the `mvnw` command and the `mvn` command.
-You may also use a maven-integrated IDE with the samples.
-e.g., see the _Using Eclipse_ section below.
-
The samples use Edgent SDK jars that have been released
in a maven repository such as Maven Central.
-Alternatively, you can download the Edgent SDK sources and build them,
-populating your local maven repository. The samples
-will then use those Edgent SDK jars. See the note below about
-building against a different Edgent runtime version.
+Alternatively, you can download the Edgent SDK sources and build them.
See [downloads](https://edgent.apache.org/docs/downloads)
for downloading the Edgent SDK sources.
@@ -103,12 +117,13 @@
Build the samples
```sh
-./mvnw clean package # -Pplatform-java7 as needed
+./mvnw clean package # -Pplatform-java7
```
A standard jar and uber jar are created for each sample category
in the sample category's target directory: `<category>/target`.
+
## Building against a different Edgent runtime version
To change the version of the Edgent runtime artifacts used,
@@ -122,71 +137,15 @@
`./mvnw ... -Dedgent.runtime.version=<the-version>`.
The build will not behave as desired.
+A similar declaration is present in template/pom.xml.
+hen running get-edgent-jars.sh, specify `--version=<the-version>`.
+
# Running the samples
See the `README.md` in each sample category directory for information
on running the samples.
-
-# Using Eclipse
-
-The Edgent Git repository and samples source release bundle contains
-Maven project definitions for the samples.
-
-Once you import the Maven projects into your workspace, builds
-in Eclipse use the same artifacts as the Maven command line tooling.
-Like the command line tooling, the jars for dependent projects
-are automatically downloaded to the local maven repository
-and used.
-
-If you want to use Eclipse to clone your fork, use the
-Eclipse Git Team Provider plugin
-
-1. From the Eclipse *File* menu, select *Import...*
-2. From the *Git* folder, select *Projects from Git* and click *Next*
-3. Select *Clone URI* to clone the remote repository. Click *Next*.
- + In the *Location* section, enter the URI of your fork in the *URI* field
- (e.g., `git@github.com:<username>/incubator-edgent.git`).
- The other fields will be populated automatically.
- Click *Next*. If required, enter your passphrase.
- + In the *Source Git Repository* window, select the branch
- (usually `master`) and click *Next*
- + Specify the directory where your local clone will be stored
- and click *Next*. The repository will be cloned.
- Note: You can build and run tests using Maven in this directory.
-4. In the *Select a wizard to use for importing projects* window, click *Cancel*.
- Then follow the steps below to import the Maven projects.
-
-
-Once you have cloned the Git repository to your machine or are working
-from an unpacked samples source release bundle, import the Maven projects
-into your workspace
-
-1. From the Eclipse *File* menu, select *Import...*
-2. From the *Maven* folder, select *Existing Maven Projects* and click *Next*
- + browse to the `samples` directory in the clone or source release directory
- and select it. A hierarchy of samples projects / pom.xml files will be
- listed and all selected.
- + Verify the *Add project(s) to working set* checkbox is checked
- + Click *Finish*. Eclipse starts the import process and builds the workspace.
-
-Top-level artifacts such as `README.md` are available under the
-`edgent-samples` project.
-
-Note: Specifics may change depending on your version of Eclipse or the
-Eclipse Maven or Git Team Provider.
-
-Once the samples projects have been imported you can run them from
-Eclipse in the usual manner. E.g.,
-
-1. From the Eclipse *Navigate* menu, select *Open Type*
- + enter type type name `HelloEdgent` and click *OK*
-2. right click on the `HelloEdgent` class name and from the context menu
- + click on *Run As*, then *Java application*.
- `HelloEdgent` runs and prints to the Console view.
-
-
# Samples Summary
<pre>
diff --git a/template/README.md b/template/README.md
index 365dc46..9650cd5 100644
--- a/template/README.md
+++ b/template/README.md
@@ -1,17 +1,40 @@
-An Edgent Application template project.
-
-Clone this template project folder to create your Edgent application project.
+This is an Edgent Application template project.
The project's pom supports
- building for java8, java7 or android execution environments
- building a standard jar and uber jar
+# Quickstart
+
+Clone this template project folder to start creating your
+Edgent application project.
+
+## Cloning the template
+
+In the unpacked samples folder
+
+```sh
+cp -R template ~/myApp
+```
+
+Verify the setup
+
+```sh
+cd ~/myApp
+./mvnw clean package
+./app-run.sh # prints a hello message
+```
+
+## Customize
+
Edit the pom for your application. Adjust it for your application's maven coordinates.
The pom has potential Edgent dependenacies present and commented out.
Include the Edgent Providers, Analytics, Utils, and Connectors used by your application.
-Read `../README.md` for general information about Edgent Application development.
+See `../README.md` for general information about Edgent Application development.
+
+# Overview
The template includes a maven wrapper script to eliminate the need to
manually download and install maven.
@@ -21,6 +44,19 @@
./mvnw clean package # add -Pplatform-java7 or -Pplatform-android as needed
```
+## Building against a different Edgent runtime version
+
+To change the version of the Edgent runtime artifacts used,
+edit the `edgent.runtime.version` property in the template's
+`pom.xml`. e.g.,
+```xml
+ <edgent.runtime.version>1.3.0-SNAPSHOT</edgent.runtime.version>
+```
+
+Note: Do NOT override the value via
+`./mvnw ... -Dedgent.runtime.version=<the-version>`.
+The build will not behave as desired.
+
# Running the application
You can copy `app-run.sh` and the generated `target/*-uber.jar` to the
