brooklyn-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From henev...@apache.org
Subject [07/50] brooklyn-docs git commit: updated docs to use archetype
Date Mon, 01 Feb 2016 17:44:07 GMT
updated docs to use archetype


Project: http://git-wip-us.apache.org/repos/asf/brooklyn-docs/repo
Commit: http://git-wip-us.apache.org/repos/asf/brooklyn-docs/commit/c75cadba
Tree: http://git-wip-us.apache.org/repos/asf/brooklyn-docs/tree/c75cadba
Diff: http://git-wip-us.apache.org/repos/asf/brooklyn-docs/diff/c75cadba

Branch: refs/heads/0.6.0
Commit: c75cadbac3037bb29da874caf234f1033a1a318d
Parents: 84cb713
Author: Alex Heneveld <alex.heneveld@cloudsoftcorp.com>
Authored: Wed Sep 25 23:23:56 2013 +0100
Committer: Alex Heneveld <alex.heneveld@cloudsoftcorp.com>
Committed: Wed Sep 25 23:23:56 2013 +0100

----------------------------------------------------------------------
 docs/dev/build/eclipse.include.md | 15 ++++---
 docs/dev/build/ide.md             | 76 ++++++++++++++--------------------
 docs/dev/code/index.include.md    | 23 +++++++++-
 docs/start/walkthrough/index.md   | 63 +++++++++++++++++++---------
 4 files changed, 106 insertions(+), 71 deletions(-)
----------------------------------------------------------------------


