Author: buildbot
Date: Mon Jun 20 21:18:53 2016
New Revision: 991062
Log:
Staging update by buildbot for ace
Modified:
websites/staging/ace/trunk/content/ (props changed)
websites/staging/ace/trunk/content/docs/setup-dev-environment.html
Propchange: websites/staging/ace/trunk/content/
------------------------------------------------------------------------------
--- cms:source-revision (original)
+++ cms:source-revision Mon Jun 20 21:18:53 2016
@@ -1 +1 @@
-1744545
+1749405
Modified: websites/staging/ace/trunk/content/docs/setup-dev-environment.html
==============================================================================
--- websites/staging/ace/trunk/content/docs/setup-dev-environment.html
(original)
+++ websites/staging/ace/trunk/content/docs/setup-dev-environment.html Mon Jun
20 21:18:53 2016
@@ -101,53 +101,70 @@
<p><a href="/"><i class='icon-home'></i> Home</a> » <a
href="/docs/">Docs</a></p>
<h1>Setting up a development environment</h1>
<div class="clear"></div>
- <div id="content"><p>Everything you need to know to start developing
Apache ACE can be found here.</p>
-<h2 id="obtaining-the-sources">Obtaining the sources</h2>
+ <div id="content"><style type="text/css">
+/* The following code is added by mdx_elementid.py
+ It was originally lifted from http://subversion.apache.org/style/site.css */
+/*
+ * Hide class="elementid-permalink", except when an enclosing heading
+ * has the :hover property.
+ */
+.headerlink, .elementid-permalink {
+ visibility: hidden;
+}
+h2:hover > .headerlink, h3:hover > .headerlink, h1:hover > .headerlink,
h6:hover > .headerlink, h4:hover > .headerlink, h5:hover > .headerlink,
dt:hover > .elementid-permalink { visibility: visible }</style>
+<p>Everything you need to know to start developing Apache ACE can be found
here.</p>
+<h2 id="obtaining-the-sources">Obtaining the sources<a class="headerlink"
href="#obtaining-the-sources" title="Permanent link">¶</a></h2>
<p>There are two ways to obtain a copy of the source code. You can either
download one of the
source releases, or checkout the code from subversion.</p>
-<h3 id="download-the-sources">Download the sources</h3>
-<p>Point your browser to: http://ace.apache.org/download.html</p>
+<h3 id="download-the-sources">Download the sources<a class="headerlink"
href="#download-the-sources" title="Permanent link">¶</a></h3>
+<p>Point your browser to the <a
href="http://ace.apache.org/downloads.html";>ACE download page</a>.</p>
<p>On that page you will find, amongst others, a link to the latest released
sources, plus an
archive containing all binary third-party dependencies. The page will
automatically select
-a download mirror close to you. Download both the source and dependencies
archive and then
+a download mirror close to you. Download <em>both</em> the source and
dependencies archive and then
type:</p>
-<div class="codehilite"><pre><span class="nv">$ </span>unzip
apache-ace-1.0.0-src.zip
-<span class="nv">$ </span>unzip apache-ace-1.0.0-deps.zip
+<div class="codehilite"><pre><span class="nv">$ </span>unzip
apache-ace-2.1.0-src.zip
+<span class="nv">$ </span>unzip apache-ace-2.1.0-deps.zip
</pre></div>
<p>Note that when unzipping the second archive, you will get some warnings
about overlapping
files. Those are the required NOTICE and LICENSE files, which are in the same
location in
-both archives. Just overwriting them is fine.</p>
-<h3 id="checkout-from-subversion">Checkout from subversion</h3>
+both archives. It is fine to overwriting theses files.</p>
+<h3 id="checkout-from-subversion">Checkout from subversion<a
class="headerlink" href="#checkout-from-subversion" title="Permanent
link">¶</a></h3>
+<p>Alternatively, you can check out the sources directly from the main Apache
source repositories:</p>
<div class="codehilite"><pre><span class="nv">$ </span>svn co
http://svn.apache.org/repos/asf/ace/trunk apache-ace
</pre></div>
+<p>or</p>
+<div class="codehilite"><pre><span class="nv">$ </span>git clone
git://git.apache.org/ace apache-ace
+</pre></div>
+
+
<p>In both cases you end up with a copy of the source code.</p>
-<h2 id="building-the-sources">Building the sources</h2>
+<h2 id="building-the-sources">Building the sources<a class="headerlink"
href="#building-the-sources" title="Permanent link">¶</a></h2>
<p>There are two ways to build the sources. You can either run a command line
build or use
-Eclipse with Bndtools to build everything. If you want to actively start
developing, we
-strongly recommend you use Eclipse with Bndtools as this is by far the most
convenient way
-to build and run Apache ACE within a development environment.</p>
-<h3 id="eclipse-with-bndtools">Eclipse with Bndtools</h3>
-<h4 id="prerequisites">Prerequisites</h4>
+Eclipse with the <a href="http://bndtools.org/";>Bndtools plugin</a> to build
everything. If you want to
+actively start developing, we strongly recommend you use Eclipse with Bndtools
as this is
+by far the most convenient way to build and run Apache ACE.</p>
+<h3 id="eclipse-with-bndtools">Eclipse with Bndtools<a class="headerlink"
href="#eclipse-with-bndtools" title="Permanent link">¶</a></h3>
+<h4 id="prerequisites">Prerequisites<a class="headerlink"
href="#prerequisites" title="Permanent link">¶</a></h4>
<p>For developing ACE using Eclipse, you need:</p>
<ul>
-<li>A recent Java JDK, at least <a
href="http://www.oracle.com/technetwork/indexes/downloads/index.html";>Java
6</a>;</li>
-<li>A recent Eclipse, for example, <a
href="http://www.eclipse.org/downloads/";>Eclipse Juno</a> with the following
plugins:</li>
+<li>A recent Java JDK, at least <a
href="http://www.oracle.com/technetwork/indexes/downloads/index.html";>Java
8</a>;</li>
+<li>A recent Eclipse, for example, <a
href="http://www.eclipse.org/downloads/";>Eclipse Mars</a> with the following
plugins:</li>
<li><a
href="http://subclipse.tigris.org/servlets/ProjectProcess?pageID=p4wYuA";>Subclipse</a>;</li>
<li><a href="http://bndtools.org/installation.html";>BndTools</a>;</li>
<li><a href="http://testng.org/doc/download.html";>TestNG</a>.</li>
</ul>
-<p>For building or exporting the compiled artifacts of ACE without Eclipse,
you only need
-<a href="http://ant.apache.org/";>Apache ANT</a> version 1.8+ installed.</p>
-<h4 id="eclipse-set-up">Eclipse set up</h4>
+<p>For building or exporting the compiled artifacts of ACE without Eclipse,
you can use the
+Gradle wrapper script that is available in the source repository.</p>
+<h4 id="eclipse-set-up">Eclipse set up<a class="headerlink"
href="#eclipse-set-up" title="Permanent link">¶</a></h4>
<p>When firing up Eclipse, make sure to either create a new workspace and
check out the
sources according to the instructions below, or choose the root folder where
you have
-previously checked out or extracted your copy of the sources. This is
important, as
-otherwise Bndtools will not function correctly.</p>
-<h5 id="checking-out-the-latest-sources">Checking out the latest sources</h5>
+previously checked out or extracted your sources. This is important, as
otherwise
+Bndtools will not function correctly.</p>
+<h5 id="checking-out-the-latest-sources">Checking out the latest sources<a
class="headerlink" href="#checking-out-the-latest-sources" title="Permanent
link">¶</a></h5>
<p>If you created a new workspace above, you need to grab the latest sources
from ACE's
subversion repository. To do this, open up the "SVN Repository Exploring"
perspective, and
add the following URL as new SVN repository using the yellow add-icon in the
"SVN
@@ -157,114 +174,104 @@ Repositories" view:</p>
<p>After this, expand the newly created tree node named after the SVN URL, and
select all
-<strong>individual</strong> projects underneath. <em>Note: do
<strong>not</strong> (only) select the root node, as
-this won't let you properly import the individual projects.</em></p>
+<strong>individual</strong> projects underneath. <em>Note: do
<strong>not</strong> (only) select the root node or the
+files that reside underneath the root node, as this won't let you properly
import the
+individual projects.</em></p>
<p>Right click on the selected (sub)projects, and choose "Checkoutâ¦" from
the context menu.
Leave all default settings as-is and click "finish". Now relax and wait until
the checkout
is completed, and all projects are imported into your workspace.</p>
<p>Switching back to the "Bndtools" perspective should give you a long list of
imported
projects.</p>
-<h5 id="importing-existing-projects">Importing existing projects</h5>
+<h5 id="importing-existing-projects">Importing existing projects<a
class="headerlink" href="#importing-existing-projects" title="Permanent
link">¶</a></h5>
<p>If you created a workspace in a folder that already contained the sources,
you need to
import these projects into the workspace. From the main menu in Eclipse,
choose: "File
-> Import..." and then select "General -> Existing projects into
workspace..." and
select your workspace folder. A list of projects should show up now. Import
them all, wait
until Eclipse has built the project and you're ready to start.</p>
-<h5 id="coding-guidelines">Coding guidelines</h5>
+<h5 id="coding-guidelines">Coding guidelines<a class="headerlink"
href="#coding-guidelines" title="Permanent link">¶</a></h5>
<p>If you want to develop for ACE, you might want to import the code templates
and formatter
rules for ACE. The formatter can be found in the <code>etc</code> folder in
subversion, and you can
import it into Eclipse as your default formatter for this workspace.</p>
-<h4 id="running-debugging">Running & debugging</h4>
+<h4 id="running-debugging">Running & debugging<a class="headerlink"
href="#running-debugging" title="Permanent link">¶</a></h4>
<p>One of the benefits of the migration to BndTools is that we can now
directly run ACE from
Eclipse with almost zero effort. In fact, it is even possible to directly
debug or profile
ACE from Eclipse. By convention, all runnable projects start with "run-" and
contain a
-".bndrun" file.</p>
-<h5 id="ace-server">ACE server</h5>
-<p>To run or debug the ACE server, you open up the "<tt>server.bndrun</tt>"
file in the
-"run-server" project. This will present you with a view in which you can
directly choose
-to run it (use "Run OSGi") or debug it (use "Debug OSGi"). Alternatively, you
can right
-click on "server.bndrun" and choose either "Run As -> Bnd OSGi Run
Launcher" or "Debug
-As -> Bnd OSGi Run Launcher".</p>
-<h5 id="ace-obr">ACE obr</h5>
-<p>To run or debug the ACE obr, you open up the "<tt>obr.bndrun</tt>" file in
the "run-obr"
-project. This will present you with a view in which you can directly choose to
run it (use
-"Run OSGi") or debug it (use "Debug OSGi"). Alternatively, you can right click
on
-"obr.bndrun" and choose either "Run As -> Bnd OSGi Run Launcher" or "Debug
As -> Bnd
-OSGi Run Launcher".</p>
-<h5 id="ace-client">ACE client</h5>
-<p>To run or debug the ACE client, you open up the "<tt>client.bndrun</tt>"
file in the
-"run-client" project. This will present you with a view in which you can
directly choose
-to run it (use "Run OSGi") or debug it (use "Debug OSGi"). Alternatively, you
can right
-click on "client.bndrun" and choose either "Run As -> Bnd OSGi Run
Launcher" or "Debug
-As -> Bnd OSGi Run Launcher".</p>
-<h5 id="ace-server-allinone">ACE server-allinone</h5>
-<p>To run or debug the "all in one" ACE server, you open up the
-"<tt>server-allinone.bndrun</tt>" file in the "run-server-allinone" project.
This will
-present you with a view in which you can directly choose to run it (use "Run
OSGi") or
-debug it (use "Debug OSGi"). Alternatively, you can right click on
-"server-allinone.bndrun" and choose either "Run As -> Bnd OSGi Run
Launcher" or "Debug
-As -> Bnd OSGi Run Launcher".</p>
-<h5 id="ace-target">ACE target</h5>
-<p>You can also directly run a target from Eclipse. Doing this is almost equal
as running the
-ones described in the previous sections. The only difference is that for
running a target,
-you need to use the "<tt>target.bndrun</tt>" file from the "run-target"
project.</p>
-<h5 id="unit-tests">Unit tests</h5>
+".bndrun" file.<br />
+To start a project, right-click the "bndrun" file and select "Run As" ->
"Bnd OSGi Run
+Launcher" or "Debug As" -> "Bnd OSGi Run Launcher".</p>
+<p>There are several projects that can be run which we outline in the next
sections.</p>
+<h5 id="ace-target">ACE target<a class="headerlink" href="#ace-target"
title="Permanent link">¶</a></h5>
+<p>This project allows you to directly start an ACE target that receives
software from the ACE
+server. By default, the target is started with a Gogo shell to allow you to
interact with it.</p>
+<p>To run or debug the ACE server, use the "<tt>target.bndrun</tt>" file in the
+"run-target" project. </p>
+<h5 id="ace-server">ACE server<a class="headerlink" href="#ace-server"
title="Permanent link">¶</a></h5>
+<p>This project allows you to start a plain ACE server <em>without</em> an OBR
and (web)client.
+Its endpoints can be reached on port <tt>8080</tt>. The server expects an OBR
to be
+available at the same host on port <tt>8082</tt>.</p>
+<p>To run or debug the ACE server, use the "<tt>server.bndrun</tt>" file in the
+"run-server" project. </p>
+<h5 id="ace-obr">ACE OBR<a class="headerlink" href="#ace-obr" title="Permanent
link">¶</a></h5>
+<p>This will start an OBR for your artifacts. By default, its endpoints can be
reached through
+port <tt>8082</tt>. </p>
+<p>To run or debug the ACE OBR, use the "<tt>obr.bndrun</tt>" file in the
"run-obr"
+project.</p>
+<h5 id="ace-client">ACE client<a class="headerlink" href="#ace-client"
title="Permanent link">¶</a></h5>
+<p>This project allows you to start the web-based client. The web UI can be
reached by opening
+<a href="http://localhost:8081/";>localhost:8081/</a> in your browser. The ACE
client expects a (plain) ACE
+server to be available on the same host through port <tt>8080</tt> and an ACE
OBR to be
+available on the same on port <tt>8082</tt>.</p>
+<p>To run or debug the ACE client, use the "<tt>client.bndrun</tt>" file in the
+"run-client" project.</p>
+<h5 id="ace-server-allinone">ACE server-allinone<a class="headerlink"
href="#ace-server-allinone" title="Permanent link">¶</a></h5>
+<p>In case you just want to start everything in one go, you can use the
"all-in-one" server. This
+starts the ACE server, OBR and web-based client and allows you to reach all
endpoints through
+port <tt>8080</tt>.</p>
+<p>To run or debug the "all in one" ACE server, use the
+"<tt>server-allinone.bndrun</tt>" file in the "run-server-allinone"
project.</p>
+<h5 id="unit-tests">Unit tests<a class="headerlink" href="#unit-tests"
title="Permanent link">¶</a></h5>
<p>ACE uses TestNG for its unit tests. To run a single test or a package of
tests, use "Run
As -> TestNG Test" or "Debug As -> TestNG Test". </p>
-<h5 id="integration-tests">Integration tests</h5>
-<p>The integration tests of ACE are placed in separate projects that are -by
convention-
+<h5 id="integration-tests">Integration tests<a class="headerlink"
href="#integration-tests" title="Permanent link">¶</a></h5>
+<p>The integration tests of ACE are placed in separate projects that are, by
convention,
named with a '<tt>.itest</tt>' suffix. These integration tests use BndTools to
get an OSGi
-framework up and running. To run one or all integration tests, use "Run As
-> OSGi
-JUnit Test" or "Debug As -> OSGi JUnit Test".</p>
-<h3 id="command-line-build">Command line build</h3>
-<h4 id="prerequisites_1">Prerequisites</h4>
-<p>For developing ACE using Ant, you need:</p>
-<ul>
-<li>A recent Java JDK, at least <a
href="http://www.oracle.com/technetwork/indexes/downloads/index.html";>Java
6</a>;</li>
-<li><a href="http://ant.apache.org/";>Apache ANT</a> version 1.8+.</li>
-</ul>
-<h4 id="building">Building</h4>
-<p>The command line build for Apache ACE is based on Ant, and generated
automatically when
-using the Bndtools plugin in Eclipse.</p>
+framework up and running. To run one or all integration tests, use "Run As
-> Bnd OSGi
+Test Launcher (JUnit)" or "Debug As -> Bnd OSGi Test Launcher (JUnit)".</p>
+<h3 id="command-line-build">Command line build<a class="headerlink"
href="#command-line-build" title="Permanent link">¶</a></h3>
+<p>The command line build for Apache ACE is based on <a
href="http://gradle.org/";>Gradle</a>.</p>
<p>The build is structured as a flat hierarchy of projects, and you can go
into any of these
projects to build just that project and its dependencies. There are two
special projects:</p>
<ol>
-<li><code>cnf</code> -- Which is collection of repositories that contain all
the required dependencies
-for building and running Apache ACE;</li>
-<li><code>build</code> -- A project that depends on all other projects and is
used to build
-everything.</li>
+<li><code>cnf</code> -- Which is collection of repositories that contain all
the required dependencies for building and running Apache ACE;</li>
+<li><code>build</code> -- A project that contains the necessary scripts and
tools to do source and binary releases.</li>
</ol>
-<p>So, to build Apache ACE, we issue the following commands:</p>
-<div class="codehilite"><pre><span class="nv">$ </span><span class="nb">cd
</span>build
-<span class="nv">$ </span>ant
+<p>So, to build Apache ACE, we issue the following command:</p>
+<div class="codehilite"><pre><span class="nv">$ </span>./gradlew build
</pre></div>
-<p>In the end, this leaves us with a set of bundles (in the <tt>generated</tt>
folder of each
-project).</p>
+<p>This will build everything, and run all unit and integration tests. In the
end, this leaves us with
+a set of bundles (in the <tt>generated</tt> folder of each individual
project).</p>
<p>The following targets are available:</p>
<ul>
<li><tt>clean</tt> -- Cleans up any files in the current project that were
generated during a build;</li>
<li><tt>build</tt> -- Build the current project;</li>
-<li><tt>test</tt> -- Run the integration tests in the <em>current</em>
project;</li>
-<li><tt>testng</tt> -- Run the unit tests in the <em>current</em> project;</li>
-<li><tt>deepclean</tt> -- Cleans up any files in the current project and all
its dependencies;</li>
-<li><tt>deeptestng</tt> -- Runs the unit tests in the current project and all
its dependencies;</li>
-<li><tt>deeptest</tt> -- Runs the integration tests in the current project and
all its dependencies.</li>
+<li><tt>rat</tt> -- Run the release audit tool that reports any license
violations, such as incompatible licenses or missing license headers;</li>
+<li><tt>export</tt> -- Exports all "bndrun" files into runnable JAR files in
<tt>generated/distributions/executable</tt> of each "runnable" project.</li>
</ul>
-<p>There actually are a few more, but these are the most important ones.</p>
-<h2 id="how-to">How to...</h2>
-<h3 id="use-my-favorite-ide-not-eclipse">...use my favorite IDE (not
Eclipse)?</h3>
+<p>There actually are a few more (use the <tt>tasks</tt> target for that), but
these are the most important ones.</p>
+<h2 id="how-to">How to...<a class="headerlink" href="#how-to" title="Permanent
link">¶</a></h2>
+<h3 id="use-my-favorite-ide-not-eclipse">...use my favorite IDE (not
Eclipse)?<a class="headerlink" href="#use-my-favorite-ide-not-eclipse"
title="Permanent link">¶</a></h3>
<p>Unfortunately, the easy answer is "no". Until somebody ports Bndtools to
your favorite
IDE, you either have to use Eclipse, or a combination of your IDE and manual
builds using
Ant (though not recommended). If you insist, please do make sure you manually
generate the
proper metadata for Eclipse.</p>
-<h3 id="build-this-thing-in-eclipse">...build this thing in Eclipse?</h3>
+<h3 id="build-this-thing-in-eclipse">...build this thing in Eclipse?<a
class="headerlink" href="#build-this-thing-in-eclipse" title="Permanent
link">¶</a></h3>
<p>Normally, you don't. Seriously. If "Build Automatically" is enabled, as
soon as you hit
save after changing a line of code, BndTools will automatically build your
bundle for you.
In fact, if your server if already running, Bndtools will even redeploy all
changed
bundles to it automatically.</p>
-<h3 id="get-rid-of-all-those-red-crosses-in-eclipse">...get rid of all those
red crosses in Eclipse?</h3>
+<h3 id="get-rid-of-all-those-red-crosses-in-eclipse">...get rid of all those
red crosses in Eclipse?<a class="headerlink"
href="#get-rid-of-all-those-red-crosses-in-eclipse" title="Permanent
link">¶</a></h3>
<p>If Eclipse complaints about missing test libraries, you probably forgot to
install the
TestNG plugin. If this plugin is installed, it will automatically cause your
projects to
get the required dependency to the TestNG library. Without this plugin,
Eclipse won't have
@@ -273,33 +280,13 @@ In case you are importing the projects i
and a couple of builds to get rid of all build errors. If the problem does
<em>not</em> go away,
please drop a line on the <a href="/get-involved/mailing-lists.html">mailing
lists</a> to get
additional help.</p>
-<h3 id="create-a-distributable-archive">...create a distributable archive</h3>
-<p>The next step is to create an archive for the server, so we end up with
something we can
-actually run:</p>
-<div class="codehilite"><pre><span class="nv">$ </span><span class="nb">cd
</span>build
-<span class="nv">$ </span>ant package-bin
-</pre></div>
-
-
-<p>Now, in the generated folder, an archive will have been created. You can
unzip this
-archive, which should expose a couple of subfolders with the same names as the
runnable
-projects that you can go into and run. You can start the "all in one" server
like this:</p>
-<div class="codehilite"><pre><span class="nv">$ </span><span class="nb">cd
</span>apache-ace-1.0.0-bin
-<span class="nv">$ </span>unzip apache-ace-1.0.0-bin/.zip
-<span class="nv">$ </span><span class="nb">cd </span>server-allinone/
-<span class="nv">$ </span>java -jar server-allinone.jar
-</pre></div>
-
-
-<p>For other projects, the steps are similar to this: just go into the correct
folder and
-launch the jar file.</p>
-<h3 id="add-an-osgi-bundle">...add an OSGi bundle</h3>
+<h3 id="add-an-osgi-bundle">...add an OSGi bundle<a class="headerlink"
href="#add-an-osgi-bundle" title="Permanent link">¶</a></h3>
<p>The easiest way to add an OSGi bundle, is to drag it onto the "Local
Repository" entry in
the "Repositories" view, or to use the "Add files to repository" toolbar icon.
Bndtools
will analyze the files you try to add and show their metadata if they're
indeed valid
bundles.</p>
<p>The bundles will end up in the local repository inside the <tt>cnf</tt>
project.</p>
-<h3 id="add-a-java-library">...add a Java library</h3>
+<h3 id="add-a-java-library">...add a Java library<a class="headerlink"
href="#add-a-java-library" title="Permanent link">¶</a></h3>
<p>If you want to add a library that does not contain any OSGi metadata, you
can follow the
steps below to add it to the "Library Repository" so it can be used in all
other projects
within Apache ACE. If your library does have sensible OSGi metadata, please
follow the
@@ -309,18 +296,10 @@ within Apache ACE. If your library does
to the following location: <tt>cnf/lib/foo/foo-1.0.0.jar</tt>. Note that the
directory
name should be equal to the basename of the added JAR file, that is,
everything <em>before</em>
the version-string of the JAR;</li>
-<li>
-<p>Update the <code>repository.xml</code>. After making changes to anything in
<tt>cnf/lib/</tt> you
-need to update the index file that describes the contents of the repository.
To do this
-enter the following commands:</p>
-<div class="codehilite"><pre><span class="nv">$ </span><span class="nb">cd
</span>cnf
-<span class="nv">$ </span>ant build
-<span class="nv">$ </span>java -cp bin org.apache.ace.bnd.LibraryIndexer
-</pre></div>
-
-
-</li>
-</ol></div>
+<li>Refresh the repositories in Bnd by invoking "Bndtools -> Refresh
Repositories".</li>
+</ol>
+<p>Your library should be now available "Repositories" view and can be used
normally in
+any OSGi project.</p></div>
<hr>
<footer>
<p>Copyright © 2012-2015 <a href="http://www.apache.org/";>The
Apache Software Foundation</a>, Licensed under the <a
href="http://www.apache.org/licenses/LICENSE-2.0";>Apache License, Version
2.0</a>.<br/>Apache ACE, the Apache ACE logo, Apache and the Apache feather
logo are trademarks of The Apache Software Foundation. All other marks
mentioned may be trademarks or registered trademarks of their respective
owners.</p>
