Repository: incubator-edgent Updated Branches: refs/heads/release1.0.0 4fb519b56 -> 0177bb455
[EDGENT-289] Update Eclipse setup instructions and misc. grammar fixes Project: http://git-wip-us.apache.org/repos/asf/incubator-edgent/repo Commit: http://git-wip-us.apache.org/repos/asf/incubator-edgent/commit/0177bb45 Tree: http://git-wip-us.apache.org/repos/asf/incubator-edgent/tree/0177bb45 Diff: http://git-wip-us.apache.org/repos/asf/incubator-edgent/diff/0177bb45 Branch: refs/heads/release1.0.0 Commit: 0177bb455239afa8b28fef7db8d49ac93b25ea66 Parents: 4fb519b Author: Queenie Ma <queeniema.apa...@gmail.com> Authored: Tue Nov 15 12:04:44 2016 -0800 Committer: Queenie Ma <queeniema.apa...@gmail.com> Committed: Tue Nov 15 12:10:42 2016 -0800 ---------------------------------------------------------------------- DEVELOPMENT.md | 184 +++++++++++++++++++++++++++------------------------- 1 file changed, 96 insertions(+), 88 deletions(-) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/incubator-edgent/blob/0177bb45/DEVELOPMENT.md ---------------------------------------------------------------------- diff --git a/DEVELOPMENT.md b/DEVELOPMENT.md index 8e8e4f8..7475ef1 100644 --- a/DEVELOPMENT.md +++ b/DEVELOPMENT.md @@ -1,8 +1,8 @@ ## Development of Apache Edgent *Apache Edgent is an effort undergoing incubation at The Apache Software Foundation (ASF), sponsored by the Incubator PMC. Incubation is required of all newly accepted projects until a further review indicates that the infrastructure, communications, and decision making process have stabilized in a manner consistent with other successful ASF projects. While incubation status is not necessarily a reflection of the completeness or stability of the code, it does indicate that the project has yet to be fully endorsed by the ASF.* - -See [README.md](README.md) for high level information about Apache Edgent. + +See [README.md](README.md) for high-level information about Apache Edgent. This document describes development of Apache Edgent itself, not how to develop Edgent applications. * See http://edgent.incubator.apache.org/docs/edgent-getting-started for getting started using Edgent @@ -12,7 +12,7 @@ The Edgent community welcomes contributions, please *Get Involved*! ## Switched from Ant to Gradle -See the updated _Building_ and _Using Eclipse_ sections below. +See the updated [Building](#building) and [Using Eclipse](#using-eclipse) sections below. The Ant tooling is no longer functional. It's recommended that developers of Edgent create a new workspace instead of @@ -22,9 +22,9 @@ reusing current ant-based Edgent workspaces. Apache Edgent is the new name and the conversion is complete. Code changes: - * package names have the prefix "org.apache.edgent" - * jar names have the prefix "edgent" - + * Package names have the prefix "org.apache.edgent" + * JAR names have the prefix "edgent" + Users of Edgent will need to update their references to the above. It's recommended that developers of Edgent create a new workspace instead of reusing their Quarks workspace. @@ -36,10 +36,12 @@ these additional development software tools. * Java 8 - The development setup assumes Java 8 and Linux. -All Edgent runtime development is done using Java 8. Jars for Java 7 and Android +All Edgent runtime development is done using Java 8. JARs for Java 7 and Android platforms are created as described below. +<a name="building"> ### Building a Binary Release Bundle +</a> Building an Edgent binary release bundle: ``` sh @@ -54,45 +56,45 @@ for information on using the binary release bundle. ### Building for Edgent Runtime Development -The primary build process is using [Gradle](https://gradle.org/), +The primary build process is using [Gradle](https://gradle.org/), any pull request is expected to maintain the build success of `clean, assemble, test`. The Gradle wrapper `edgent/{gradlew,gradlew.bat}` should be used. -The wrapper ensures the appropriate version of gradle is used and it -will automatically download it if needed. e.g.: +The wrapper ensures the appropriate version of Gradle is used and it +will automatically download it if needed, e.g.: ``` sh $ ./gradlew --version $ ./gradlew clean build ``` -The gradle tooling: -- creates release images under `<edgent>/build/release-edgent` -- creates build artifacts under `<edgent>/build/distributions` and `<edgent>/<project>/build` +The Gradle tooling: +- Creates release images under `<edgent>/build/release-edgent` +- Creates build artifacts under `<edgent>/build/distributions` and `<edgent>/<project>/build` The top-level Gradle file is `edgent/build.gradle` and it contains several unique tasks: * `assemble` (default) : Build all code and Javadoc into `build\distributions`. The build will fail on any code error or Javadoc warning or error. -* `all` : synonym for `assemble` -* `build` : essentially like "assemble test reports" +* `all` : Synonym for `assemble` +* `build` : Essentially like "assemble test reports" * `clean` : Clean the project * `test` : Run the JUnit tests, if any test fails the test run stops. Use `--continue` to not stop on the first failure. - * use a project test task and optionally the `--tests` option to run a subset of the tests. Multiple `--tests` options may be specified following each test task. + * Use a project test task and optionally the `--tests` option to run a subset of the tests. Multiple `--tests` options may be specified following each test task. * `$ ./gradlew <project>:test` * `$ ./gradlew <project>:test --tests '*.SomeTest'` * `$ ./gradlew <project>:test --tests '*.SomeTest.someMethod'` - * use the `cleanTest` task to force rerunning a previously successful test task (without forcing a rerun of all of the task's dependencies): + * Use the `cleanTest` task to force rerunning a previously successful test task (without forcing a rerun of all of the task's dependencies): * `$ ./gradlew [<project>:]cleanTest [<project>:]test` -* `reports` : Generate JUnit and Code Coverage reports in `build\distributions\reports`. Use after executing the `test` target. +* `reports` : Generate JUnit and Code Coverage reports in `build\distributions\reports`. Use after executing the `test` target. * `reports\tests\overview-summary.html` - JUnit test report * `reports\coverage\index.html` - Code coverage report -* `release` : Build release bundles in `build/release-edgent`, that includes subsets of the Edgent jars that run on Java 7 (`build/distributions/java7`) and Android (`build/distributions/android`). By default SNAPSHOT bundles are created. Specify `-Dedgent.snapshotId=""` to create bundles for a formal release. -* `signAll` : Sign the release bundles in `build/release-edgent` (first run `release`). You will be promoted for your PGP code signing key's Id, the location of the keyring file, and the secret key password. Default response values may be set with environment variables: - * `GPG_ID` - the code signing key's id (e.g., D0F56CAD) +* `release` : Build release bundles in `build/release-edgent`, that includes subsets of the Edgent JARs that run on Java 7 (`build/distributions/java7`) and Android (`build/distributions/android`). By default, SNAPSHOT bundles are created. Specify `-Dedgent.snapshotId=""` to create bundles for a formal release. +* `signAll` : Sign the release bundles in `build/release-edgent` (first run `release`). You will be promoted for your PGP code signing key's ID, the location of the keyring file, and the secret key password. Default response values may be set with environment variables: + * `GPG_ID` - the code signing key's ID (e.g., D0F56CAD) * `GPG_SECRING` - path to the secret key's keyring file -The build process has been tested on Linux and MacOSX. +The build process has been tested on Linux and macOS. To build on Windows probably needs some changes, please get involved and contribute them! @@ -107,11 +109,11 @@ The build setup is contained in `.travis.yml` in the project root directory. It includes: * Building the project * Testing on Java 8 and Java 7 -Not all tests may be run, some tests are skipped due to timing issues or if excessive setup is required. + - Not all tests may be run, some tests are skipped due to timing issues or if excessive setup is required. -If your test may randomly fail because for example it depends on publicly available test services, +If your test randomly fails because, for example, it depends on publicly available test services, or is timing dependent, and if timing variances on the Travis CI servers may make it more likely -for your tests to fail, you may disable the test from being executed on Travis CI using the +for your tests to fail, you may disable the test from being executed on Travis CI using the following statement: ``` Java @Test @@ -126,25 +128,25 @@ Closing and reopening a pull request will kick off a new build against the pull ### Java 7 and Android Java 7 and Android target platforms are supported through use of -retrolambda to convert Edgent Java8 jars to Java7 jars. +retrolambda to convert Edgent Java8 JARs to Java7 JARs. -Building a release (`./gradlew release`) produces three sets of jars under +Building a release (`./gradlew release`) produces three sets of JARs under * build/distributions/java8 - Java 8 SE * build/distributions/java7 - Java 7 SE * build/distributions/android - Android -See [JAVA_SUPPORT.md](JAVA_SUPPORT.md) for which Edgent capabilities / jars are supported +See [JAVA_SUPPORT.md](JAVA_SUPPORT.md) for which Edgent capabilities / JARs are supported for each environment. -#### Adding Edgent Runtime Jars to Java 7 & Android +#### Adding Edgent Runtime JARs to Java 7 & Android -The gradle tooling uses some ant tooling to create the Java 7 and Android platform jars. +The Gradle tooling uses some Ant tooling to create the Java 7 and Android platform JARs. -Java 7 Edgent runtime jars are created using `platform/java7/build.xml`. Adding a jar just requires: -* Adding it to target `retro7.edgent` - Copy entry for an existing jar. -* Adding any tests for it to targets `test7.setup` and `test7.run` - Copy entry for an existing jar. +Java 7 Edgent runtime JARs are created using `platform/java7/build.xml`. Adding a JAR just requires: +* Adding it to target `retro7.edgent` - Copy entry for an existing JAR. +* Adding any tests for it to targets `test7.setup` and `test7.run` - Copy entry for an existing JAR. -Any Java 7 jar is automatically included in Android unless it is explictly excluded in `platform/android/build.xml`. +Any Java 7 JAR is automatically included in Android unless it is explictly excluded in `platform/android/build.xml`. ### Test reports @@ -157,22 +159,22 @@ Running the `reports` target produces two reports: All of the standard build system _tasks_ above must be run with `JAVA_HOME` set to use a Java8 VM. -As noted above, the `release` task includes generation of Java7 -compatible versions of the Edgent jars. After the release task has been run, +As noted above, the `release` task includes generation of Java7 +compatible versions of the Edgent JARs. After the release task has been run, Edgent may be tested in a Java7 context using some special _test7_ tasks. -See [JAVA_SUPPORT](JAVA_SUPPORT.md) for information about what +See [JAVA_SUPPORT](JAVA_SUPPORT.md) for information about what Edgent features are supported in the different environments. ``` sh # run with JAVA_HOME set for Java8 -$ ./gradlew test7Compile # compile the Edgent tests to operate in a java7 environment +$ ./gradlew test7Compile # compile the Edgent tests to operate in a Java7 environment # run with JAVA_HOME set for Java7 -$ ./gradlew test7Run # run the tests with a java7 VM +$ ./gradlew test7Run # run the tests with a Java7 VM # run with JAVA_HOME set for Java8 -$ ./gradlew test7Reports # generate the junit and coverage tests +$ ./gradlew test7Reports # generate the JUnit and coverage tests ``` ### Publish to Maven Repository @@ -184,11 +186,11 @@ Use the following to do the publish. $ ./gradlew publishToMavenLocal ``` -The component jars / wars are published as well as their sources. +The component JARs / WARs are published as well as their sources. The published groupId is `org.apache.edgent`. The artifactIds match the -names of the jars in the target-dir / release tgz. +names of the JARs in the target-dir / release tgz. -E.g. `org.apache.edgent:edgent.api.topology:0.4.0` +For example: `org.apache.edgent:edgent.api.topology:0.4.0` ### Code Layout @@ -225,9 +227,9 @@ such as an MQTT broker, Apache Kafka, a cloud based IoT service, etc. Placeholder: see [EDGENT-23](https://issues.apache.org/jira/browse/EDGENT-23) A couple of key items in the mean time: -* use spaces not hard tabs, indent is 4 spaces -* don't use wildcard imports -* don't deliver code with warnings (e.g., unused imports) +* Use spaces not hard tabs, indent is 4 spaces +* Don't use wildcard imports +* Don't deliver code with warnings (e.g., unused imports) ### Logging @@ -237,23 +239,23 @@ Search the code for org.slf4j.LoggerFactory to see a sample of its use. ### Use of Java 8 features Edgent's primary development environment is Java 8, to take advantage of lambda expressions -since Edgent's primary api is a functional one. +since Edgent's primary API is a functional one. -**However** in order to support Android (and Java 7) other features of Java 8 are not used in the core +**However**, in order to support Android (and Java 7), other features of Java 8 are not used in the core code. Lambdas are translated into Java 7 compatible classes using retrolambda. Thus: * For core code that needs to run on Android: - * the only Java 8 feature that can be used is lambda expressions. + * The only Java 8 feature that can be used is lambda expressions * JMX functionality cannot be used. -* For test code that tests core code that runs on Android +* For test code that tests core code that runs on Android: * Java 8 lambda expressions can be used * Java 8 default & static interface methods - * Java 8 new classes and methods cannot be used. - -In general most code is expected to work on Android (but might not yet) with the exception: + * Java 8 new classes and methods cannot be used + +In general, most code is expected to work on Android (but might not yet) with the exception: * Functionality aimed at the developer environment, such as console and development provider -* Any JMX related code. +* Any JMX related code ### The ASF / GitHub Integration @@ -266,23 +268,23 @@ The repositories are mirrored on GitHub: https://github.com/apache/incubator-edgent Use of the normal GitHub workflow brings benefits to the team including -lightweight code reviewing, automatic regression tests, etc -for both committers and non-committers. +lightweight code reviewing, automatic regression tests, etc. +for both committers and non-committers. -For a description of the GitHub workflow see: +For a description of the GitHub workflow, see: https://guides.github.com/introduction/flow/ https://guides.github.com/activities/hello-world/ In summary: -* fork the incubator-edgent GitHub repository -* clone your fork, use lightweight per-task branches, and commit / push changes to your fork - * descriptive branch names are good. You can also include a reference - to the Jira issue. e.g., mqtt-ssl-edgent-100 for issue EDGENT-100 -* when ready, create a pull request. Committers will get notified. - * include EDGENT-XXXX (the Jira issue) in the name of your pull request - * for early preview / feedback, create a pull request with [WIP] in the title. - Committers wonât consider it for merging until after [WIP] is removed. +* Fork the incubator-edgent GitHub repository +* Clone your fork, use lightweight per-task branches, and commit / push changes to your fork + * Descriptive branch names are good. You can also include a reference + to the JIRA issue, e.g., *mqtt-ssl-edgent-100* for issue EDGENT-100 +* When ready, create a pull request. Committers will get notified. + * Include *EDGENT-XXXX* (the JIRA issue) in the name of your pull request + * For early preview / feedback, create a pull request with *[WIP]* in the title. + Committers wonât consider it for merging until after *[WIP]* is removed. Since the GitHub incubator-edgent repository is a mirror of the ASF repository, the usual GitHub based merge workflow for committers isnât supported. @@ -293,43 +295,49 @@ into the repo at the ASF. One way is described here: * http://mail-archives.apache.org/mod_mbox/incubator-quarks-dev/201603.mbox/%3C1633289677.553519.1457733763078.JavaMail.yahoo%40mail.yahoo.com%3E Notes with the above PR merge directions: - * use an https url unless you have a ssh key setup at GitHub: - `$ git remote add mirror https://github.com/apache/incubator-edgent.git` + * Use an HTTPS URL unless you have a SSH key setup at GitHub: + - `$ git remote add mirror https://github.com/apache/incubator-edgent.git` +<a name="using-eclipse"> ### Using Eclipse +</a> -The Edgent git repository contains Eclipse project definitions for the +The Edgent Git repository contains Eclipse project definitions for the top-level directories that contain code, such as api, runtime, connectors. -**The git repository does not include the 3rd party jars that Edgent depends on -and Eclipse builds of Edgent projects will fail until a gradle task is run +**The Git repository does not include the 3rd party JARs that Edgent depends on, +and Eclipse builds of Edgent projects will fail until a Gradle task is run to make them available in your workspace. See the steps below.** -Using the plugin Eclipse Git Team Provider allows you to import these projects +Using the Eclipse Git Team Provider plugin allows you to import these projects into your Eclipse workspace directly from your fork. -1. From the File menu select Import -1. From the Git folder select Projects from Git and click Next -1. Select Clone URI and click Next -1. Under Location enter the URI of your fork (the other fields will be filled in automatically) and click Next -1. If required, enter your passphrase to unlock you ssh key -1. Select the branch, usually master and click Next -1. Set the directory where your local clone will be stored and click Next (the directory `edgent` under this directory is where you can build and run tests using the Gradle targets) -1. Select Import existing Eclipse projects and click Next -1. In the Import Projects window, make sure that the Search for nested projects checkbox is selected. Click Finish to bring in all Edgent projects. **Expect build failures until you...** -1. Run a gradle task to make all of the dependant 3rd party jars available to Eclipse. When the command finishes, refresh your Eclipse workspace so that it rebuilds the projects. +1. From the *File* menu, select *Import...* +2. From the *Git* folder, select *Projects from Git* and click *Next* +3. In the *Select Repository Source* window, select one of the following: + - *Existing local repository* if you have already cloned the project to your machine. Click *Next*. + + Click *Add* and browse to the local Git repository directory + + Select the checkbox next to the repository and click *Finish* + + In the *Select a Git repository* window, choose *incubator-edgent* and click *Next* + - *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., `g...@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*. Note: You can build and run tests using the Gradle targets in this directory. +4. In the *Select a wizard to use for importing projects* window, choose *Import existing Eclipse projects* and click *Next* +5. In the *Import Projects* window, ensure that the *Search for nested projects* checkbox is selected. Click *Finish* to bring in all the Edgent projects. **Expect build failures until you...** +6. Run the following Gradle task in your clone directory to make all of the dependant 3rd party JARs available to Eclipse. When the command finishes, refresh your Eclipse workspace (*File* > *Refresh*) so that it rebuilds the projects. ``` sh $ ./gradlew setupExternalJars ``` -The project `_edgent` exists to make the top level artifacts such as -`build.gradle` manageable via Eclipse. Unfortunately folders for the -other projects (e.g., `api`) also show up in the `_edgent` folder and +The `_edgent` project exists to make the top-level artifacts such as +`build.gradle` manageable via Eclipse. Unfortunately, folders for the +other projects (e.g., `api`) also show up in the `_edgent` folder, and are best ignored. -Builds and junit testing of Edgent in Eclipse are independent from the artifacts -generated by the gradle build tooling. Neither environment is affected by -the other. This is not ideal but it's where things are at at this time. +Builds and JUnit testing of Edgent in Eclipse are independent from the artifacts +generated by the Gradle build tooling. Neither environment is affected by +the other. This is not ideal, but it's where things are at at this time. Both sets of tooling can be, and typically are, used in the same workspace. -Note. Specifics may change depending on your version of Eclipse or the Eclipse Git Team Provider. +Note: Specifics may change depending on your version of Eclipse or the Eclipse Git Team Provider.