http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/c75cadba/docs/dev/build/eclipse.include.md
----------------------------------------------------------------------
diff --git a/docs/dev/build/eclipse.include.md b/docs/dev/build/eclipse.include.md
index 700f975..298d948 100644
--- a/docs/dev/build/eclipse.include.md
+++ b/docs/dev/build/eclipse.include.md
@@ -1,12 +1,15 @@
 
 - Maven Plugin: m2e from [download.eclipse.org/technology/m2e/releases](http://download.eclipse.org/technology/m2e/releases)
-  (typically availabile in the default Eclipse update site set)
+  (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 availabile in the default Eclipse update site set)
-
-- Groovy Plugin: GRECLIPSE from [dist.springsource.org/release/GRECLIPSE/e4.2](http://dist.springsource.org/release/GRECLIPSE/e4.2)

-  (or [for Eclipse 3.7](http://dist.springsource.org/release/GRECLIPSE/e3.7))
-  You can even visit the [groovy update site](http://groovy.codehaus.org/Eclipse+Plugin)
for more details.
+  (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/brooklyn-docs/blob/c75cadba/docs/dev/build/ide.md
----------------------------------------------------------------------
diff --git a/docs/dev/build/ide.md b/docs/dev/build/ide.md
index a51e71c..dabc400 100644
--- a/docs/dev/build/ide.md
+++ b/docs/dev/build/ide.md
@@ -11,57 +11,57 @@ 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.
 
-Here are some general tips:
-
-* Add your favourite plugins for Maven, Groovy, Git and JavaScript, if necessary
-
-* Turn off auto-rebuild if it bothers you
-
-* 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 (optionally regenerate dependencies).
-  Sometimes closing projects (so that it reads from your ``~/.m2/repository``) helps.
+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 Groovy, Maven (m2e), Git, JavaScript
and TestNG plugins. 
-Via Help -> Install New Software, or from the Eclipse Marketplace,
-we recommend:
+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, with Eclipse 4.2, m2e 1.1, and GrEclipse 2.7, 
-the codebase has been imported (Import -> Existing Maven Projects) 
-and successfully run with no errors.
-However this isn't always the case.
+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 quicks, and mileage may vary.
 
 If you encounter issues, the following hints may be helpful:
 
-* 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).
-
-* m2e likes to put ``excluding="**"`` on `resources`` directories; if you're seeing funny
missing files
+* 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).
+  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:
+  the following command to remove these rogue blocks in the generated `.classpath` files:
 
-  ``find . -name .classpath -exec sed -i.bak 's/[ ]*..cluding="[\*\/]*\(\.java\)*"//g' {}
\;``
+{% highlight bash %}
+% find . -name .classpath -exec sed -i.bak 's/[ ]*..cluding="[\*\/]*\(\.java\)*"//g' {} \;
+{% endhighlight %}
 
-* Getting the web console project to build nicely can be trickier. 
+* 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):
 
-  ``find . \( -path "*/src/main" -or -path "*/src/test" \) -exec echo {} \; -exec mkdir -p
{}/{java,resources} \;``
+{% 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, 
@@ -70,19 +70,6 @@ If you encounter issues, the following hints may be helpful:
   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. 
 
- <!-- 
- FIXME Relates to old Grails, rather than new JavaScript web-console.
- Should we just delete this section, or does any of it apply to the new web-console?
- 
-* Getting the web console project to build nicely can be trickier. 
-  If you're lucky it will just work...
-  But you may find you have to first build from the command-line, 
-  then add all the source folders, and ``target/plugin-classes`` as a class file folder.
-  Easier may be just to run "grails run-app" in the directory to launch it (plus that does
dynamic restarts),
-  and use the IDE as just a text editor (or use a different text editor for that project
only).
-  Note too that some jiggery-pokery may currently be needed to get Groovy 1.8 playing nicely
with Grails 1.3.
- -->
- 
 If the pain starts to be too much, come find us on IRC #brooklyncentral or [elsewhere]({{site.url}}/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!)
 
@@ -90,7 +77,8 @@ If the pain starts to be too much, come find us on IRC #brooklyncentral
or [else
 
 ## Intelli-J IDEA
 
-Tips from Intelli-J users wanted!
+Many of our contributers prefer Intelli-J.  However none of them have yet volunteered any
set-up tips.
+[Be the first!]({{site.url}}/dev/tips/update-docs.html)
 
 
 

http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/c75cadba/docs/dev/code/index.include.md
----------------------------------------------------------------------
diff --git a/docs/dev/code/index.include.md b/docs/dev/code/index.include.md
index 62302f8..5655a40 100644
--- a/docs/dev/code/index.include.md
+++ b/docs/dev/code/index.include.md
@@ -4,11 +4,30 @@ Brooklyn is available at [GitHub brooklyncentral/brooklyn](http://github.com/bro
 
 {% highlight bash %}
 git clone git@github.com:brooklyncentral/brooklyn.git
+cd brooklyn
 {% endhighlight %}
 
-You'll find versions in branches, and examples in the **examples** sub-dir.
-These examples are pushed to the [brooklyn-examples](http://github.com/brooklyncentral/brooklyn-examples)
GitHub project when a version is released.
+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.url}}/use/examples),
+and pushed to the [brooklyn-examples](http://github.com/brooklyncentral/brooklyn-examples)

+GitHub project when a version is released.
+
+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.url}}/use/guide/quickstart/index.html).
+This document is intended to help people become familiar with the codebase.
 
 ## Project Structure
 

http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/c75cadba/docs/start/walkthrough/index.md
----------------------------------------------------------------------
diff --git a/docs/start/walkthrough/index.md b/docs/start/walkthrough/index.md
index 6623cb9..3b4d819 100644
--- a/docs/start/walkthrough/index.md
+++ b/docs/start/walkthrough/index.md
@@ -3,6 +3,7 @@ layout: page
 title: Walkthrough
 toc: /toc.json
 ---
+{% include fields.md %}
 
 ## Intro
 
@@ -15,11 +16,30 @@ composed of:
 * a cluster of JBoss appservers
 * a MySQL database
 
-Here's the essential code which creates these and sets them up
-for management:
+A sample project can be created using the Brooklyn maven quickstart archetype:
+
+{% highlight bash %}
+export BROOKLYN_VERSION=0.6.0-SNAPSHOT
+mvn archetype:generate \
+    -DarchetypeGroupId=io.brooklyn -DarchetypeArtifactId=brooklyn-archetype-quickstart -DarchetypeVersion=${BROOKLYN_VERSION}
\
+    -DgroupId=com.acme.sample -DartifactId=brooklyn-sample -Dversion=0.1.0-SNAPSHOT -Dpackage=com.acme.sample.brooklyn
+cd brooklyn-sample
+{% endhighlight %}
+
+{% if SNAPSHOT %}
+For a snapshot version, you must either have a local `mvn install` of Brooklyn as described

+[here]({{site.url}}/dev/code/index.html) or include the following additional `-D` define
in 
+in the `mvn archetype:generate` command:
+
+{% highlight bash %}
+    -DarchetypeCatalog=https://oss.sonatype.org/content/repositories/snapshots/archetype-catalog.xml
+{% endhighlight %}
+{% endif %}
+
+An application blueprint can then be defined as a class as follows:
 
 {% highlight java %}
-public class WebClusterDatabaseExample extends AbstractApplication {
+public class ClusterWebServerDatabaseSample extends AbstractApplication {
     @Override
     public void init() {
         MySqlNode mysql = addChild(EntitySpec.create(MySqlNode.class));
@@ -29,18 +49,22 @@ public class WebClusterDatabaseExample extends AbstractApplication {
 {% endhighlight %}
 
 
-## Runtime: the Web Console
+## Runtime
 
-Build and run this Brooklyn "Application", specifying a target location, and our application
is deployed.
+To launch this application, simply build the project and run the `start.sh` script
+in the resulting assembly:
 
 {% highlight bash %}
-export BROOKLYN_CLASSPATH=/path/to/your/project/target/classes
-brooklyn launch --app brooklyn.demo.WebClusterDatabaseExample --location jclouds:aws-ec2:eu-west-1
+mvn clean assembly:assembly
+cd target/brooklyn-sample-0.1.0-SNAPSHOT-dist/brooklyn-sample-0.1.0-SNAPSHOT/
+./start.sh application --class com.acme.sample.brooklyn.ClusterWebServerDatabaseSample \
+    --location jclouds:aws-ec2:eu-west-1
 {% endhighlight %}
 
-Amazon is used in these screenshots, but lots of targets are supported (using [jclouds](http://jclouds.org))
-including fixed IP addresses and private clouds, 
-or just localhost (very handy for dev/test, and with port conflicts resolved automatically!).
+Amazon is used in these screenshots, but lots of targets are supported,
+including `--location localhost`, fixed IP addresses, and 
+everything supported by [jclouds](http://jclouds.org), from OpenStack to Google Compute.
+**It is necessary to set up credentials and/or access, as described [here]({{ site.url }}/use/guide/defining-applications/common-usage#locations).**
 
 [![Web Console](walkthrough-webconsole-map-w700.png "Web Console")](walkthrough-webconsole-map.png)

 
@@ -53,7 +77,7 @@ and exposes operations ("effectors") that can be performed on entities.
 [![Web Console Details](walkthrough-webconsole-details-w700.png "Web Console Details")](walkthrough-webconsole-details.png)

 
 
-## Some Configuration and Management
+## Topology, Dependencies, and Management Policies
 
 Of course in the real world, application deployments are more interesting;
 they do things and need configuration.  For instance you might need to:
@@ -76,7 +100,7 @@ block "at the last moment" when the value is needed
 (but after e.g. the VMs have been provisioned, to speed things up).
 
 {% highlight java %}
-public class WebClusterDatabaseExample extends AbstractApplication {
+public class ClusterWebServerDatabaseSample extends AbstractApplication {
     @Override
     public void init() {
         MySqlNode mysql = addChild(EntitySpec.create(MySqlNode.class)
@@ -86,7 +110,7 @@ public class WebClusterDatabaseExample extends AbstractApplication {
                 .configure("memberSpec", EntitySpec.create(JBoss7Server.class)
                         .configure("httpPort", "8080+")
                         .configure("war", WAR_PATH)
-                        .configure(javaSysProp("brooklyn.example.db.url"), 
+                        .configure(JavaEntityMethods.javaSysProp("brooklyn.example.db.url"),

                                 formatString("jdbc:%s%s?user=%s\\&password=%s", 
                                         attributeWhenReady(mysql, MySqlNode.MYSQL_URL), DB_TABLE,
DB_USERNAME, DB_PASSWORD))));
     }
@@ -125,15 +149,16 @@ A separate policy operates at the ``Controlled`` cluster to ensure the
 load-balancer is updated as the pool of web servers expands and contracts.
 
 Fire up a JMeter session and blast the Nginx address.
-The resizer policy scales up our cluster:
+The auto-scaler policy scales up our cluster:
 
-[![Web Cluster Scaling with the Resizer Policy](walkthrough-webconsole-scaling-w700.png "Screenshot
of Web Cluster Scaling with the Resizer Policy")](walkthrough-webconsole-scaling.png) 
+[![Web Cluster Scaling with the Auto-Scaler Policy](walkthrough-webconsole-scaling-w700.png
"Screenshot of Web Cluster Scaling with the Resizer Policy")](walkthrough-webconsole-scaling.png)

 
 
-## Run it Yourself
+## What Next?
  
-All the code for this walkthrough (and even the JMeter script) is included with
-Brooklyn as the ``simple-web-cluster`` example,
+In addition to the sample project created by the archetype, with its README and
+`assembly` build, you can find additional code related to this example
+(and even the JMeter script) included with Brooklyn as the ``simple-web-cluster`` example,
 described [in detail here]({{site.url}}/use/examples/webcluster).
 
 For your applications, you might want to mix in other data stores, messaging systems, or
on-line services including PaaS.
@@ -184,4 +209,4 @@ If you want to adventure beyond ``localhost`` (the default),
 simply supply the your favourite cloud (e.g. ``aws-ec2:eu-west-1``)
 with credentials set up as described [here]({{ site.url }}/use/guide/management/index.html#startup-config).
 
--->
\ No newline at end of file
+-->


Mime
View raw message