cleanup/fix some sample README and scripts
Project: http://git-wip-us.apache.org/repos/asf/incubator-edgent-samples/repo Commit: http://git-wip-us.apache.org/repos/asf/incubator-edgent-samples/commit/d6db0081 Tree: http://git-wip-us.apache.org/repos/asf/incubator-edgent-samples/tree/d6db0081 Diff: http://git-wip-us.apache.org/repos/asf/incubator-edgent-samples/diff/d6db0081 Branch: refs/heads/develop Commit: d6db0081056734c816a654e675163d1a35ea9223 Parents: 7db0380 Author: Dale LaBossiere <dlab...@us.ibm.com> Authored: Wed Sep 6 15:14:47 2017 -0400 Committer: Dale LaBossiere <dlab...@us.ibm.com> Committed: Wed Sep 6 15:14:47 2017 -0400 ---------------------------------------------------------------------- APPLICATION_DEVELOPMENT.md | 216 ++++++++++++++++++++++++++++++++++++++++ README.md | 201 +------------------------------------ console/run-sample.sh | 2 +- scenarios/README.md | 52 ++++++---- scenarios/run-sample.sh | 3 +- topology/run-sample.sh | 2 +- utils/README.md | 2 +- utils/run-sample.sh | 2 +- 8 files changed, 258 insertions(+), 222 deletions(-) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/incubator-edgent-samples/blob/d6db0081/APPLICATION_DEVELOPMENT.md ---------------------------------------------------------------------- diff --git a/APPLICATION_DEVELOPMENT.md b/APPLICATION_DEVELOPMENT.md new file mode 100644 index 0000000..9199c94 --- /dev/null +++ b/APPLICATION_DEVELOPMENT.md @@ -0,0 +1,216 @@ +<!-- + 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. +--> + +#Edgent Application Development, Packaging and Execution. + +This file is a work-in-progress. + +To develop Edgent applications you will utilize the +Edgent SDK/runtime jars, package your application +artifacts for deploying to an edge device for execution. + +The Edgent SDK/runtime jars are published to maven-central. +Alternatively, you can build the Edgent SDK yourself from a source release +and the resulting jars will be added to your local maven repository. + +There are a set of Edgent jars for each supported platform: java8, java7, and android. +The artifact groupId prefix is: org.apache.edgent (for java8), +org.apache.edgent.java7 and org.apache.edgent.android. e.g. + org.apache.edgent.api org.apache.edgent.api.java7 + +See `JAVA_SUPPORT.md` for more information on coordinates, etc. + +The Edgent API is most easily used by using java8 lambda expressions. +If you only want to deploy your Edgent application to a java8 environment +then your application may use any java8 features it chooses. You compile +and run against the Edgent java8 jars. + +If you want to deploy your Edgent application to a java7 or android +environment, it's still easiest to write your application using the Edgent APIs +with java8 lambda expressions. You compile with java8 but constrain +your application to using java7 features plus java8 lambda expressions. +The Retrolambda tool is used to convert your application's generated +class files to java7. +(the java7 and android Edgent jars were created in that manner too) +Your application would then be run against the appropriate +Edgent platform jars. Alternatively you can forgo the use of lambda +expressions and write your application in java7 and compile +and run against the appropriate Edgent platform jars. + +For convenience it's easiest to build your Edgent applcation using +maven-repository-enabled build tooling (e.g., maven, maven-enabled +Eclipse or IntelliJ). The tooling transparently downloads the +required Edgent jars from the maven repository. + +The supplied Edgent samples poms include support for building for +a java8, java7 or android execution environent. The poms are +configured for the generation of a standard jar as well as an +uber jar for a sample application. + +You can clone the samples/template project as a starting point +for your Edgent application. See `samples/template/README.md`. + +TODO: we would like to provide a maven Edgent Application archetype +that users can use to create an application project template. + +If you can't or don't want to use maven-repository-enabled tooling +you will need to get a local copy of the Edgent jars and their +dependencies and add them to your compile classpath. +The Edgent supplied get-edgent-jars.sh tool can be used to +get copies of the jars from a maven repository. + + +##Packaging and Execution + +Edgent doesn't provide any "deployment" mechanisms other than its primitive +"register jar" feature (see the IotProvider javadoc). Generally, managing +the deployment of application and Edgent jars to edge devices is left to +others (as an example, the IBM Watson IoT Platform has device APIs to +support "firmware" download/update). + +To run your Edgent application on an edge device, your application +jar(s) need to be on the device. Additionally, the application's +dependent Edgent jars (and their transitive dependencies) need to +be on the device. It's unlikely the device will be able to retrieve +the dependencies directly from a remote maven repository such as +maven central. + +Here are three options for dealing with this: + +a) construct an uber-jar for your application. + The uber jar contains the application's classes and + the application's dependent Edgent classes and their + transitive dependencies. + + The uber jar is a standalone entity containing + everything that's needed to run your application. + + The Edgent samples poms contain configuration information + that generates an uber jar in addition to the standard + application jar. Eclipse can also export an uber jar. + +b) create an application package bundle. + The bundle contains the application's jar + and the application's dependent Edgent jars and their + transitive dependencies. + The bundle is copied to the device and unpacked. + A run script forms the appropriate CLASSPATH + to the package's jars and starts the application. + + The Edgent supplied package-app.sh tool supports this mode. + Eclipse can also export a similar collection + of information. + +c) separately manage the application's jars and the + Edgent jars and their dependencies. + Copy the application's jars to the device. + Get a copy of the Edgent jars and their dependencies + onto the device to be shared by any Edgent applications + that want to use them. + + The Apache Edgent project does not release a + binary bundle containing all of the Edgent jars + and their dependencies. The binary artifacts + are only released to maven central. + + The Edgent supplied get-edgent-jars.sh tool supports this mode. + +##get-edgent-jars.sh + +The `get-edgent-jars.sh` script copies the Edgent runtime jars and their +dependencies from a local or remote maven repository. + +The user may then directly use the jars in CLASSPATH specifications +for Edgent application compilation or execution. +A `classpath.sh` script is generated to assist with this. + +By default the script retrieves the Edgent java8 platform jars for the +script's default Edgent version. + +The script creates and builds a small maven project as +part of its execution. + +```sh +get-edgent-jars.sh --version 1.2.0-SNAPSHOT # retrieve the Edgent 1.2.0-SNAPSHOT java8 jars +This command downloads the Apache Edgent jars and their transitive external dependencies. +The external dependencies have their own licensing term that you should review. +A summary of the external dependencies can be found here <TODO URL>. +Continue? [y/n] y +##### Generating maven project get-edgent-jars-project... +##### Generating dependency decls... +##### Adding dependency decls to pom... +##### Retrieving jars into local maven repo... +... +##### Copying jars... +##### Generating classpath.sh... +##### The Edgent jars are in get-edgent-jars-project/edgent-jars +##### The external jars are in get-edgent-jars-project/ext-jars +##### CLASSPATH may be set by copying get-edgent-jars-project/java8/classpath.sh and using it like: +##### export CLASSPATH=`classpath.sh path-to-parent-of-edgent-jars-dir` +``` + +For more usage information: + +```sh +get-edgent-jars.sh -h +``` + +##package-app.sh + +The `package-app.sh` script creates an application bundle. +The application bundle can be copied to an edge-device, +unpacked and then used to run the application. + +The application bundle contains the application's jar, +the application's dependent Edgent jars (as specified in +the application's pom) and the Edgent jars' dependencies, +and a run-app.sh script. + +The application's pom specified Edgent runtime jars and +their dependencies are retrieved from a local or remote +maven repository. + +If the application was built using java8, complied against +the java8 Edgent jars, and the execution environment is +java7 or android, use the appropriate script options +to retrieve the appropriate Edgent platform jars for +execution. + +The run-app.sh script configures the CLASSPATH and runs +the application. + +E.g., + +```sh +cd MyApp # the project directory +package-app.sh --mainClass com.mycompany.app.MyApp --appjar target/my-app-1.0-SNAPSHOT.jar +##### get the app specific dependencies... +... +##### create target/app-run.sh... +##### create target/app-pkg.tar... +##### Copy target/app-pkg.tar to the destination system" +##### To run the app:" +##### mkdir app-pkg" +##### tar xf app-pkg.tar -C app-pkg" +##### (cd app-pkg; ./app-run.sh)" +``` + +For more usage information: + +```sh +package-app.sh -h +``` http://git-wip-us.apache.org/repos/asf/incubator-edgent-samples/blob/d6db0081/README.md ---------------------------------------------------------------------- diff --git a/README.md b/README.md index b9b0dee..15e4fdb 100644 --- a/README.md +++ b/README.md @@ -14,204 +14,9 @@ See the License for the specific language governing permissions and limitations under the License. --> -#Apache Edgent SDK samples. -This file is a work-in-progress. - -The following describes Edgent Application development in general -and the Edgent SDK samples in particular. - -#Edgent Application Development, Packaging and Execution. - -The Edgent SDK/runtime jars are published to maven-central. - -There are a set of Edgent jars for each supported platform: java8, java7, and android. -The artifact groupId prefix is: org.apache.edgent (for java8), -org.apache.edgent.java7 and org.apache.edgent.android. e.g. - org.apache.edgent.api org.apache.edgent.api.java7 - -See `JAVA_SUPPORT.md` for more information on coordinates, etc. - -The Edgent API is most easily used by using java8 lambda expressions. -If you only want to deploy your Edgent application to a java8 environment -then your application may use any java8 features it chooses. You compile -and run against the Edgent java8 jars. - -If you want to deploy your Edgent application to a java7 or android -environment, it easiest to write your application using the Edgent APIs -with java8 lambda expressions. You compile with java8 but constrain -your application to using java7 features plus java8 lambda expressions. -The Retrolambda tool is used to convert your application's generated -class files to java7. -(the java7 and android Edgent jars were created in that manner too) -Your application would then be run against the appropriate -Edgent platform jars. Alternatively you can forgo the use of lambda -expressions and write your application in java7 and compile -and run against the appropriate Edgent platform jars. - -For convenience it's easiest to build your Edgent applcation using -maven-repository-enabled build tooling (e.g., maven, maven-enabled -Eclipse or IntelliJ). The tooling transparently downloads the -required Edgent jars from the maven repository. - -The supplied Edgent samples poms include support for building for -a java8, java7 or android execution environent. The poms are -configured for the generation of a standard jar as well as an -uber jar for a sample application. - -You can clone the samples/template project as a starting point -for your Edgent application. See samples/template/README.md. - -TODO: we would like to provide a maven Edgent Application archetype -that users can use to create an application project template. - -If you can't or don't want to use maven-repository-enabled tooling -you will need to get a local copy of the Edgent jars and their -dependencies and add them to your compile classpath. -The Edgent supplied get-edgent-jars.sh tool can be used to -get copies of the jars from a maven repository. - - -##Packaging and Execution - -Edgent doesn't provide any "deployment" mechanisms other than its primitive -"register jar" feature (see the IotProvider javadoc). Generally, managing -the deployment of application and Edgent jars to edge devices is left to -others (as an example, the IBM Watson IoT Platform has device APIs to -support "firmware" download/update). - -To run your Edgent application on an edge device, your application -jar(s) need to be on the device. Additionally, the application's -dependent Edgent jars (and their transitive dependencies) need to -be on the device. It's unlikely the device will be able to retrieve -the dependencies directly from a remote maven repository such as -maven central. - -Here are three options for dealing with this: - -a) construct an uber-jar for your application. - The uber jar contains the application's classes and - the application's dependent Edgent classes and their - transitive dependencies. - - The uber jar is a standalone entity containing - everything that's needed to run your application. - - The Edgent samples poms contain configuration information - that generates an uber jar in addition to the standard - application jar. Eclipse can also export an uber jar. - -b) create an application package bundle. - The bundle contains the application's jar - and the application's dependent Edgent jars and their - transitive dependencies. - The bundle is copied to the device and unpacked. - A run script forms the appropriate CLASSPATH - to the package's jars and starts the application. - - The Edgent supplied package-app.sh tool supports this mode. - Eclipse can also export a similar collection - of information. - -c) separately manage the application's jars and the - Edgent jars and their dependencies. - Copy the application's jars to the device. - Get a copy of the Edgent jars and their dependencies - onto the device to be shared by any Edgent applications - that want to use them. - - The Apache Edgent project does not release a - binary bundle containing all of the Edgent jars - and their dependencies. The binary artifacts - are only released to maven central. - - The Edgent supplied get-edgent-jars.sh tool supports this mode. - -##get-edgent-jars.sh - -The `get-edgent-jars.sh` script copies the Edgent runtime jars and their -dependencies from a local or remote maven repository. - -The user may then directly use the jars in CLASSPATH specifications -for Edgent application compilation or execution. -A `classpath.sh` script is generated to assist with this. - -By default the script retrieves the Edgent java8 platform jars for the -script's default Edgent version. - -The script creates and builds a small maven project as -part of its execution. - -```sh -get-edgent-jars.sh --version 1.2.0-SNAPSHOT # retrieve the Edgent 1.2.0-SNAPSHOT java8 jars -This command downloads the Apache Edgent jars and their transitive external dependencies. -The external dependencies have their own licensing term that you should review. -A summary of the external dependencies can be found here <TODO URL>. -Continue? [y/n] y -##### Generating maven project get-edgent-jars-project... -##### Generating dependency decls... -##### Adding dependency decls to pom... -##### Retrieving jars into local maven repo... -... -##### Copying jars... -##### Generating classpath.sh... -##### The Edgent jars are in get-edgent-jars-project/edgent-jars -##### The external jars are in get-edgent-jars-project/ext-jars -##### CLASSPATH may be set by copying get-edgent-jars-project/java8/classpath.sh and using it like: -##### export CLASSPATH=`classpath.sh path-to-parent-of-edgent-jars-dir` -``` - -For more usage information: - -```sh -get-edgent-jars.sh -h -``` - -##package-app.sh - -The `package-app.sh` script creates an application bundle. -The application bundle can be copied to an edge-device, -unpacked and then used to run the application. - -The application bundle contains the application's jar, -the application's dependent Edgent jars (as specified in -the application's pom) and the Edgent jars' dependencies, -and a run-app.sh script. - -The application's pom specified Edgent runtime jars and -their dependencies are retrieved from a local or remote -maven repository. - -If the application was built using java8, complied against -the java8 Edgent jars, and the execution environment is -java7 or android, use the appropriate script options -to retrieve the appropriate Edgent platform jars for -execution. - -The run-app.sh script configures the CLASSPATH and runs -the application. - -E.g., - -```sh -cd MyApp # the project directory -package-app.sh --mainClass com.mycompany.app.MyApp --appjar target/my-app-1.0-SNAPSHOT.jar -##### get the app specific dependencies... -... -##### create target/app-run.sh... -##### create target/app-pkg.tar... -##### Copy target/app-pkg.tar to the destination system" -##### To run the app:" -##### mkdir app-pkg" -##### tar xf app-pkg.tar -C app-pkg" -##### (cd app-pkg; ./app-run.sh)" -``` - -For more usage information: - -```sh -package-app.sh -h -``` +See [APPLICATION_DEVELOPMENT.md](APPLICATION_DEVELOPMENT.md) for general +information on Edgent Application Development, Packaging and Execution. #Building the Edgent samples @@ -229,4 +34,4 @@ in the sample category's target directory: `<category>/target`. ##Running the samples -See the README in each sample category directory. +See the README.md in each sample category directory. http://git-wip-us.apache.org/repos/asf/incubator-edgent-samples/blob/d6db0081/console/run-sample.sh ---------------------------------------------------------------------- diff --git a/console/run-sample.sh b/console/run-sample.sh index 7cbd42a..b11529e 100755 --- a/console/run-sample.sh +++ b/console/run-sample.sh @@ -60,5 +60,5 @@ if [ "${SAMPLE_FQ}" = "" ]; then exit 1 fi -java -cp ${UBER_JAR} "${SAMPLE_FQ}" "$*" +java -cp ${UBER_JAR} "${SAMPLE_FQ}" "$@" http://git-wip-us.apache.org/repos/asf/incubator-edgent-samples/blob/d6db0081/scenarios/README.md ---------------------------------------------------------------------- diff --git a/scenarios/README.md b/scenarios/README.md index 7a2d3ac..da1d9e3 100644 --- a/scenarios/README.md +++ b/scenarios/README.md @@ -20,36 +20,50 @@ See the Recipe this was created for [here](https://developer.ibm.com/recipes/tutorials/apache-quarks-on-pi-to-watson-iot-foundation/). If that link doesn't work, try [here](https://developer.ibm.com/recipes/tutorials/apache-edgent-on-pi-to-watson-iot-foundation/). -## Requirements: -* You must have Pi4J installed on the device (if you are running outside of a Raspberry Pi, you will have to download the JARs and include them in your classpath) -* You must have Edgent downloaded and built -* You will need to have an HC-SR04 Range sensor hooked up with your EchoPin set to pin 18 and your TripPin at pin 16 (see these instructions on hardware setup: http://www.modmypi.com/blog/hc-sr04-ultrasonic-range-sensor-on-the-raspberry-pi). To use a simulated sensor, pass in true as your second argument. -* You will need to have an LED hooked up to pin 12 (See these instructions to set up an LED, however use pin 12 as your control pin: https://projects.drogon.net/raspberry-pi/gpio-examples/tux-crossing/gpio-examples-1-a-single-led/). To use a simulated LED, pass in true as your third argument. -* You will need to have your device registered with Watson IoTF and a device.cfg file, or you can use a quickstart version by passing in "quickstart" as your first argument. - -To compile, export your Edgent install and PI4J libraries (on Raspberry Pi, the default Pi4J location is `/opt/pi4j/lib`): +See the README.md in the samples root directory for information on building the samples. + +The build generated uber jar contains all of the dependent +Edgent jars and their transitive dependencies. -`$ EDGENT=<edgent-root-dir>` +The desired sample can be run using the run-sample.sh script. e.g., -`$ export PI4J_LIB=<Pi4J-libs> # directory where pi4j-core.jar resides` +```sh +cd scenarios +./run-sample.sh IotpRangeSensor quickstart true true # see below +``` -`$ cd $EDGENT` +For usage information: -`$ ./gradlew # builds the range sensor sample only if the PI4J_LIB environment variable is set` +```sh +./run-sample.sh +./run-sample.sh --list +``` -To run: - -`$ CP=$EDGENT/build/distributions/java8/samples/lib/edgent.samples.scenarios.jar` +If you want to run a sample from the standard jar there are two options: +a) get a local copy of all of the Edgent jars and their dependencies. + Form a CLASSPATH to the jars and run the sample's main class. + The get-edgent-jars.sh script can be used to get the jars from + a maven repository (local or remote). +b) create an application package bundle. The bundle includes the + sample(s) jar and a copy of all of the dependent Edgent jars + and their dependencies. The package-app.sh script can be + used to create this bundle. + The package-app.sh script also creates a run-app.sh script. + The run-app.sh script configures the CLASSPATH and runs the main class. -`$ MAIN=org.apache.edgent.samples.scenarios.iotp.range.sensor.IotpRangeSensor` + +## Requirements: +* You will need to have an HC-SR04 Range sensor hooked up with your EchoPin set to pin 18 and your TripPin at pin 16 (see these instructions on hardware setup: http://www.modmypi.com/blog/hc-sr04-ultrasonic-range-sensor-on-the-raspberry-pi). To use a simulated sensor, pass in true as your second argument. +* You will need to have an LED hooked up to pin 12 (See these instructions to set up an LED, however use pin 12 as your control pin: https://projects.drogon.net/raspberry-pi/gpio-examples/tux-crossing/gpio-examples-1-a-single-led/). To use a simulated LED, pass in true as your third argument. +* You will need to have your device registered with Watson IoTF and a device.cfg file, or you can use a quickstart version by passing in "quickstart" as your first argument. -`$ java -cp $CP $MAIN <device cfg file> <simulatedSensor?> <simulatedLED?>` +`./run-sample.sh IotpRangeSensor <device cfg file> <simulatedSensor?> <simulatedLED?>` To run with a device.cfg file, range sensor, and LED: -`$ java -cp $CP $MAIN device.cfg false false` +`./run-sample.sh IotpRangeSensor device.cfg false false` To run in fully simulated mode (no sensors and using IoTF quickstart): -`$ java -cp $CP $MAIN quickstart true true` \ No newline at end of file +`./run-sample.sh IotpRangeSensor quickstart true true` http://git-wip-us.apache.org/repos/asf/incubator-edgent-samples/blob/d6db0081/scenarios/run-sample.sh ---------------------------------------------------------------------- diff --git a/scenarios/run-sample.sh b/scenarios/run-sample.sh index fea6ead..2b2c92b 100755 --- a/scenarios/run-sample.sh +++ b/scenarios/run-sample.sh @@ -60,5 +60,6 @@ if [ "${SAMPLE_FQ}" = "" ]; then exit 1 fi -java -cp ${UBER_JAR} "${SAMPLE_FQ}" "$*" +set -x +java -cp ${UBER_JAR} "${SAMPLE_FQ}" "$@" http://git-wip-us.apache.org/repos/asf/incubator-edgent-samples/blob/d6db0081/topology/run-sample.sh ---------------------------------------------------------------------- diff --git a/topology/run-sample.sh b/topology/run-sample.sh index c9568d5..1614a7d 100755 --- a/topology/run-sample.sh +++ b/topology/run-sample.sh @@ -70,5 +70,5 @@ if [ "${SAMPLE_FQ}" = "" ]; then exit 1 fi -java -cp ${UBER_JAR} "${SAMPLE_FQ}" "$*" +java -cp ${UBER_JAR} "${SAMPLE_FQ}" "$@" http://git-wip-us.apache.org/repos/asf/incubator-edgent-samples/blob/d6db0081/utils/README.md ---------------------------------------------------------------------- diff --git a/utils/README.md b/utils/README.md index 348edae..7381f2e 100644 --- a/utils/README.md +++ b/utils/README.md @@ -6,7 +6,7 @@ Edgent jars and their transitive dependencies. The desired sample can be run using the run-sample.sh script. e.g., ```sh -cd topology +cd utils ./run-sample.sh PeriodicSourceWithMetrics ``` http://git-wip-us.apache.org/repos/asf/incubator-edgent-samples/blob/d6db0081/utils/run-sample.sh ---------------------------------------------------------------------- diff --git a/utils/run-sample.sh b/utils/run-sample.sh index 8e9128a..697f44f 100755 --- a/utils/run-sample.sh +++ b/utils/run-sample.sh @@ -60,5 +60,5 @@ if [ "${SAMPLE_FQ}" = "" ]; then exit 1 fi -java -cp ${UBER_JAR} "${SAMPLE_FQ}" "$*" +java -cp ${UBER_JAR} "${SAMPLE_FQ}" "$@"
