Return-Path: X-Original-To: apmail-brooklyn-commits-archive@minotaur.apache.org Delivered-To: apmail-brooklyn-commits-archive@minotaur.apache.org Received: from mail.apache.org (hermes.apache.org [140.211.11.3]) by minotaur.apache.org (Postfix) with SMTP id 2A038CEFD for ; Fri, 9 Jan 2015 16:10:06 +0000 (UTC) Received: (qmail 83556 invoked by uid 500); 9 Jan 2015 16:10:07 -0000 Delivered-To: apmail-brooklyn-commits-archive@brooklyn.apache.org Received: (qmail 83532 invoked by uid 500); 9 Jan 2015 16:10:07 -0000 Mailing-List: contact commits-help@brooklyn.incubator.apache.org; run by ezmlm Precedence: bulk List-Help: List-Unsubscribe: List-Post: List-Id: Reply-To: dev@brooklyn.incubator.apache.org Delivered-To: mailing list commits@brooklyn.incubator.apache.org Received: (qmail 83523 invoked by uid 99); 9 Jan 2015 16:10:07 -0000 Received: from nike.apache.org (HELO nike.apache.org) (192.87.106.230) by apache.org (qpsmtpd/0.29) with ESMTP; Fri, 09 Jan 2015 16:10:07 +0000 X-ASF-Spam-Status: No, hits=-2000.0 required=5.0 tests=ALL_TRUSTED,T_RP_MATCHES_RCVD X-Spam-Check-By: apache.org Received: from [140.211.11.3] (HELO mail.apache.org) (140.211.11.3) by apache.org (qpsmtpd/0.29) with SMTP; Fri, 09 Jan 2015 16:09:34 +0000 Received: (qmail 80987 invoked by uid 99); 9 Jan 2015 16:09:30 -0000 Received: from tyr.zones.apache.org (HELO tyr.zones.apache.org) (140.211.11.114) by apache.org (qpsmtpd/0.29) with ESMTP; Fri, 09 Jan 2015 16:09:30 +0000 Received: by tyr.zones.apache.org (Postfix, from userid 65534) id A1FB181657F; Fri, 9 Jan 2015 16:09:29 +0000 (UTC) Content-Type: text/plain; charset="us-ascii" MIME-Version: 1.0 Content-Transfer-Encoding: 8bit From: heneveld@apache.org To: commits@brooklyn.incubator.apache.org Date: Fri, 09 Jan 2015 16:09:37 -0000 Message-Id: <509cf3632c3240cc89979a374421d1a4@git.apache.org> In-Reply-To: References: X-Mailer: ASF-Git Admin Mailer Subject: [09/13] incubator-brooklyn git commit: wholesale replacement by docs folder from master X-Virus-Checked: Checked by ClamAV on apache.org http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/a7a317bf/docs/guide/dev/build/developers-catalog.xml ---------------------------------------------------------------------- diff --git a/docs/guide/dev/build/developers-catalog.xml b/docs/guide/dev/build/developers-catalog.xml deleted file mode 100644 index 3afe052..0000000 --- a/docs/guide/dev/build/developers-catalog.xml +++ /dev/null @@ -1,87 +0,0 @@ - - - Brooklyn Developers Catalog - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - file://~/.m2/repository/io/brooklyn/example/brooklyn-example-simple-web-cluster/0.7.0-M2-incubating/brooklyn-example-simple-web-cluster-0.7.0-M2-incubating.jar - file://~/.m2/repository/io/brooklyn/example/brooklyn-example-global-web-fabric/0.7.0-M2-incubating/brooklyn-example-global-web-fabric-0.7.0-M2-incubating.jar - file://~/.m2/repository/io/brooklyn/example/brooklyn-example-global-web-fabric/0.7.0-M2-incubating/brooklyn-example-global-web-fabric-0.7.0-M2-incubating.jar - file://~/.m2/repository/io/brooklyn/example/brooklyn-example-portable-cloudfoundry/0.7.0-M2-incubating/brooklyn-example-portable-cloudfoundry-0.7.0-M2-incubating.jar - file://~/.m2/repository/io/brooklyn/example/brooklyn-example-simple-web-cluster/0.7.0-M2-incubating/brooklyn-example-simple-web-cluster-0.7.0-M2-incubating.jar - file://~/.m2/repository/io/brooklyn/example/brooklyn-example-hello-world-sql-webapp/0.7.0-M2-incubating/brooklyn-example-hello-world-sql-webapp-0.7.0-M2-incubating.jar - file://~/.m2/repository/io/brooklyn/example/brooklyn-example-simple-messaging-pubsub/0.7.0-M2-incubating/brooklyn-example-simple-messaging-pubsub-0.7.0-M2-incubating.jar - file://~/.m2/repository/io/brooklyn/example/brooklyn-examples-parent/0.7.0-M2-incubating/brooklyn-examples-parent-0.7.0-M2-incubating.jar - file://~/.m2/repository/io/brooklyn/example/brooklyn-example-hello-world-webapp/0.7.0-M2-incubating/brooklyn-example-hello-world-webapp-0.7.0-M2-incubating.jar - file://~/.m2/repository/io/brooklyn/example/brooklyn-example-simple-nosql-cluster/0.7.0-M2-incubating/brooklyn-example-simple-nosql-cluster-0.7.0-M2-incubating.jar - file://~/.m2/repository/io/brooklyn/example/brooklyn-examples-webapps-parent/0.7.0-M2-incubating/brooklyn-examples-webapps-parent-0.7.0-M2-incubating.jar - - - - http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/a7a317bf/docs/guide/dev/build/eclipse.include.md ---------------------------------------------------------------------- diff --git a/docs/guide/dev/build/eclipse.include.md b/docs/guide/dev/build/eclipse.include.md deleted file mode 100644 index e0dc3c0..0000000 --- a/docs/guide/dev/build/eclipse.include.md +++ /dev/null @@ -1,15 +0,0 @@ - -- Maven Plugin: m2e from [download.eclipse.org/technology/m2e/releases](http://download.eclipse.org/technology/m2e/releases), or for kepler [http://download.eclipse.org/releases/kepler](http://download.eclipse.org/releases/kepler) - (typically bundled with Eclipse or available in the default update site set) - -- Git Plugin: egit from [download.eclipse.org/egit/updates](http://download.eclipse.org/egit/updates) - (typically bundled with Eclipse or available in the default update site set) - -- Groovy Plugin: GRECLIPSE from - [dist.springsource.org/release/GRECLIPSE/e4.3](http://dist.springsource.org/release/GRECLIPSE/e4.3) - (or for Eclipse [4.2](http://dist.springsource.org/release/GRECLIPSE/e4.2) - or [3.7](http://dist.springsource.org/release/GRECLIPSE/e3.7)). - Be sure to include Groovy 1.8.6 compiler support and Maven-Eclipse (m2e) support. - More details are at the [groovy update site](http://groovy.codehaus.org/Eclipse+Plugin). - -- TestNG Plugin: beust TestNG from [beust.com/eclipse](http://beust.com/eclipse) http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/a7a317bf/docs/guide/dev/build/ide.md ---------------------------------------------------------------------- diff --git a/docs/guide/dev/build/ide.md b/docs/guide/dev/build/ide.md deleted file mode 100644 index 3abae3c..0000000 --- a/docs/guide/dev/build/ide.md +++ /dev/null @@ -1,123 +0,0 @@ ---- -layout: guide-normal -title: IDE Setup -toc: /guide/toc.json ---- - -Gone are the days when IDE integration always just works... Maven and Eclipse fight, -neither quite gets along perfectly with Groovy, -git branch switches (sooo nice) can be slow, etc etc. - -But with a bit of a dance the IDE can still be your friend, -making it much easier to run tests and debug. - -As a general tip, don't always trust the IDE to build correctly; if you hit a snag, -do a command-line ``mvn clean install`` (optionally with ``-DskipTests``) -then refresh the project. - -See instructions below for specific IDEs. - - -## Eclipse - -If you're an Eclipse user, you'll probably want the Maven (m2e) plugin -and the Groovy Eclipse plugin (used for testing and examples primarily). -You may also want Git and TestNG plugins. -You can install these using Help -> Install New Software, or from the Eclipse Marketplace: - -{% readj eclipse.include.md %} - -As of this writing, Eclipse 4.2 and Eclipse 4.3 are commonly used, -and the codebase can be imported (Import -> Existing Maven Projects) -and successfully built and run inside an IDE. -However there are quirks, and mileage may vary. - -If you encounter issues, the following hints may be helpful: - -* If you attempt to import projects before the plugins are installed, you may encounter errors such as - '``No marketplace entries found to handle maven-compiler-plugin:2.3.2:compile in Eclipse``', - and the projects will not be recognized as java projects. If you do, simply cancel the import - (or delete the imported projects if they have been imported) and install the plugins as described above. - If you have installed plugins from alternative locations, remove them and re-install them from the locations - specified above. - -* A quick command-line build (`mvn clean install -DskipTests`) followed by a workspace refresh - can be useful to re-populate files which need to be copied to `target/` - -* m2e likes to put `excluding="**"` on `resources` directories; if you're seeing funny missing files - (things like not resolving jclouds/aws-ec2 locations or missing WARs), try building clean install - from the command-line then doing Maven -> Update Project (clean uses a maven-replacer-plugin to fix - `.classpath`s). - Alternatively you can go through and remove these manually in Eclipse (Build Path -> Configure) - or the filesystem, or use - the following command to remove these rogue blocks in the generated `.classpath` files: - -{% highlight bash %} -% find . -name .classpath -exec sed -i.bak 's/[ ]*..cluding="[\*\/]*\(\.java\)*"//g' {} \; -{% endhighlight %} - -* If m2e reports import problems, it is usually okay (even good) to mark all to "Resolve All Later". - The build-helper connector is useful if you're prompted for it, but - do *not* install the Tycho OSGi configurator (this causes show-stopping IAE's, and we don't need Eclipse to make bundles anyway). - You can manually mark as permanently ignored certain errors; - this updates the pom.xml (and should be current). - -* You may need to ensure ``src/main/{java,resources}`` is created in each project dir, - if (older versions) complain about missing directories, - and the same for ``src/test/{java,resources}`` *if* there are tests (``src/test`` exists): - -{% highlight bash %} -find . \( -path "*/src/main" -or -path "*/src/test" \) -exec echo {} \; -exec mkdir -p {}/{java,resources} \; -{% endhighlight %} - -* You may need to add the groovy nature (or even java nature) to projects; - with some maven-eclipse plugins this works fine, - but for others (older ones) you may need to handcraft these - (either right-click the project in the Package Explorer and choose Configure, - or edit the ``.project`` manually adding it to the project properties). - The tips [for jclouds maven-eclipse](http://www.jclouds.org/documentation/devguides/using-eclipse) might be helpful. - -If the pain starts to be too much, come find us on IRC #brooklyncentral or [elsewhere]({{site.path.guide}}/meta/contact.html) and we can hopefully share our pearls. -(And if you have a tip we haven't mentioned please let us know that too!) - - - -## IntelliJ IDEA - -To develop or debug Brooklyn in IntelliJ, you will need to ensure that the Groovy and TestNG plugins are installed -via the IntelliJ IDEA | Preferences | Plugins menu. Once installed, you can open Brooklyn from the root folder, -(e.g. ``~/myfiles/brooklyn``) which will automatically open the subprojects. - -There have previously been issues where the java 6 compiler incorrectly identified the return type of functions that use -generics. These issues have been refactored away, however may return in future. If so, you can either set the java compiler -level to 1.7, or setup IntelliJ to use the Eclipse compiler as per the instructions provided by JetBeans: - -> The problem seems to be caused by bug in java compiler from JDK 1.6, it is known to sometimes produce compilation -> errors for complicated code involving generic types. Java compiler from JDK 1.7 compiles your code successfully so I would -> recommend you to consider upgrading to JDK 1.7. If it isn't possible you can switch to Eclipse Compiler (Settings | -> Compiler | Java Compiler | "Use Compiler" combobox). - - -## Netbeans - -Tips from Netbeans users wanted! - - - -## Debugging Tips - -To debug Brooklyn, create a launch configuration which launches the ``BrooklynJavascriptGuiLauncher`` class. NOTE: You may -need to add additional projects or folders to the classpath of the run configuration (e.g. add the brooklyn-software-nosql -project if you wish to deploy a MongoDBServer). You will also need to ensure that the working directory is set to the jsgui -folder. For IntelliJ, you can set the 'Working directory' of the Run/Debug Configuration to ``$MODULE_DIR/../jsgui``. For -Eclipse, use the default option of ``${workspace_loc:brooklyn-jsgui}``. - -To debug the jsgui (the Brooklyn web console), you will need to build Brooklyn with -DskipOptimization to prevent the build from minifying the javascript. -When building via the command line, use the command ``mvn clean install -DskipOptimization``, and if you are using IntelliJ IDEA, you can add the option -to the Maven Runner by clicking on the Maven Settings icon in the Maven Projects tool window and adding the ``skipOptimization`` property with no value. - -When running at the command line you can enable remote connections so that one can attach a debugger to the Java process: - Run Java with the following on the command line or in JAVA_OPTS: ``-agentlib:jdwp=transport=dt_socket,server=y,suspend=n,address=5005`` - -To debug a brooklyn instance that has been run with the above JAVA_OPTS, create a remote build configuration (IntelliJ - -Run | Edit Configurations | + | Remote) with the default options, ensuring the port matches the address specified in JAVA_OPTS. http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/a7a317bf/docs/guide/dev/build/index.md ---------------------------------------------------------------------- diff --git a/docs/guide/dev/build/index.md b/docs/guide/dev/build/index.md deleted file mode 100644 index 90aa6fa..0000000 --- a/docs/guide/dev/build/index.md +++ /dev/null @@ -1,184 +0,0 @@ ---- -layout: guide-normal -title: Maven Build -toc: /guide/toc.json ---- - -## The Basics - -To build the code, you need Maven (v3) installed and Java (1.6). -With that in place, you should be able to build everything with a: - -{% highlight bash %} -brooklyn% mvn clean install -{% endhighlight %} - -Key things to note if you're new to Maven: - -* You may need more JVM memory, e.g. at the command-line (or in `.profile`): - - ``export MAVEN_OPTS="-Xmx1024m -Xms512m -XX:MaxPermSize=256m`` - -* You can do this in specific projects as well. - -* Add ``-DskipTests`` to skip tests. - -* Run ``-PIntegration`` to run integration tests, or ``-PLive`` to run live tests - ([tests described here](tests.html)) - -* Nearly all the gory details are in the root ``pom.xml``, which is referenced by child project poms. - -* You can also open and use the code in your favourite IDE, - although you may hit a few **[snags](ide.html)** - (that link has some tips for resolving them too) - - -## When the RAT Bites - -We use RAT to ensure that all files are compliant to Apache standards. Most of the time you shouldn't see it or need to know about it, but if it detects a violation, you'll get a message such as: - - [ERROR] Failed to execute goal org.apache.rat:apache-rat-plugin:0.10:check (default) on project brooklyn-parent: Too many files with unapproved license: 1 See RAT report in: /Users/alex/Data/cloudsoft/dev/gits/brooklyn/target/rat.txt -> [Help 1] - -If there's a problem, see the file `rat.txt` in the `target` directory of the failed project. (Maven will show you this link in its output.) - -Often the problem is one of the following: - -* You've added a file which requires the license header but doesn't have it - - **Resolution:** Simply copy the header from another file - -* You've got some temporary files which RAT things should have headers - - **Resolution:** Move the files away, add headers, or turn off RAT (see below) - -* The project structure has changed and you have stale files (e.g. in a `target` directory) - - **Resolution:** Remove the stale files, e.g. with `git clean -df` (and if needed a `find . -name target -prune -exec rm -rf {} \;` to delete folders named `target`) - -To disable RAT checking on a build, set `rat.ignoreErrors`, e.g. `mvn -Drat.ignoreErrors=true clean install`. (But note you will need RAT to pass in order for a PR to be accepted!) - -If there is a good reason that a file, pattern, or directory should be permanently ignored, that is easy to add inside the root `pom.xml`. - - -## Other Handy Hints - -* On some **Ubuntu** (e.g. 10.4 LTS) maven v3 is not currently available from the repositories. - Some instructions for installing at are [at superuser.com](http://superuser.com/questions/298062/how-do-i-install-maven-3). - -* The **mvnf** script - ([get the gist here](https://gist.github.com/2241800)) - simplifies building selected projects, so if you just change something in ``software-webapp`` - and then want to re-run the examples you can do: - - ``examples/simple-web-cluster% mvnf ../../{software/webapp,usage/all}`` - -* The **developers catalog** ([developers-catalog.xml](developers-catalog.xml)) uses artifacts from your local `~/.m2/repository/...` (after building from source). This avoids unnecessary web requests to Maven Central or Sonatype, and will allow you to work off-line. - - ``wget {{site.url_root}}{{site.path.guide}}/dev/build/developers-catalog.xml > ~/.brooklyn/catalog.xml`` - -## Appendix: Sample Output - -A healthy build will look something like the following, -including a few warnings (which we have looked into and -understand to be benign and hard to get rid of them, -although we'd love to if anyone can help!): - -{% highlight bash %} -brooklyn% mvn clean install -[INFO] Scanning for projects... -[INFO] ------------------------------------------------------------------------ -[INFO] Reactor Build Order: -[INFO] -[INFO] Brooklyn Parent Project -[INFO] Brooklyn Utilities to Support Testing (listeners etc) -[INFO] Brooklyn Logback Includable Configuration -[INFO] Brooklyn Common Utilities -[INFO] Brooklyn Groovy Utilities -[INFO] Brooklyn API - -... - -[WARNING] Ignoring project type war - supportedProjectTypes = [jar] - -... - -[WARNING] We have a duplicate org/xmlpull/v1/XmlPullParser.class in /Users/aled/.m2/repository/xpp3/xpp3_min/1.1.4c/xpp3_min-1.1.4c.jar - -... - -[INFO] — maven-assembly-plugin:2.3:single (build-distribution-dir) @ brooklyn-dist — -[INFO] Reading assembly descriptor: src/main/config/build-distribution-dir.xml -[WARNING] Cannot include project artifact: io.brooklyn:brooklyn-dist:jar:0.7.0-SNAPSHOT; it doesn't have an associated file or directory. -[INFO] Copying files to /Users/aled/repos/apache/incubator-brooklyn/usage/dist/target/brooklyn-dist -[WARNING] Assembly file: /Users/aled/repos/apache/incubator-brooklyn/usage/dist/target/brooklyn-dist is not a regular file (it may be a directory). It cannot be attached to the project build for installation or deployment. - -... - -[INFO] — maven-assembly-plugin:2.3:single (build-distribution-archive) @ brooklyn-dist — -[INFO] Reading assembly descriptor: src/main/config/build-distribution-archive.xml -[WARNING] Cannot include project artifact: io.brooklyn:brooklyn-dist:jar:0.7.0-SNAPSHOT; it doesn't have an associated file or directory. -[INFO] Building tar: /Users/aled/repos/apache/incubator-brooklyn/usage/dist/target/brooklyn-0.7.0-SNAPSHOT-dist.tar.gz -[WARNING] Cannot include project artifact: io.brooklyn:brooklyn-dist:jar:0.7.0-SNAPSHOT; it doesn't have an associated file or directory. - -... - -[WARNING] Don't override file /Users/aled/repos/apache/incubator-brooklyn/usage/archetypes/quickstart/target/test-classes/projects/integration-test-1/project/brooklyn-sample/src/main/resources/sample-icon.png - -... - -[INFO] Reactor Summary: -[INFO] -[INFO] Brooklyn Parent Project ........................... SUCCESS [3.072s] -[INFO] Brooklyn Utilities to Support Testing (listeners etc) SUCCESS [3.114s] -[INFO] Brooklyn Logback Includable Configuration ......... SUCCESS [0.680s] -[INFO] Brooklyn Common Utilities ......................... SUCCESS [7.263s] -[INFO] Brooklyn Groovy Utilities ......................... SUCCESS [5.193s] -[INFO] Brooklyn API ...................................... SUCCESS [2.146s] -[INFO] Brooklyn Test Support ............................. SUCCESS [2.517s] -[INFO] CAMP Server Parent Project ........................ SUCCESS [0.075s] -[INFO] CAMP Base ......................................... SUCCESS [4.079s] -[INFO] Brooklyn REST Swagger Apidoc Utilities ............ SUCCESS [1.983s] -[INFO] Brooklyn Logback Configuration .................... SUCCESS [0.625s] -[INFO] CAMP Server ....................................... SUCCESS [5.446s] -[INFO] Brooklyn Core ..................................... SUCCESS [1:24.122s] -[INFO] Brooklyn Policies ................................. SUCCESS [44.425s] -[INFO] Brooklyn Hazelcast Storage ........................ SUCCESS [7.143s] -[INFO] Brooklyn Jclouds Location Targets ................. SUCCESS [16.488s] -[INFO] Brooklyn Secure JMXMP Agent ....................... SUCCESS [8.634s] -[INFO] Brooklyn JMX RMI Agent ............................ SUCCESS [2.315s] -[INFO] Brooklyn Software Base ............................ SUCCESS [28.538s] -[INFO] Brooklyn Network Software Entities ................ SUCCESS [3.896s] -[INFO] Brooklyn OSGi Software Entities ................... SUCCESS [4.589s] -[INFO] Brooklyn Web App Software Entities ................ SUCCESS [17.484s] -[INFO] Brooklyn Messaging Software Entities .............. SUCCESS [7.106s] -[INFO] Brooklyn Database Software Entities ............... SUCCESS [5.229s] -[INFO] Brooklyn NoSQL Data Store Software Entities ....... SUCCESS [11.901s] -[INFO] Brooklyn Monitoring Software Entities ............. SUCCESS [4.027s] -[INFO] Brooklyn CAMP REST API ............................ SUCCESS [15.285s] -[INFO] Brooklyn REST API ................................. SUCCESS [4.489s] -[INFO] Brooklyn REST Server .............................. SUCCESS [30.270s] -[INFO] Brooklyn REST Client .............................. SUCCESS [7.007s] -[INFO] Brooklyn REST JavaScript Web GUI .................. SUCCESS [24.397s] -[INFO] Brooklyn Launcher ................................. SUCCESS [15.923s] -[INFO] Brooklyn Command Line Interface ................... SUCCESS [9.279s] -[INFO] Brooklyn All Things ............................... SUCCESS [13.875s] -[INFO] Brooklyn Distribution ............................. SUCCESS [49.370s] -[INFO] Brooklyn Quick-Start Project Archetype ............ SUCCESS [12.053s] -[INFO] Brooklyn Examples Aggregator Project .............. SUCCESS [0.085s] -[INFO] Brooklyn Examples Support Aggregator Project - Webapps SUCCESS [0.053s] -[INFO] hello-world-webapp Maven Webapp ................... SUCCESS [0.751s] -[INFO] hello-world-sql-webapp Maven Webapp ............... SUCCESS [0.623s] -[INFO] Brooklyn Simple Web Cluster Example ............... SUCCESS [5.398s] -[INFO] Brooklyn Global Web Fabric Example ................ SUCCESS [3.176s] -[INFO] Brooklyn Simple Messaging Publish-Subscribe Example SUCCESS [3.217s] -[INFO] Brooklyn NoSQL Cluster Examples ................... SUCCESS [6.790s] -[INFO] Brooklyn QA ....................................... SUCCESS [7.117s] -[INFO] ------------------------------------------------------------------------ -[INFO] BUILD SUCCESS -[INFO] ------------------------------------------------------------------------ -[INFO] Total time: 8:33.983s -[INFO] Finished at: Mon Jul 21 14:56:46 BST 2014 -[INFO] Final Memory: 66M/554M -[INFO] ------------------------------------------------------------------------ - -{% endhighlight %} http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/a7a317bf/docs/guide/dev/build/tests.md ---------------------------------------------------------------------- diff --git a/docs/guide/dev/build/tests.md b/docs/guide/dev/build/tests.md deleted file mode 100644 index f202dc2..0000000 --- a/docs/guide/dev/build/tests.md +++ /dev/null @@ -1,26 +0,0 @@ ---- -layout: guide-normal -title: Tests -toc: /guide/toc.json ---- - -We have the following tests groups: - -* normal (i.e. no group) -- should run quickly, not need internet, and not side effect the machine (apart from a few /tmp files) -* Integration -- deploys locally, may read and write from internet, takes longer. - If you change an entity, rerun the relevant integration test to make sure all is well! -* Live -- deploys remotely, may provision machines (but should clean up, getting rid of them in a try block) -* Live-sanity -- a sub-set of "Live" that can be run regularly; a trade-off of optimal code coverage for the - time/cost of those tests. -* WIP -- short for "work in progress", this will disable the test from being run by the normal brooklyn maven profiles, - while leaving the test enabled so that one can work on it in IDEs or run the selected test(s) from the command line. -* Acceptance -- this (currently little-used) group is for very long running tests, such as soak tests - -To run these from the command line, use something like the following: - -* normal: `mvn clean install` -* integration: `mvn clean verify -PEssentials,Locations,Entities,Integration -Dmaven.test.failure.ignore=true` -* Live: `mvn clean verify -PEntities,Locations,Entities,Live -Dmaven.test.failure.ignore=true` -* Live-sanity: `mvn clean verify -PEntities,Locations,Entities,Live-sanity -Dmaven.test.failure.ignore=true` - - http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/a7a317bf/docs/guide/dev/build/toc.json ---------------------------------------------------------------------- diff --git a/docs/guide/dev/build/toc.json b/docs/guide/dev/build/toc.json deleted file mode 100644 index 192f1e3..0000000 --- a/docs/guide/dev/build/toc.json +++ /dev/null @@ -1,8 +0,0 @@ -[ -{ "title": "Maven", - "file": "{{ site.path.guide }}/dev/build/index.html" }, -{ "title": "IDE", - "file": "{{ site.path.guide }}/dev/build/ide.html" }, -{ "title": "Tests", - "file": "{{ site.path.guide }}/dev/build/tests.html" } -] http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/a7a317bf/docs/guide/dev/code/entity.md ---------------------------------------------------------------------- diff --git a/docs/guide/dev/code/entity.md b/docs/guide/dev/code/entity.md deleted file mode 100644 index f84e23c..0000000 --- a/docs/guide/dev/code/entity.md +++ /dev/null @@ -1,91 +0,0 @@ ---- -layout: guide-normal -title: Writing an Entity -toc: /guide/toc.json ---- - -## Ways to write an entity - -There are several ways to write a new entity: - -* Write pure-java, extending existing base-classes and using utilities such as `HttpTool` and `BashCommands`. -* Write scripts, and configure (e.g. using YAML) a **`VanillaSoftwareProcess`**. -* Use Chef recipes, and wire these into the entity by using `ChefConfig` and `ChefLifecycleEffectorTasks`. -* Use an equivalent of Chef (e.g. Salt or Puppet; support for these is currently less mature than for Chef) - -The rest of this section covers writing an entity in pure-java (or other JVM languages). - - -## Things To Know - -All entities have an interface and an implementation. The methods on the interface -are its effectors; the interface also defines its sensors. - -Entities are created through the management context (rather than calling the -constructor directly). This returns a proxy for the entity rather than the real -instance, which is important in a distributed management plane. - -All entity implementations inherit from `AbstractEntity`, -often through one of the following: - -* **`SoftwareProcessImpl`**: if it's a software process -* **`VanillaJavaAppImpl`**: if it's a plain-old-java app -* **`JavaWebAppSoftwareProcessImpl`**: if it's a JVM-based web-app -* **`DynamicClusterImpl`**, **`DynamicGroupImpl`** or **`AbstractGroupImpl`**: if it's a collection of other entities - -Software-based processes tend to use *drivers* to install and -launch the remote processes onto *locations* which support that driver type. -For example, `AbstractSoftwareProcessSshDriver` is a common driver superclass, -targetting `SshMachineLocation` (a machine to which Brooklyn can ssh). -The various `SoftwareProcess` entities above (and some of the exemplars -listed at the end of this page) have their own dedicated drivers. - -Finally, there are a collection of *traits*, such as `Resizable`, -in the package ``brooklyn.entity.trait``. These provide common -sensors and effectors on entities, supplied as interfaces. -Choose one (or more) as appropriate. - - - -## Key Steps - -So to get started: - -1. Create your entity interface, extending the appropriate selection from above, - to define the effectors and sensors. -2. Include an annotation like `@ImplementedBy(YourEntityImpl.class)` on your interface, - where `YourEntityImpl` will be the class name for your entity implementation. -3. Create your entity class, implementing your entity interface and extending the - classes for your chosen entity super-types. Naming convention is a suffix "Impl" - for the entity class, but this is not essential. -4. Create a driver interface, again extending as appropriate (e.g. `SoftwareProcessDriver`). - The naming convention is to have a suffix "Driver". -5. Create the driver class, implementing your driver interface, and again extending as appropriate. - Naming convention is to have a suffix "SshDriver" for an ssh-based implementation. - The correct driver implementation is found using this naming convention, or via custom - namings provided by the `BasicEntityDriverFactory`. -6. Wire the `public Class getDriverInterface()` method in the entity implementation, to specify - your driver interface. -7. Provide the implementation of missing lifecycle methods in your driver class (details below) -8. Connect the sensors from your entity (e.g. overriding `connectSensors()` of `SoftwareProcessImpl`).. - See the sensor feeds, such as `HttpFeed` and `JmxFeed`. - -Any JVM language can be used to write an entity. However use of pure Java is encouraged for -entities in core brooklyn. - - -## Helpful References - -A few handy pointers will help make it easy to build your own entities. -Check out some of the exemplar existing entities -(note, some of the other entities use deprecated utilities and a deprecated class -hierarchy; it is suggested to avoid these, looking at the ones below instead): - -* `JBoss7Server` -* `MySqlNode` - -You might also find the following helpful: - -* **[Entity Design Tips]({{site.path.guide}}/dev/tips/index.html#EntityDesign)** -* The **[User Guide]({{site.path.guide}}/use/guide/index.html)** -* The **[Mailing List](https://mail-archives.apache.org/mod_mbox/incubator-brooklyn-dev/)** http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/a7a317bf/docs/guide/dev/code/index.include.md ---------------------------------------------------------------------- diff --git a/docs/guide/dev/code/index.include.md b/docs/guide/dev/code/index.include.md deleted file mode 100644 index d25c163..0000000 --- a/docs/guide/dev/code/index.include.md +++ /dev/null @@ -1,96 +0,0 @@ -## The Basics - -Brooklyn is available at [GitHub apache/incubator-brooklyn](http://github.com/apache/incubator-brooklyn). Check it out using: - -{% highlight bash %} -git clone git@github.com:apache/incubator-brooklyn.git -cd brooklyn -{% endhighlight %} - -Build it with: - -{% highlight bash %} -mvn clean install -{% endhighlight %} - -And launch it with: - -{% highlight bash %} -cd usage/dist/target/brooklyn-dist/ -bin/brooklyn launch -{% endhighlight %} - -Plenty of examples are in the **examples** sub-dir, -described [here]({{site.path.guide}}/use/examples). - -Information on using Brooklyn -- configuring locations (in `brooklyn.properties`) -and adding new projects to a catalog -- can be found in the [User's Guide]({{site.path.guide}}/use/guide/quickstart/index.html). -This document is intended to help people become familiar with the codebase. - -## Project Structure - -Brooklyn is split into the following projects and sub-projects: - -* **``camp``**: the components for a server which speaks the CAMP REST API and which understands the CAMP YAML plan language -* **``api``**: the pure-Java interfaces for interacting with the system -* **``core``**: the base class implementations for entities and applications, entity traits, locations, policies, sensor and effector support, tasks, and more -* **``locations``**: specific location integrations - * **``jclouds``**: integration with many cloud APIs and providers, via Apache jclouds -* **``policies``**: collection of useful policies for automating entity activity -* **``software``**: entities which are mainly launched by launched software processes on machines, and collections thereof - * **``base``**: software process lifecycle abstract classes and drivers (e.g. SSH) - * **``webapp``**: web servers (JBoss, Tomcat), load-balancers (Nginx), and DNS (Geoscaling) - * **``database``**: relational databases (SQL) - * **``nosql``**: datastores other than RDBMS/SQL (often better in distributed environments) - * **``messaging``**: messaging systems, including Qpid, Apache MQ, RabbitMQ - * **``monitoring``**: monitoring tools, including Monit - * **``osgi``**: OSGi servers - * **...** -* **``utils``**: projects which lower level utilities - * **common**: Utility classes and methods developed for Brooklyn but not dependendent on Brooklyn - * **groovy**: Groovy extensions and utility classes and methods developed for Brooklyn but not dependendent on Brooklyn - * **jmx/jmxmp-ssl-agent**: An agent implementation that can be attached to a Java process, to give expose secure JMXMP - * **jmx/jmxrmi-agent**: An agent implementation that can be attached to a Java process, to give expose JMX-RMI without requiring all high-number ports to be open - * **rest-swagger**: Swagger REST API utility classes and methods developed for Brooklyn but not dependendent on Brooklyn - * **test-support**: Test utility classes and methods developed for Brooklyn but not dependendent on Brooklyn -* **``usage``**: projects which make Brooklyn easier to use, either for end-users or Brooklyn developers - * **all**: maven project to supply a shaded JAR (containing all dependencies) for convenience - * **archetypes**: A maven archetype, for easily generating the structure of a new downstream projects - * **camp**: Brooklyn bindings for the CAMP REST API - * **cli**: backing implementation for Brooklyn's command line interface - * **dist**: builds brooklyn as a downloadable .zip and .tar.gz - * **jsgui**: Javascript web-app for the brooklyn management web console (builds a WAR) - * **launcher**: for launching brooklyn, either using a main method or invoked from the cli project - * **logback-includes**: Various helpful logback XML files that can be included; does not contain logback.xml - * **logback-xml**: Contains a logback.xml that references the include files in brooklyn-logback-includes - * **rest-api**: The API classes for the Brooklyn REST api - * **rest-client**: A client Java implementation for using the Brooklyn REST API - * **rest-server**: The server-side implementation of the Brooklyn REST API - * **scripts**: various scripts useful for building, updating, etc. (see comments in the scripts) - * **qa**: longevity and stress tests - * **test-support**: provides Brooklyn-specific support for tests, used by nearly all projects in scope ``test`` -* **``docs``**: the markdown source code for this documentation, as described [here]({{site.path.guide}}/dev/tips/update-docs.html) -* **``examples``**: some canonical examples, as listed [here]({{site.path.guide}}/use/examples) -* **``sandbox``**: various projects, entities, and policies which the Brooklyn Project is incubating - - -## Next Steps - -If you're interested in building and editing the code, check out: - -* [Maven setup](../build/index.html) -* [IDE setup](../build/ide.html) -* [Tests](../build/tests.html) -* [Tips](../tips/index.html) - -If you want to start writing your own policies and entities, have a look at: - -* [Writing a Brooklyn Entity](entity.html) -* [Writing a Brooklyn Policy](policy.html) -* Or see the [User Guide]({{ site.path.guide }}/use/guide/index.html) - on [policies]({{ site.path.guide }}/use/guide/policies/index.html) - and [entities]({{ site.path.guide }}/use/guide/entities/index.html) - -Where things aren't documented **please ask us** at -[the brooklyn mailing list](https://mail-archives.apache.org/mod_mbox/incubator-brooklyn-dev/) -so we can remedy this! http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/a7a317bf/docs/guide/dev/code/index.md ---------------------------------------------------------------------- diff --git a/docs/guide/dev/code/index.md b/docs/guide/dev/code/index.md index 8220a8d..1d4407b 100644 --- a/docs/guide/dev/code/index.md +++ b/docs/guide/dev/code/index.md @@ -1,7 +1,94 @@ --- -layout: guide-normal -title: Code Structure -toc: /guide/toc.json +title: About the Code +layout: website-normal --- -{% readj index.include.md %} +## The Basics + +Brooklyn is available at [GitHub apache/incubator-brooklyn](http://github.com/apache/incubator-brooklyn). Check it out using: + +{% highlight bash %} +git clone git@github.com:apache/incubator-brooklyn.git +cd brooklyn +{% endhighlight %} + +Build it with: + +{% highlight bash %} +mvn clean install +{% endhighlight %} + +And launch it with: + +{% highlight bash %} +cd usage/dist/target/brooklyn-dist/ +bin/brooklyn launch +{% endhighlight %} + +Plenty of examples are in the **examples** sub-dir, +described [here]({{site.path.guide}}/use/examples). + +Information on using Brooklyn -- configuring locations (in `brooklyn.properties`) +and adding new projects to a catalog -- can be found in the [User's Guide]({{site.path.guide}}/use/guide/quickstart/index.html). +This document is intended to help people become familiar with the codebase. + +## Project Structure + +Brooklyn is split into the following projects and sub-projects: + +* **``camp``**: the components for a server which speaks the CAMP REST API and which understands the CAMP YAML plan language +* **``api``**: the pure-Java interfaces for interacting with the system +* **``core``**: the base class implementations for entities and applications, entity traits, locations, policies, sensor and effector support, tasks, and more +* **``locations``**: specific location integrations + * **``jclouds``**: integration with many cloud APIs and providers, via Apache jclouds +* **``policies``**: collection of useful policies for automating entity activity +* **``software``**: entities which are mainly launched by launched software processes on machines, and collections thereof + * **``base``**: software process lifecycle abstract classes and drivers (e.g. SSH) + * **``webapp``**: web servers (JBoss, Tomcat), load-balancers (Nginx), and DNS (Geoscaling) + * **``database``**: relational databases (SQL) + * **``nosql``**: datastores other than RDBMS/SQL (often better in distributed environments) + * **``messaging``**: messaging systems, including Qpid, Apache MQ, RabbitMQ + * **``monitoring``**: monitoring tools, including Monit + * **``osgi``**: OSGi servers + * **...** +* **``utils``**: projects which lower level utilities + * **common**: Utility classes and methods developed for Brooklyn but not dependendent on Brooklyn + * **groovy**: Groovy extensions and utility classes and methods developed for Brooklyn but not dependendent on Brooklyn + * **jmx/jmxmp-ssl-agent**: An agent implementation that can be attached to a Java process, to give expose secure JMXMP + * **jmx/jmxrmi-agent**: An agent implementation that can be attached to a Java process, to give expose JMX-RMI without requiring all high-number ports to be open + * **rest-swagger**: Swagger REST API utility classes and methods developed for Brooklyn but not dependendent on Brooklyn + * **test-support**: Test utility classes and methods developed for Brooklyn but not dependendent on Brooklyn +* **``usage``**: projects which make Brooklyn easier to use, either for end-users or Brooklyn developers + * **all**: maven project to supply a shaded JAR (containing all dependencies) for convenience + * **archetypes**: A maven archetype, for easily generating the structure of a new downstream projects + * **camp**: Brooklyn bindings for the CAMP REST API + * **cli**: backing implementation for Brooklyn's command line interface + * **dist**: builds brooklyn as a downloadable .zip and .tar.gz + * **jsgui**: Javascript web-app for the brooklyn management web console (builds a WAR) + * **launcher**: for launching brooklyn, either using a main method or invoked from the cli project + * **logback-includes**: Various helpful logback XML files that can be included; does not contain logback.xml + * **logback-xml**: Contains a logback.xml that references the include files in brooklyn-logback-includes + * **rest-api**: The API classes for the Brooklyn REST api + * **rest-client**: A client Java implementation for using the Brooklyn REST API + * **rest-server**: The server-side implementation of the Brooklyn REST API + * **scripts**: various scripts useful for building, updating, etc. (see comments in the scripts) + * **qa**: longevity and stress tests + * **test-support**: provides Brooklyn-specific support for tests, used by nearly all projects in scope ``test`` +* **``docs``**: the markdown source code for this documentation, as described [here]({{site.path.guide}}/dev/tips/update-docs.html) +* **``examples``**: some canonical examples, as listed [here]({{site.path.guide}}/use/examples) +* **``sandbox``**: various projects, entities, and policies which the Brooklyn Project is incubating + + +## Next Steps + +If you're interested in building and editing the code, check out: + +* [Maven setup](../env/maven-build.html) +* [IDE setup](../env/ide/) +* [Tests](tests.html) +* [Tips](../tips/) +* [Remote Debugging](../tips/debugging-remote-brooklyn.html) + +Where things aren't documented **please ask us** at +[the brooklyn mailing list](https://mail-archives.apache.org/mod_mbox/incubator-brooklyn-dev/) +so we can remedy this! http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/a7a317bf/docs/guide/dev/code/policy.md ---------------------------------------------------------------------- diff --git a/docs/guide/dev/code/policy.md b/docs/guide/dev/code/policy.md deleted file mode 100644 index a62bdd2..0000000 --- a/docs/guide/dev/code/policy.md +++ /dev/null @@ -1,47 +0,0 @@ ---- -layout: guide-normal -title: Writing a Policy -toc: /guide/toc.json ---- - -Policies perform the active management enabled by Brooklyn. -Each policy instance is associated with an entity, -and at runtime it will typically subscribe to sensors on that entity or children, -performing some computation and optionally actions when a subscribed sensor event occurs. -This action might be invoking an effector or emitting a new sensor, -depending the desired behvaiour is. - -Writing a policy is straightforward. -Simply extend ``AbstractPolicy``, -overriding the ``setEntity`` method to supply any subscriptions desired: - -{% highlight java %} - @Override - public void setEntity(EntityLocal entity) { - super.setEntity(entity) - subscribe(entity, TARGET_SENSOR, this) - } -{% endhighlight %} - -and supply the computation and/or activity desired whenever that event occurs: - -{% highlight java %} - @Override - public void onEvent(SensorEvent event) { - int val = event.getValue() - if (val % 2 == 1) - entity.sayYoureOdd(); - } -{% endhighlight %} - -You'll want to do more complicated things, no doubt, -like access other entities, perform multiple subscriptions, -and emit other sensors -- and you can. -See the source code, and see some commonly used policies -in ``AutoScalerPolicy`` and ``RollingMeanEnricher``. - -One rule of thumb, to close on: -try to keep policies simple, and compose them together at runtime; -for instance, if a complex computation triggers an action, -define one **enricher** policy to aggregate other sensors and emit a new sensor, -then write a second policy to perform that action. http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/a7a317bf/docs/guide/dev/code/tests.md ---------------------------------------------------------------------- diff --git a/docs/guide/dev/code/tests.md b/docs/guide/dev/code/tests.md new file mode 100644 index 0000000..f202dc2 --- /dev/null +++ b/docs/guide/dev/code/tests.md @@ -0,0 +1,26 @@ +--- +layout: guide-normal +title: Tests +toc: /guide/toc.json +--- + +We have the following tests groups: + +* normal (i.e. no group) -- should run quickly, not need internet, and not side effect the machine (apart from a few /tmp files) +* Integration -- deploys locally, may read and write from internet, takes longer. + If you change an entity, rerun the relevant integration test to make sure all is well! +* Live -- deploys remotely, may provision machines (but should clean up, getting rid of them in a try block) +* Live-sanity -- a sub-set of "Live" that can be run regularly; a trade-off of optimal code coverage for the + time/cost of those tests. +* WIP -- short for "work in progress", this will disable the test from being run by the normal brooklyn maven profiles, + while leaving the test enabled so that one can work on it in IDEs or run the selected test(s) from the command line. +* Acceptance -- this (currently little-used) group is for very long running tests, such as soak tests + +To run these from the command line, use something like the following: + +* normal: `mvn clean install` +* integration: `mvn clean verify -PEssentials,Locations,Entities,Integration -Dmaven.test.failure.ignore=true` +* Live: `mvn clean verify -PEntities,Locations,Entities,Live -Dmaven.test.failure.ignore=true` +* Live-sanity: `mvn clean verify -PEntities,Locations,Entities,Live-sanity -Dmaven.test.failure.ignore=true` + + http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/a7a317bf/docs/guide/dev/code/toc.json ---------------------------------------------------------------------- diff --git a/docs/guide/dev/code/toc.json b/docs/guide/dev/code/toc.json deleted file mode 100644 index 6bb112b..0000000 --- a/docs/guide/dev/code/toc.json +++ /dev/null @@ -1,10 +0,0 @@ -[ -{ "title": "Structure", - "file": "{{ site.path.guide }}/dev/code/index.html" }, -{ "title": "Writing an Entity", - "file": "{{ site.path.guide }}/dev/code/entity.html" }, -{ "title": "Writing a Policy", - "file": "{{ site.path.guide }}/dev/code/policy.html" }, -{ "title": "brooklyn.git (github)", - "file": "http://github.com/apache/incubator-brooklyn" } -] http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/a7a317bf/docs/guide/dev/env/ide/eclipse.include.md ---------------------------------------------------------------------- diff --git a/docs/guide/dev/env/ide/eclipse.include.md b/docs/guide/dev/env/ide/eclipse.include.md new file mode 100644 index 0000000..b1cf5ea --- /dev/null +++ b/docs/guide/dev/env/ide/eclipse.include.md @@ -0,0 +1,15 @@ + +- Maven Plugin: m2e from [download.eclipse.org/technology/m2e/releases](http://download.eclipse.org/technology/m2e/releases), or for kepler [http://download.eclipse.org/releases/kepler](http://download.eclipse.org/releases/kepler) + (typically bundled with Eclipse or available in the default update site set) + +- Git Plugin: egit from [download.eclipse.org/egit/updates](http://download.eclipse.org/egit/updates) + (typically bundled with Eclipse or available in the default update site set) + +- Groovy Plugin: GRECLIPSE from + [dist.springsource.org/release/GRECLIPSE/e4.3](http://dist.springsource.org/release/GRECLIPSE/e4.3) + (or for Eclipse [4.2](http://dist.springsource.org/release/GRECLIPSE/e4.2) + or [3.7](http://dist.springsource.org/release/GRECLIPSE/e3.7)). + Be sure to include Groovy 2.3.4 compiler support and Maven-Eclipse (m2e) support. + More details are at the [groovy update site](http://groovy.codehaus.org/Eclipse+Plugin). + +- TestNG Plugin: beust TestNG from [beust.com/eclipse](http://beust.com/eclipse) http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/a7a317bf/docs/guide/dev/env/ide/index.md ---------------------------------------------------------------------- diff --git a/docs/guide/dev/env/ide/index.md b/docs/guide/dev/env/ide/index.md new file mode 100644 index 0000000..3abae3c --- /dev/null +++ b/docs/guide/dev/env/ide/index.md @@ -0,0 +1,123 @@ +--- +layout: guide-normal +title: IDE Setup +toc: /guide/toc.json +--- + +Gone are the days when IDE integration always just works... Maven and Eclipse fight, +neither quite gets along perfectly with Groovy, +git branch switches (sooo nice) can be slow, etc etc. + +But with a bit of a dance the IDE can still be your friend, +making it much easier to run tests and debug. + +As a general tip, don't always trust the IDE to build correctly; if you hit a snag, +do a command-line ``mvn clean install`` (optionally with ``-DskipTests``) +then refresh the project. + +See instructions below for specific IDEs. + + +## Eclipse + +If you're an Eclipse user, you'll probably want the Maven (m2e) plugin +and the Groovy Eclipse plugin (used for testing and examples primarily). +You may also want Git and TestNG plugins. +You can install these using Help -> Install New Software, or from the Eclipse Marketplace: + +{% readj eclipse.include.md %} + +As of this writing, Eclipse 4.2 and Eclipse 4.3 are commonly used, +and the codebase can be imported (Import -> Existing Maven Projects) +and successfully built and run inside an IDE. +However there are quirks, and mileage may vary. + +If you encounter issues, the following hints may be helpful: + +* If you attempt to import projects before the plugins are installed, you may encounter errors such as + '``No marketplace entries found to handle maven-compiler-plugin:2.3.2:compile in Eclipse``', + and the projects will not be recognized as java projects. If you do, simply cancel the import + (or delete the imported projects if they have been imported) and install the plugins as described above. + If you have installed plugins from alternative locations, remove them and re-install them from the locations + specified above. + +* A quick command-line build (`mvn clean install -DskipTests`) followed by a workspace refresh + can be useful to re-populate files which need to be copied to `target/` + +* m2e likes to put `excluding="**"` on `resources` directories; if you're seeing funny missing files + (things like not resolving jclouds/aws-ec2 locations or missing WARs), try building clean install + from the command-line then doing Maven -> Update Project (clean uses a maven-replacer-plugin to fix + `.classpath`s). + Alternatively you can go through and remove these manually in Eclipse (Build Path -> Configure) + or the filesystem, or use + the following command to remove these rogue blocks in the generated `.classpath` files: + +{% highlight bash %} +% find . -name .classpath -exec sed -i.bak 's/[ ]*..cluding="[\*\/]*\(\.java\)*"//g' {} \; +{% endhighlight %} + +* If m2e reports import problems, it is usually okay (even good) to mark all to "Resolve All Later". + The build-helper connector is useful if you're prompted for it, but + do *not* install the Tycho OSGi configurator (this causes show-stopping IAE's, and we don't need Eclipse to make bundles anyway). + You can manually mark as permanently ignored certain errors; + this updates the pom.xml (and should be current). + +* You may need to ensure ``src/main/{java,resources}`` is created in each project dir, + if (older versions) complain about missing directories, + and the same for ``src/test/{java,resources}`` *if* there are tests (``src/test`` exists): + +{% highlight bash %} +find . \( -path "*/src/main" -or -path "*/src/test" \) -exec echo {} \; -exec mkdir -p {}/{java,resources} \; +{% endhighlight %} + +* You may need to add the groovy nature (or even java nature) to projects; + with some maven-eclipse plugins this works fine, + but for others (older ones) you may need to handcraft these + (either right-click the project in the Package Explorer and choose Configure, + or edit the ``.project`` manually adding it to the project properties). + The tips [for jclouds maven-eclipse](http://www.jclouds.org/documentation/devguides/using-eclipse) might be helpful. + +If the pain starts to be too much, come find us on IRC #brooklyncentral or [elsewhere]({{site.path.guide}}/meta/contact.html) and we can hopefully share our pearls. +(And if you have a tip we haven't mentioned please let us know that too!) + + + +## IntelliJ IDEA + +To develop or debug Brooklyn in IntelliJ, you will need to ensure that the Groovy and TestNG plugins are installed +via the IntelliJ IDEA | Preferences | Plugins menu. Once installed, you can open Brooklyn from the root folder, +(e.g. ``~/myfiles/brooklyn``) which will automatically open the subprojects. + +There have previously been issues where the java 6 compiler incorrectly identified the return type of functions that use +generics. These issues have been refactored away, however may return in future. If so, you can either set the java compiler +level to 1.7, or setup IntelliJ to use the Eclipse compiler as per the instructions provided by JetBeans: + +> The problem seems to be caused by bug in java compiler from JDK 1.6, it is known to sometimes produce compilation +> errors for complicated code involving generic types. Java compiler from JDK 1.7 compiles your code successfully so I would +> recommend you to consider upgrading to JDK 1.7. If it isn't possible you can switch to Eclipse Compiler (Settings | +> Compiler | Java Compiler | "Use Compiler" combobox). + + +## Netbeans + +Tips from Netbeans users wanted! + + + +## Debugging Tips + +To debug Brooklyn, create a launch configuration which launches the ``BrooklynJavascriptGuiLauncher`` class. NOTE: You may +need to add additional projects or folders to the classpath of the run configuration (e.g. add the brooklyn-software-nosql +project if you wish to deploy a MongoDBServer). You will also need to ensure that the working directory is set to the jsgui +folder. For IntelliJ, you can set the 'Working directory' of the Run/Debug Configuration to ``$MODULE_DIR/../jsgui``. For +Eclipse, use the default option of ``${workspace_loc:brooklyn-jsgui}``. + +To debug the jsgui (the Brooklyn web console), you will need to build Brooklyn with -DskipOptimization to prevent the build from minifying the javascript. +When building via the command line, use the command ``mvn clean install -DskipOptimization``, and if you are using IntelliJ IDEA, you can add the option +to the Maven Runner by clicking on the Maven Settings icon in the Maven Projects tool window and adding the ``skipOptimization`` property with no value. + +When running at the command line you can enable remote connections so that one can attach a debugger to the Java process: + Run Java with the following on the command line or in JAVA_OPTS: ``-agentlib:jdwp=transport=dt_socket,server=y,suspend=n,address=5005`` + +To debug a brooklyn instance that has been run with the above JAVA_OPTS, create a remote build configuration (IntelliJ - +Run | Edit Configurations | + | Remote) with the default options, ensuring the port matches the address specified in JAVA_OPTS. http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/a7a317bf/docs/guide/dev/env/index.md ---------------------------------------------------------------------- diff --git a/docs/guide/dev/env/index.md b/docs/guide/dev/env/index.md new file mode 100644 index 0000000..ef00e89 --- /dev/null +++ b/docs/guide/dev/env/index.md @@ -0,0 +1,13 @@ +--- +title: Dev Environment +layout: website-normal +breadcrumbs: +- /website/documentation/index.md +- ../index.md +- index.md +children: +- maven-build.md +- ide/ +--- + +TODO \ No newline at end of file http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/a7a317bf/docs/guide/dev/env/maven-build.md ---------------------------------------------------------------------- diff --git a/docs/guide/dev/env/maven-build.md b/docs/guide/dev/env/maven-build.md new file mode 100644 index 0000000..90aa6fa --- /dev/null +++ b/docs/guide/dev/env/maven-build.md @@ -0,0 +1,184 @@ +--- +layout: guide-normal +title: Maven Build +toc: /guide/toc.json +--- + +## The Basics + +To build the code, you need Maven (v3) installed and Java (1.6). +With that in place, you should be able to build everything with a: + +{% highlight bash %} +brooklyn% mvn clean install +{% endhighlight %} + +Key things to note if you're new to Maven: + +* You may need more JVM memory, e.g. at the command-line (or in `.profile`): + + ``export MAVEN_OPTS="-Xmx1024m -Xms512m -XX:MaxPermSize=256m`` + +* You can do this in specific projects as well. + +* Add ``-DskipTests`` to skip tests. + +* Run ``-PIntegration`` to run integration tests, or ``-PLive`` to run live tests + ([tests described here](tests.html)) + +* Nearly all the gory details are in the root ``pom.xml``, which is referenced by child project poms. + +* You can also open and use the code in your favourite IDE, + although you may hit a few **[snags](ide.html)** + (that link has some tips for resolving them too) + + +## When the RAT Bites + +We use RAT to ensure that all files are compliant to Apache standards. Most of the time you shouldn't see it or need to know about it, but if it detects a violation, you'll get a message such as: + + [ERROR] Failed to execute goal org.apache.rat:apache-rat-plugin:0.10:check (default) on project brooklyn-parent: Too many files with unapproved license: 1 See RAT report in: /Users/alex/Data/cloudsoft/dev/gits/brooklyn/target/rat.txt -> [Help 1] + +If there's a problem, see the file `rat.txt` in the `target` directory of the failed project. (Maven will show you this link in its output.) + +Often the problem is one of the following: + +* You've added a file which requires the license header but doesn't have it + + **Resolution:** Simply copy the header from another file + +* You've got some temporary files which RAT things should have headers + + **Resolution:** Move the files away, add headers, or turn off RAT (see below) + +* The project structure has changed and you have stale files (e.g. in a `target` directory) + + **Resolution:** Remove the stale files, e.g. with `git clean -df` (and if needed a `find . -name target -prune -exec rm -rf {} \;` to delete folders named `target`) + +To disable RAT checking on a build, set `rat.ignoreErrors`, e.g. `mvn -Drat.ignoreErrors=true clean install`. (But note you will need RAT to pass in order for a PR to be accepted!) + +If there is a good reason that a file, pattern, or directory should be permanently ignored, that is easy to add inside the root `pom.xml`. + + +## Other Handy Hints + +* On some **Ubuntu** (e.g. 10.4 LTS) maven v3 is not currently available from the repositories. + Some instructions for installing at are [at superuser.com](http://superuser.com/questions/298062/how-do-i-install-maven-3). + +* The **mvnf** script + ([get the gist here](https://gist.github.com/2241800)) + simplifies building selected projects, so if you just change something in ``software-webapp`` + and then want to re-run the examples you can do: + + ``examples/simple-web-cluster% mvnf ../../{software/webapp,usage/all}`` + +* The **developers catalog** ([developers-catalog.xml](developers-catalog.xml)) uses artifacts from your local `~/.m2/repository/...` (after building from source). This avoids unnecessary web requests to Maven Central or Sonatype, and will allow you to work off-line. + + ``wget {{site.url_root}}{{site.path.guide}}/dev/build/developers-catalog.xml > ~/.brooklyn/catalog.xml`` + +## Appendix: Sample Output + +A healthy build will look something like the following, +including a few warnings (which we have looked into and +understand to be benign and hard to get rid of them, +although we'd love to if anyone can help!): + +{% highlight bash %} +brooklyn% mvn clean install +[INFO] Scanning for projects... +[INFO] ------------------------------------------------------------------------ +[INFO] Reactor Build Order: +[INFO] +[INFO] Brooklyn Parent Project +[INFO] Brooklyn Utilities to Support Testing (listeners etc) +[INFO] Brooklyn Logback Includable Configuration +[INFO] Brooklyn Common Utilities +[INFO] Brooklyn Groovy Utilities +[INFO] Brooklyn API + +... + +[WARNING] Ignoring project type war - supportedProjectTypes = [jar] + +... + +[WARNING] We have a duplicate org/xmlpull/v1/XmlPullParser.class in /Users/aled/.m2/repository/xpp3/xpp3_min/1.1.4c/xpp3_min-1.1.4c.jar + +... + +[INFO] — maven-assembly-plugin:2.3:single (build-distribution-dir) @ brooklyn-dist — +[INFO] Reading assembly descriptor: src/main/config/build-distribution-dir.xml +[WARNING] Cannot include project artifact: io.brooklyn:brooklyn-dist:jar:0.7.0-SNAPSHOT; it doesn't have an associated file or directory. +[INFO] Copying files to /Users/aled/repos/apache/incubator-brooklyn/usage/dist/target/brooklyn-dist +[WARNING] Assembly file: /Users/aled/repos/apache/incubator-brooklyn/usage/dist/target/brooklyn-dist is not a regular file (it may be a directory). It cannot be attached to the project build for installation or deployment. + +... + +[INFO] — maven-assembly-plugin:2.3:single (build-distribution-archive) @ brooklyn-dist — +[INFO] Reading assembly descriptor: src/main/config/build-distribution-archive.xml +[WARNING] Cannot include project artifact: io.brooklyn:brooklyn-dist:jar:0.7.0-SNAPSHOT; it doesn't have an associated file or directory. +[INFO] Building tar: /Users/aled/repos/apache/incubator-brooklyn/usage/dist/target/brooklyn-0.7.0-SNAPSHOT-dist.tar.gz +[WARNING] Cannot include project artifact: io.brooklyn:brooklyn-dist:jar:0.7.0-SNAPSHOT; it doesn't have an associated file or directory. + +... + +[WARNING] Don't override file /Users/aled/repos/apache/incubator-brooklyn/usage/archetypes/quickstart/target/test-classes/projects/integration-test-1/project/brooklyn-sample/src/main/resources/sample-icon.png + +... + +[INFO] Reactor Summary: +[INFO] +[INFO] Brooklyn Parent Project ........................... SUCCESS [3.072s] +[INFO] Brooklyn Utilities to Support Testing (listeners etc) SUCCESS [3.114s] +[INFO] Brooklyn Logback Includable Configuration ......... SUCCESS [0.680s] +[INFO] Brooklyn Common Utilities ......................... SUCCESS [7.263s] +[INFO] Brooklyn Groovy Utilities ......................... SUCCESS [5.193s] +[INFO] Brooklyn API ...................................... SUCCESS [2.146s] +[INFO] Brooklyn Test Support ............................. SUCCESS [2.517s] +[INFO] CAMP Server Parent Project ........................ SUCCESS [0.075s] +[INFO] CAMP Base ......................................... SUCCESS [4.079s] +[INFO] Brooklyn REST Swagger Apidoc Utilities ............ SUCCESS [1.983s] +[INFO] Brooklyn Logback Configuration .................... SUCCESS [0.625s] +[INFO] CAMP Server ....................................... SUCCESS [5.446s] +[INFO] Brooklyn Core ..................................... SUCCESS [1:24.122s] +[INFO] Brooklyn Policies ................................. SUCCESS [44.425s] +[INFO] Brooklyn Hazelcast Storage ........................ SUCCESS [7.143s] +[INFO] Brooklyn Jclouds Location Targets ................. SUCCESS [16.488s] +[INFO] Brooklyn Secure JMXMP Agent ....................... SUCCESS [8.634s] +[INFO] Brooklyn JMX RMI Agent ............................ SUCCESS [2.315s] +[INFO] Brooklyn Software Base ............................ SUCCESS [28.538s] +[INFO] Brooklyn Network Software Entities ................ SUCCESS [3.896s] +[INFO] Brooklyn OSGi Software Entities ................... SUCCESS [4.589s] +[INFO] Brooklyn Web App Software Entities ................ SUCCESS [17.484s] +[INFO] Brooklyn Messaging Software Entities .............. SUCCESS [7.106s] +[INFO] Brooklyn Database Software Entities ............... SUCCESS [5.229s] +[INFO] Brooklyn NoSQL Data Store Software Entities ....... SUCCESS [11.901s] +[INFO] Brooklyn Monitoring Software Entities ............. SUCCESS [4.027s] +[INFO] Brooklyn CAMP REST API ............................ SUCCESS [15.285s] +[INFO] Brooklyn REST API ................................. SUCCESS [4.489s] +[INFO] Brooklyn REST Server .............................. SUCCESS [30.270s] +[INFO] Brooklyn REST Client .............................. SUCCESS [7.007s] +[INFO] Brooklyn REST JavaScript Web GUI .................. SUCCESS [24.397s] +[INFO] Brooklyn Launcher ................................. SUCCESS [15.923s] +[INFO] Brooklyn Command Line Interface ................... SUCCESS [9.279s] +[INFO] Brooklyn All Things ............................... SUCCESS [13.875s] +[INFO] Brooklyn Distribution ............................. SUCCESS [49.370s] +[INFO] Brooklyn Quick-Start Project Archetype ............ SUCCESS [12.053s] +[INFO] Brooklyn Examples Aggregator Project .............. SUCCESS [0.085s] +[INFO] Brooklyn Examples Support Aggregator Project - Webapps SUCCESS [0.053s] +[INFO] hello-world-webapp Maven Webapp ................... SUCCESS [0.751s] +[INFO] hello-world-sql-webapp Maven Webapp ............... SUCCESS [0.623s] +[INFO] Brooklyn Simple Web Cluster Example ............... SUCCESS [5.398s] +[INFO] Brooklyn Global Web Fabric Example ................ SUCCESS [3.176s] +[INFO] Brooklyn Simple Messaging Publish-Subscribe Example SUCCESS [3.217s] +[INFO] Brooklyn NoSQL Cluster Examples ................... SUCCESS [6.790s] +[INFO] Brooklyn QA ....................................... SUCCESS [7.117s] +[INFO] ------------------------------------------------------------------------ +[INFO] BUILD SUCCESS +[INFO] ------------------------------------------------------------------------ +[INFO] Total time: 8:33.983s +[INFO] Finished at: Mon Jul 21 14:56:46 BST 2014 +[INFO] Final Memory: 66M/554M +[INFO] ------------------------------------------------------------------------ + +{% endhighlight %} http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/a7a317bf/docs/guide/dev/how-to-contrib.md ---------------------------------------------------------------------- diff --git a/docs/guide/dev/how-to-contrib.md b/docs/guide/dev/how-to-contrib.md deleted file mode 100644 index 120d3d9..0000000 --- a/docs/guide/dev/how-to-contrib.md +++ /dev/null @@ -1,38 +0,0 @@ ---- -layout: guide-normal -title: How to Contribute -toc: /guide/toc.json ---- - -### The Process - -If you've built something which you think others could use, or are interested in doing so -- -whether a new supported entity, or a policy, or an example -- -it's easy to give back to the community. Just: - -1. **Tell [the brooklyn mailing list](https://mail-archives.apache.org/mod_mbox/incubator-brooklyn-dev/)** about your work or interest - -1. **Create your fork** of the project on GitHub - -1. **Clone it** to your local machine and do your work on it - -1. **Push it**, and tell everyone about it - -1. **Sign the relevant Apache contributor agreement(s)** - -1. **Issue a pull request** from your GitHub repo - -The same process holds for contributing to this documentation (web site and user guide), -but see the additional [tips for updating documentation]({{ site.path.guide }}/dev/tips/update-docs.html). - - -### Some Words of Advice - -* Do early-stage work in the ``/sandbox``, which means we can pulled it in to ``master`` more often -- - keeping branches short-lived and making it easier to collaborate! - -* Include javadoc and tests - -* See the [tips here]({{site.path.guide}}/dev/tips/index.html) - -* If you get blocked, **[hollar]({{site.path.guide}}/meta/contact.html)**! http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/a7a317bf/docs/guide/dev/index.md ---------------------------------------------------------------------- diff --git a/docs/guide/dev/index.md b/docs/guide/dev/index.md index c6c9e33..31dd7e1 100644 --- a/docs/guide/dev/index.md +++ b/docs/guide/dev/index.md @@ -1,7 +1,30 @@ --- -layout: guide-normal -title: Getting to Code -toc: /guide/toc.json +title: Developer Guide +layout: website-normal +menu_parent: /website/documentation/ +breadcrumbs: +- /website/documentation/index.md +- /guide/dev/index.md +children: +- env/ +- code/ +- code/tests.md +- tips/ +- tips/logging.md +- tips/debugging-remote-brooklyn.md --- -{% readj code/index.include.md %} +The Developer Guide contains information on working with the Brooklyn codebase. + +Of particular note to people getting started, there is: + +* Help with Maven +* Help with Git +* Help setting up IDE's + +And for the Brooklyn codebase itself, see: + +* Project structure +* Areas of Special Hairiness + +(All links are TODO.) http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/a7a317bf/docs/guide/dev/links.md ---------------------------------------------------------------------- diff --git a/docs/guide/dev/links.md b/docs/guide/dev/links.md deleted file mode 100644 index 6fd12e2..0000000 --- a/docs/guide/dev/links.md +++ /dev/null @@ -1,22 +0,0 @@ ---- -layout: guide-normal -title: Development Bookmarks -toc: ../toc.json ---- - -{% include fields.md %} - -Handy places: - -* **Code** is in Github at [https://github.com/apache/incubator-brooklyn/](https://github.com/apache/incubator-brooklyn/) - -* **Issues** are in Jira at [https://issues.apache.org/jira/browse/BROOKLYN/](https://issues.apache.org/jira/browse/BROOKLYN/) - -* **Maven repositories** are: - * [Apache releases]({{ apache_releases_repo_groupid_url }}) - * [Apache snapshots]({{ apache_snapshots_repo_groupid_url }}) - * Other repositories are at [http://developers.cloudsoftcorp.com/download/maven2/](http://developers.cloudsoftcorp.com/download/maven2/) for releases - and [http://ccweb.cloudsoftcorp.com/maven/libs-snapshot-local/](http://ccweb.cloudsoftcorp.com/maven/libs-snapshot-local/) for snapshots - -* **CI server** is a jenkins server at: [https://builds.apache.org/job/incubator-brooklyn-master-build/](https://builds.apache.org/job/incubator-brooklyn-master-build/) - http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/a7a317bf/docs/guide/dev/tips/debugging-remote-brooklyn.md ---------------------------------------------------------------------- diff --git a/docs/guide/dev/tips/debugging-remote-brooklyn.md b/docs/guide/dev/tips/debugging-remote-brooklyn.md new file mode 100644 index 0000000..337aa21 --- /dev/null +++ b/docs/guide/dev/tips/debugging-remote-brooklyn.md @@ -0,0 +1,140 @@ +--- +layout: guide-normal +title: Brooklyn Remote Debugging +toc: /guide/toc.json +--- + +Usually during development, you will be running Brooklyn from your IDE (see [IDE Setup](ide.html)), in which case +debugging is as simple as setting a breakpoint. There may however be times when you need to debug an existing remote +Brooklyn instance (often referred to as Resident Brooklyn, or rBrooklyn) on another machine, usually in the cloud. + +Thankfully, the tools are available to do this, and setting it up is quite straightforward. The steps are as follows: + +* [Getting the right source code version](#sourceCodeVersion) +* [Starting Brooklyn with a debug listener](#startingBrooklyn) +* [Creating an SSH tunnel](#sshTunnel) +* [Connecting your IDE](#connectingIDE) + +## Getting the right source code version +The first step is to ensure that your local copy of the source code is at the version used to build the remote Brooklyn +instance. The git commit that was used to build Brooklyn is available via the REST API: + +``` +http://:/v1/server/version +``` + +This should return details of the build as a JSON string similar to the following (formatted for clarity): + +```JSON +{ + "version": "0.7.0-SNAPSHOT", + "buildSha1": "c0fdc15291702281acdebf1b11d431a6385f5224", + "buildBranch": "UNKNOWN" +} +``` + +The value that we're interested in is `buildSha1`. This is the git commit that was used to build Brooklyn. We can now +checkout and build the Brooklyn code at this commit by running the following in the root of your Brooklyn repo: + +``` +git checkout c0fdc15291702281acdebf1b11d431a6385f5224 +mvn clean install -DskipTests +``` + +Whilst building the code isn't strictly necessary, it can help prevent some IDE issues. + +## Starting Brooklyn with a debug listener +By default, Brooklyn does not listen for a debugger to be attached, however this behaviour can be set by setting JAVA_OPTS, +which will require a restart of the Brooklyn node. To do this, SSH to the remote Brooklyn node and run the following in the +root of the Brooklyn installation: + +``` +# NOTE: Running this kill command will lose existing apps and machines if persistence is disabled. +kill `cat pid_java` +export JAVA_OPTS="-Xms256m -Xmx1g -XX:MaxPermSize=256m -agentlib:jdwp=transport=dt_socket,address=127.0.0.1:8888,server=y,suspend=n" +bin/brooklyn launch & +``` + +If `JAVA_OPTS` is not set, Brooklyn will automatically set it to `"-Xms256m -Xmx1g -XX:MaxPermSize=256m"`, which is why +we have prepended the agentlib settings with these values here. + +You should see the following in the console output: + +``` +Listening for transport dt_socket at address: 8888 +``` + +This will indicate the Brooklyn is listening on port 8888 for a debugger to be attached. + +## Creating an SSH tunnel +If port 8888 is accessible on the remote Brooklyn server, then you can skip this step and simply use the address of the +server in place of 127.0.0.1 in the [Connecting your IDE](#connectingIDE) section below. It will normally be possible to +make the port accessible by configuring Security Groups, iptables, endpoints etc., but for a quick ad-hoc connection it's +usually simpler to create an SSH tunnel. This will create an open SSH connection that will redirect traffic from a port +on a local interface via SSH to a port on the remote machine. To create the tunnel, run the following on your local +machine: + +``` +# replace this with the address or IP of the remote Brooklyn node +REMOTE_HOST= +# if you wish to use a different port, this value must match the port specified in the JAVA_OPTS +REMOTE_PORT=8888 +# if you wish to use a different local port, this value must match the port specified in the IDE configuration +LOCAL_PORT=8888 +# set this to the login user you use to SSH to the remote Brooklyn node +SSH_USER=root +# The private key file used to SSH to the remote node. If you use a password, see the alternative command below +PRIVATE_KEY_FILE=~/.ssh/id_rsa + +ssh -YNf -i $PRIVATE_KEY_FILE -l $SSH_USER -L $LOCAL_PORT:127.0.0.1:$REMOTE_PORT $REMOTE_HOST + +``` + +If you use a password to SSH to the remote Brooklyn node, simply remove the `-i $PRIVATE_KEY_FILE` section like so: + +``` +ssh -YNf -l $SSH_USER -L $LOCAL_PORT:127.0.0.1:$REMOTE_PORT $REMOTE_HOST +``` + +If you are using a password to connect, you will be prompted to enter your password to connect to the remote node upon +running the SSH command. + +The SSH tunnel should now be redirecting traffic from port 8888 on the local 127.0.0.1 network interface via the SSH +tunnel to port 8888 on the remote 127.0.0.1 interface. It should now be possible to connect the debugger and start +debugging. + +## Connecting your IDE +Setting up your IDE will differ depending upon which IDE you are using. Instructions are given here for Eclipse and +IntelliJ, and have been tested with Eclipse Luna and IntelliJ Ultimate 14. + +### Eclipse Setup +To debug using Eclipse, first open the Brooklyn project in Eclipse (see [IDE Setup](ide.html)). + +Now create a debug configuration by clicking `Run` | `Debug Configurations...`. You will then be presented with the +Debug Configuration dialog. + +Select `Remote Java Application` from the list and click the 'New' button to create a new configuration. Set the name +to something suitable such as 'Remote debug on 8888'. The Project can be set to any of the Brooklyn projects, the +Connection Type should be set to 'Standard (Socket Attach)'. The Host should be set to either localhost or 127.0.0.1 +and the Port should be set to 8888. Click 'Debug' to start debugging. + +### IntelliJ Setup +To debug using IntelliJ, first open the Brooklyn project in IntelliJ (see [IDE Setup](ide.html)). + +Now create a debug configuration by clicking `Run` | `Edit Configurations`. You will then be presented with the +Run/Debug Configurations dialog. + +Click on the `+` button and select 'Remote' to create a new remote configuration. Set the name to something suitable +such as 'Remote debug on 8888'. The first three sections simply give the command line arguments for starting the java +process using different versions of java, however we have already done this in +[Starting Brooklyn with a debug listener](#startingBrooklyn). The Transport option should be set to 'Socket', the Debugger Mode should be set to 'Attach', the +Host should be set to localhost or 127.0.0.1 (or the address of the remote machine if you are not using an SSH tunnel), +and the Port should be set to 8888. The 'Search sources' section should be set to ``. Click OK to save the +configuration, then select the configuration from the configurations drop-down and click the debug button to start +debugging. + +### Testing +The easiest way to test that remote debugging has been setup correctly is to set a breakpoint and see if it is hit. An +easy place to start is to create a breakpoint in the `ServerResource.java` class, in the `getStatus()` +method. + http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/a7a317bf/docs/guide/dev/tips/index.md ---------------------------------------------------------------------- diff --git a/docs/guide/dev/tips/index.md b/docs/guide/dev/tips/index.md index e809b7d..9045fe9 100644 --- a/docs/guide/dev/tips/index.md +++ b/docs/guide/dev/tips/index.md @@ -1,7 +1,6 @@ --- layout: guide-normal title: Miscellaneous Tips and Tricks -toc: /guide/toc.json --- ## General Good Ways of Working http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/a7a317bf/docs/guide/dev/tips/local-artifact-repo.md ---------------------------------------------------------------------- diff --git a/docs/guide/dev/tips/local-artifact-repo.md b/docs/guide/dev/tips/local-artifact-repo.md deleted file mode 100644 index 455a545..0000000 --- a/docs/guide/dev/tips/local-artifact-repo.md +++ /dev/null @@ -1,32 +0,0 @@ ---- -layout: guide-normal -title: Prepopulating a Local Artifact Repository -toc: /guide/toc.json ---- - -On occasion it can be useful to have/control/prepopulate a local repository of entity installers [1]. - -The following command (run from `~/`) may be used to sync Cloudsoft's fallback repository to the local `~/.brooklyn/repository/` folder: - - wget --directory-prefix=".brooklyn/repository/" --no-parent --relative --no-host-directories --reject="index.html*" --cut-dirs=2 --recursive -e robots=off --user-agent="Brooklyn Repository Sync" http://downloads.cloudsoftcorp.com/brooklyn/repository/ - -Brooklyn's default search behaviour for installation artifacts is as follows: - -1. The local `~/.brooklyn/repository/` folder. -2. The entity's installer's public download url (or an overridden url if one has been specified). -3. Cloudsoft's fallback repository. - -Cloudsoft's fallback repository [2] contains many of the installation artifacts used by current Brooklyn entities. - -It is intended to prevent problems occurring when the public url for an installer changes (e.g. when several new versions of MySQL have been released). It is provided on an as-is and as-available basis. - -If you use this command to create a local repository, please respect the `--user-agent`. In future this will allow Cloudsoft to easily filter repository syncing behaviour from fallback behaviour, allowing out-of-date entities to be more easily identified and updated. - -
- -
    -
  1. For example, when establishing a local cache or enterprise golden source, or when developing Brooklyn while offline, in planes, trains and automobiles, or other such situations of exemplary derring-do [3].
    2. -
  2. downloads.cloudsoftcorp.com/brooklyn/repository
    3. -
  3. This one time, Cloudsoft ran a team hackathon in a castle in the remote Highlands of Scotland. Remote Highlands != reliable big pipe internet.
    4. -
- http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/a7a317bf/docs/guide/dev/tips/logging.md ---------------------------------------------------------------------- diff --git a/docs/guide/dev/tips/logging.md b/docs/guide/dev/tips/logging.md index e9e3ffc..7c4543c 100644 --- a/docs/guide/dev/tips/logging.md +++ b/docs/guide/dev/tips/logging.md @@ -1,7 +1,6 @@ --- -layout: guide-normal title: Logging -toc: /guide/toc.json +layout: website-normal --- ## Logging: A Quick Overview @@ -66,6 +65,10 @@ For example: configuration file, except it should be wrapped in ```` XML tags rather than ```` XML tags (because it is included from the ``logback.xml`` which comes with ``brooklyn-logback-xml``.) +* To redirect all jclouds logging to a separate file include ``brooklyn/logback-logger-debug-jclouds.xml``. + This redirects all logging from ``org.jclouds`` and ``jclouds`` to one of two files: anything + logged from Brooklyn's persistence thread will end up in a `persistence.log`, everything else + will end up in ``jclouds.log``. You should **not** supply your own ``logback.xml`` if you are using ``brooklyn-logback-xml``. If you do, logback will detect multiple files with that name and will scream at you.