ace-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From build...@apache.org
Subject svn commit: r991089 - in /websites/staging/ace/trunk/content: ./ docs/setup-dev-environment.html
Date Tue, 21 Jun 2016 06:57:28 GMT
Author: buildbot
Date: Tue Jun 21 06:57:28 2016
New Revision: 991089

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 Tue Jun 21 06:57:28 2016
@@ -1 +1 @@
-1749405
+1749454

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 Tue Jun 21 06:57:28
2016
@@ -120,8 +120,8 @@ source releases, or checkout the code fr
 <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 <em>both</em> the source and dependencies
archive and then
-type:</p>
+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-2.1.0-src.zip
 <span class="nv">$ </span>unzip apache-ace-2.1.0-deps.zip
 </pre></div>
@@ -131,7 +131,8 @@ type:</p>
 files. Those are the required NOTICE and LICENSE files, which are in the same location in
 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">&para;</a></h3>
-<p>Alternatively, you can check out the sources directly from the main Apache source
repositories:</p>
+<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>
 
@@ -141,18 +142,21 @@ both archives. It is fine to overwriting
 </pre></div>
 
 
-<p>In both cases you end up with a copy of the source code.</p>
+<p>In both cases you end up with a copy of the source code. <em>Note: committers
should always
+use Subversion as the Git mirror is read-only.</em></p>
 <h2 id="building-the-sources">Building the sources<a class="headerlink" href="#building-the-sources"
title="Permanent link">&para;</a></h2>
 <p>There are two ways to build the sources. You can either run a command line build
or use
-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>
+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">&para;</a></h3>
 <h4 id="prerequisites">Prerequisites<a class="headerlink" href="#prerequisites"
title="Permanent link">&para;</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
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 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>
@@ -160,13 +164,16 @@ by far the most convenient way to build
 <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">&para;</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 sources. This is important, as otherwise 
-Bndtools will not function correctly.</p>
+<p>Start Eclipse with a new, empty, workspace. To set up the projects you can do either:</p>
+<ol>
+<li>if you use the <em>same</em> root folder/directory in which your ACE
sources are checked out
+   (or extracted) as your Eclipse workspace, you can import the projects directly using
+   "File -&gt; Import... -&gt; General -&gt; Existing Projects into Workspace";</li>
+<li>checkout the sources from Subversion as described below.</li>
+</ol>
 <h5 id="checking-out-the-latest-sources">Checking out the latest sources<a class="headerlink"
href="#checking-out-the-latest-sources" title="Permanent link">&para;</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
+<p>If you created a new and empty workspace, 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
 Repositories" view:</p>
 <div class="codehilite"><pre><span class="n">https</span><span
class="p">:</span><span class="o">//</span><span class="n">svn</span><span
class="p">.</span><span class="n">apache</span><span class="p">.</span><span
class="n">org</span><span class="o">/</span><span class="n">repos</span><span
class="o">/</span><span class="n">asf</span><span class="o">/</span><span
class="n">ace</span><span class="o">/</span><span class="n">trunk</span><span
class="o">/</span>
@@ -175,19 +182,13 @@ 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 or the
-files that reside underneath the root node, as this won't let you properly import 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.
+<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<a class="headerlink"
href="#importing-existing-projects" title="Permanent link">&para;</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
--&gt; Import..." and then select "General -&gt; 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<a class="headerlink" href="#coding-guidelines"
title="Permanent link">&para;</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
@@ -196,39 +197,54 @@ import it into Eclipse as your default f
 <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.<br />
-To start a project, right-click the "bndrun" file and select "Run As" -&gt; "Bnd OSGi
Run 
+".bndrun" file.</p>
+<p>To start a project, right-click the "bndrun" file and select "Run As" -&gt;
"Bnd OSGi Run
 Launcher" or "Debug As" -&gt; "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">&para;</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">&para;</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">&para;</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"
