ace-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From ma...@apache.org
Subject svn commit: r1372360 - in /ace/site/trunk: content/dev-doc/getting-started.mdtext content/dev-doc/release-guide.mdtext content/user-doc/getting-started.mdtext templates/sidenav.html
Date Mon, 13 Aug 2012 11:03:34 GMT
Author: marrs
Date: Mon Aug 13 11:03:33 2012
New Revision: 1372360

URL: http://svn.apache.org/viewvc?rev=1372360&view=rev
Log:
Added new getting started guides for new, Bndtools based build. Added an (empty) link to the
release guide.

Added:
    ace/site/trunk/content/dev-doc/getting-started.mdtext
    ace/site/trunk/content/dev-doc/release-guide.mdtext
Modified:
    ace/site/trunk/content/user-doc/getting-started.mdtext
    ace/site/trunk/templates/sidenav.html

Added: ace/site/trunk/content/dev-doc/getting-started.mdtext
URL: http://svn.apache.org/viewvc/ace/site/trunk/content/dev-doc/getting-started.mdtext?rev=1372360&view=auto
==============================================================================
--- ace/site/trunk/content/dev-doc/getting-started.mdtext (added)
+++ ace/site/trunk/content/dev-doc/getting-started.mdtext Mon Aug 13 11:03:33 2012
@@ -0,0 +1,169 @@
+Title: Getting Started
+
+Everything you need to know to start developing Apache ACE can be found here.
+
+## Obtaining the sources
+
+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.
+
+### Download the sources
+
+Point your browser to: http://ace.apache.org/download.html
+
+On that page you will find, amongst others, a link to the latest released sources. The page
will automatically select a download mirror close to you. Download the archive and then type:
+
+$ unzip apache-ace-src-1.0.0.zip
+
+### Checkout from subversion
+
+$ svn co http://svn.apache.org/repos/asf/ace/trunk apache-ace
+
+In both cases you end up with a copy of the source code in the apache-ace folder.
+
+
+## Building the sources
+
+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.
+
+### Eclipse with Bndtools
+
+#### Prerequisites
+
+For developing ACE using Eclipse, you need:
+
+* A recent Java JDK, at least [Java 6](http://www.oracle.com/technetwork/indexes/downloads/index.html);
+* A recent Eclipse, for example, [Eclipse Juno](http://www.eclipse.org/downloads/) with the
following plugins:
+  * [Subclipse](http://subclipse.tigris.org/servlets/ProjectProcess?pageID=p4wYuA);
+  * [BndTools](http://bndtools.org/installation.html);
+  * [TestNG](http://testng.org/doc/download.html).
+
+For building or exporting the compiled artifacts of ACE without Eclipse, you only need [Apache
ANT](http://ant.apache.org/) version 1.8+ installed.
+
+#### Eclipse set up
+
+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.
+
+##### Checking out the latest sources
+
+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 Repositories" view:
+
+    https://svn.apache.org/repos/asf/ace/trunk/
+
+After this, expand the newly created tree node named after the SVN URL, and select all **individual**
projects underneath. 
+*Note: do **not** (only) select the root node, as this won't let you properly import the
individual projects.*
+
+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.
+
+Switching back to the "Bndtools" perspective should give you a long list of imported projects.
+
+##### Importing existing projects
+
+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.
+
+##### Coding guidelines
+
+If you want to develop for ACE, you might want to import the code templates and formatter
rules for ACE.
+
+**TODO**
+
+#### Running & debugging
+
+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.
+
+##### ACE server
+
+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 -> OSGi Run" or "Debug As -> OSGi Run".
+
+##### ACE target
+
+You can also directly run a target from Eclipse. Doing this is almost equal as running the
ACE server described in the previous section. The only difference is that for running a target,
you need to use the "<tt>target.bndrun</tt>" file from the "run-target" project.
+
+##### Unit tests
+
+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". 
+
+##### Integration tests
+
+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".
+
+### Command line build
+
+#### Prerequisites
+
+For developing ACE using Eclipse, you need:
+
+* A recent Java JDK, at least [Java 6](http://www.oracle.com/technetwork/indexes/downloads/index.html);
+* [Apache ANT](http://ant.apache.org/) version 1.8+.
+
+#### Building
+
+The command line build for Apache ACE is based on Ant, and generated automatically when using
the Bndtools plugin in Eclipse.
+
+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:
+
+1. cnf -- Which is collection of repositories that contain all the required dependencies
for building and running Apache ACE.
+2. build -- A project that depends on all other projects and is used to build everything.
+
+So, to build Apache ACE, we type the following commands:
+
+```
+$ cd build
+$ ant
+```
+
+This leaves us with a set of bundles.
+
+The following targets are available:
+
+* clean -- Cleans up any files in the current project that were generated during a build.
+* build -- Build the current project.
+* test -- Run the integration tests in the current project.
+* testng -- Run the unit tests in the current project.
+* deepclean -- Cleans up any files in the current project and all its dependencies.
+* deeptestng -- Runs the unit tests in the current project and all its dependencies.
+* deeptest -- Runs the integration tests in the current project and all its dependencies.
+
+There actually are a few more, but these are the most important ones.
+
+## How to...
+
+### ...create a distributable archive
+
+The next step is to create an archive for the server, so we end up with something we can
actually run:
+
+```
+$ ant -f bin-build.xml package
+```
+
+Now, in the generated folder, two archives will have been created, and there are also subfolders
with the same names as the archives that you can go into and run. You can start the server
like this:
+
+```
+$ cd generated/ace-devserver
+$ sh run.sh
+```
+
+### ...add an OSGi bundle
+
+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.
+
+The bundles will end up in the local repository inside the `cnf` project.
+
+### ...add a Java library
+
+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 "How
to add a bundle" instructions below.
+
+Step 1: Copy the library to the right location
+
+The jar file for the library should be copied to the following location:
+
+cnf/lib/foo/foo-1.0.0.jar
+
+Step 2: Update the repository.xml
+
+After making changes to anything in cnf/lib/ you need to update the index file that describes
the contents of the repository. To do this enter the following commands:
+
+```
+$ cd cnf
+$ ant
+$ java -cp bin org.apache.ace.bnd.LibraryIndexer
+```

Added: ace/site/trunk/content/dev-doc/release-guide.mdtext
URL: http://svn.apache.org/viewvc/ace/site/trunk/content/dev-doc/release-guide.mdtext?rev=1372360&view=auto
==============================================================================
--- ace/site/trunk/content/dev-doc/release-guide.mdtext (added)
+++ ace/site/trunk/content/dev-doc/release-guide.mdtext Mon Aug 13 11:03:33 2012
@@ -0,0 +1,4 @@
+Title: Release Guide
+
+Apache ACE is an open source project, and as such its only official releases are source releases.
For convenience we also provide binaries. This document describes how to do a source release.
+

Modified: ace/site/trunk/content/user-doc/getting-started.mdtext
URL: http://svn.apache.org/viewvc/ace/site/trunk/content/user-doc/getting-started.mdtext?rev=1372360&r1=1372359&r2=1372360&view=diff
==============================================================================
--- ace/site/trunk/content/user-doc/getting-started.mdtext (original)
+++ ace/site/trunk/content/user-doc/getting-started.mdtext Mon Aug 13 11:03:33 2012
@@ -2,14 +2,22 @@ Title: Getting Started
 
 This guide shows the core functionality of ACE, organizing bundles and other artifacts into
logical features and distributions and associating those with specific targets, all done using
a convenient web interface.
 
-Using Apache ACE
-----------------
+##Using Apache ACE
 
+### Starting the server
+
+To start using ACE, you must first launch a server. If you're a developer, you can do that
inside Eclipse, as explained [here](/dev-doc/getting-started.html). Otherwise, you need to
download a distribution of the server, unpack it, and start it up:
+
+1. Download a binary distribution of the server from the [download](/downloads.html) page.
+1. Unpack the archive somewhere on your filesystem.
+1. Start it by running `run.sh` (on Linux and Mac OS X) or `run.bat` (on Windows).
+
+### Working with ACE
+
+Apache ACE has both a Web UI and a [REST API](restapi.html) to interact with it. Both use
a similar workflow. You start by checking out a copy of the workspace, then you work on that
copy, and finally you commit your changes back to the server.
 
 The following steps can be followed to get started:
 
-1. First we need to actually checkout and [build ACE|Maven Build]. Follow the link to get
more information on how to do that.
-1. Once ACE is built, we can start the server with integrated Web UI. Go to {{ace-target-devserver/target/org.apache.ace.target.devserver-*-distribution/ace-devserver}}.
Start it using the `run.sh` or `run.bat` file.
 1. Now the server is started, let's connect to it. Launch a browser and point it to: http://localhost:8080/ace/
You should now be greeted with a login prompt. Log in with user "d" password "f" and you should
see a view with 4 empty columns and some buttons at the top of the screen.
 1. Click on 'Retrieve' to get the initial version of the repository. It will look as if nothing's
happened, but you have now in fact retrieved the first, empty version of the repository and
can start manipulating it. Once you're happy with it, you can commit it back (which we'll
do a bit later).
 1. Upload some sample bundles into the artifacts column by first clicking the 'Add Artifact...'
button. In the dialog that appears, you can upload a bundle using the 'Upload' button in the
middle of the window. You can perform this step multiple times if you want to upload more
than one bundle. Finally, hit the 'Add' button to add all uploaded artifacts to ACE.
@@ -20,12 +28,3 @@ The following steps can be followed to g
 1. Now we need a target to actually deploy our artifacts to. To start a target, go to `ace-launcher/target`
and start it using `java -jar org.apache.ace.launcher*.jar`.
 1. After a few seconds, the target should show up in the Web UI. To associate it with a distribution,
drag that distribution onto the target.
 1. Click on 'Store' to actually store changes on the server, which should trigger the actual
deployment of the artifacts to the target.
-
-Debugging
----------
-
-You can hook up a standard remote debugger to either target. To do that, edit the run.sh
(or run.bat) script and include the following extra parameter for Pax Runner:
-
-`--vmOptions="-Xdebug -Xrunjdwp:transport=dt_socket,address=8000,server=y,suspend=y"`
-
-Now run the target, and start the debugger of your favorite IDE.
\ No newline at end of file

Modified: ace/site/trunk/templates/sidenav.html
URL: http://svn.apache.org/viewvc/ace/site/trunk/templates/sidenav.html?rev=1372360&r1=1372359&r2=1372360&view=diff
==============================================================================
--- ace/site/trunk/templates/sidenav.html (original)
+++ ace/site/trunk/templates/sidenav.html Mon Aug 13 11:03:33 2012
@@ -41,6 +41,9 @@
     <a href="#" class="dropdown-toggle" data-toggle="dropdown">Developer Documentation
<b class="caret"></b></a>
     <ul class="dropdown-menu">
       <li>
+        <a href="/dev-doc/getting-started.html">Getting Started</a>
+      </li>
+      <li>
         <a href="/dev-doc/requirements/">Requirements</a>
       </li>
       <li>
@@ -55,6 +58,9 @@
       <li>
         <a href="/dev-doc/coding-standards.html">Coding Standards</a>
       </li>
+      <li>
+        <a href="/dev-doc/release-guide.html">Release Guide</a>
+      </li>
     </ul>
   </li>
   <li class="dropdown">



Mime
View raw message