+<h5 id="run-develop">run-develop<a class="headerlink" href="#run-develop" title="Permanent
link">&para;</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, making it easy to debug or troubleshoot it. <em>Note: since the Gogo bundles
are
+already installed, do <strong>not</strong> provision them using ACE! The deployment
will fail.</em></p>
+<p>To run or debug the ACE server, use the "<tt>develop.bndrun</tt>" file
in the
+"run-develop" project. </p>
+<h5 id="run-target">run-target<a class="headerlink" href="#run-target" title="Permanent
link">&para;</a></h5>
+<p>This project allows you to directly start an ACE target that receives software from
the
+ACE server. In contrast to the "run-develop" project, this target does only start an ACE
+management agent and nothing else.</p>
+<p>To run or debug the ACE server, use the "<tt>target.bndrun</tt>" file
in the "run-target"
+project. </p>
+<h5 id="run-server">run-server<a class="headerlink" href="#run-server" title="Permanent
link">&para;</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="run-obr">run-obr<a class="headerlink" href="#run-obr" title="Permanent link">&para;</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="run-client">run-client<a class="headerlink" href="#run-client" title="Permanent
link">&para;</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="run-server-allinone">run-server-allinone<a class="headerlink" href="#run-server-allinone"
title="Permanent link">&para;</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="run-relay">run-relay<a class="headerlink" href="#run-relay" title="Permanent
link">&para;</a></h5>
+<p>This project allows you to start a relay server that you can use to distribute the
load
+from your main ACE server. Instead of all clients talking directly to one ACE server, you
+can let clients talk to one or more relay servers. The default relay configuration expects
+an ACE server to run at port <tt>8080</tt> and an OBR to run at port <tt>8082</tt>.
Its
+endpoints are reacheable through port <tt>8282</tt>.</p>
+<p>To run or debug the relay server, use the "<tt>relay.bndrun</tt>" file
in the "run-relay"
 project.</p>
-<h5 id="ace-client">ACE client<a class="headerlink" href="#ace-client" title="Permanent
link">&para;</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">&para;</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">&para;</a></h5>
 <p>ACE uses TestNG for its unit tests. To run a single test or a package of tests,
use "Run
 As -&gt; TestNG Test" or "Debug As -&gt; TestNG Test". </p>
@@ -242,46 +258,53 @@ Test Launcher (JUnit)" or "Debug As -&gt
 <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 contains the necessary scripts
and tools to do source and binary releases.</li>
+<li><code>cnf</code> -- Which is collection of repositories and configuration
files 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 command:</p>
 <div class="codehilite"><pre><span class="nv">$ </span>./gradlew
build
 </pre></div>
 
 
-<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>
+<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 (there actually are a few more, use the <tt>tasks</tt>
+target for that, but these are the most important ones):</p>
 <ul>
-<li><tt>clean</tt> -- Cleans up any files in the current project that were
generated during a build;</li>
+<li><tt>clean</tt> -- Cleans up any files and artifacts in the current
projects that were
+  generated during a build;</li>
 <li><tt>build</tt> -- Build the current project;</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>
+<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 (use the <tt>tasks</tt> target for that),
but these are the most important ones.</p>
+<p>You can prefix these task names with the <code>&lt;project-name&gt;:</code>
to execute them for a single
+project. For example, <code>run-target:export</code> would create the runnable
JAR file for the
+<tt>run-target</tt> project only.</p>
 <h2 id="how-to">How to...<a class="headerlink" href="#how-to" title="Permanent link">&para;</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">&para;</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>
+Gradle (though not recommended).</p>
 <h3 id="build-this-thing-in-eclipse">...build this thing in Eclipse?<a class="headerlink"
href="#build-this-thing-in-eclipse" title="Permanent link">&para;</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>
+save after changing a line of code, Bndtools will automatically build your bundle(s) for
+you. In fact, if any project is already running, Bndtools will even redeploy all changed
+bundles to it automatically allowing you to directly test your changes at runtime.</p>
 <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">&para;</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
-the required library and fails to compile the code correctly.<br />
-In case you are importing the projects into Eclipse for the first time, it takes a while
-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>
+the required library and fails to compile the code correctly.  In case you are importing
+the projects into Eclipse for the first time, it takes a while 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="add-an-osgi-bundle">...add an OSGi bundle<a class="headerlink" href="#add-an-osgi-bundle"
title="Permanent link">&para;</a></h3>
-<p>The easiest way to add an OSGi bundle, is to drag it onto the "Local Repository"
entry in
+<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>
@@ -293,13 +316,13 @@ within Apache ACE. If your library does
 "...add an OSGi bundle" instructions above.</p>
 <ol>
 <li>Copy the library to the right location. The jar file for the library should be
copied
-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>
+   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>Refresh the repositories in Bnd by invoking "Bndtools -&gt; Refresh Repositories".</li>
 </ol>
-<p>Your library should be now available "Repositories" view and can be used normally
in
-any OSGi project.</p></div>
+<p>Your library should be now available "Repositories" view and can be used normally
in any
+OSGi project.</p></div>
       <hr>
       <footer>
         <p>Copyright &#169; 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>



Mime
View raw message