ace-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From j...@apache.org
Subject svn commit: r1749405 - /ace/site/trunk/content/docs/setup-dev-environment.mdtext
Date Mon, 20 Jun 2016 21:18:46 GMT
Author: jawi
Date: Mon Jun 20 21:18:46 2016
New Revision: 1749405

URL: http://svn.apache.org/viewvc?rev=1749405&view=rev
Log:
ACE-596

Modified:
    ace/site/trunk/content/docs/setup-dev-environment.mdtext

Modified: ace/site/trunk/content/docs/setup-dev-environment.mdtext
URL: http://svn.apache.org/viewvc/ace/site/trunk/content/docs/setup-dev-environment.mdtext?rev=1749405&r1=1749404&r2=1749405&view=diff
==============================================================================
--- ace/site/trunk/content/docs/setup-dev-environment.mdtext (original)
+++ ace/site/trunk/content/docs/setup-dev-environment.mdtext Mon Jun 20 21:18:46 2016
@@ -9,35 +9,42 @@ source releases, or checkout the code fr
 
 ### Download the sources
 
-Point your browser to: http://ace.apache.org/download.html
+Point your browser to the [ACE download page](http://ace.apache.org/downloads.html).
 
 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 *both* the source and dependencies archive and then
 type:
 
     :::sh
-    $ unzip apache-ace-1.0.0-src.zip
-    $ unzip apache-ace-1.0.0-deps.zip
+    $ unzip apache-ace-2.1.0-src.zip
+    $ unzip apache-ace-2.1.0-deps.zip
 
 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.
+both archives. It is fine to overwriting theses files.
 
 ### Checkout from subversion
 
+Alternatively, you can check out the sources directly from the main Apache source repositories:
+
     :::sh
     $ svn co http://svn.apache.org/repos/asf/ace/trunk apache-ace
 
+or
+
+    :::sh
+    $ git clone git://git.apache.org/ace apache-ace
+
 In both cases you end up with a copy of the source code.
 
 
 ## 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 the [Bndtools plugin](http://bndtools.org/) 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.
 
 ### Eclipse with Bndtools
 
@@ -45,21 +52,21 @@ to build and run Apache ACE within a dev
 
 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).
+* A recent Java JDK, at least [Java 8](http://www.oracle.com/technetwork/indexes/downloads/index.html);
+* A recent Eclipse, for example, [Eclipse Mars](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.
+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.
 
 #### 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.
+previously checked out or extracted your sources. This is important, as otherwise 
+Bndtools will not function correctly.
 
 ##### Checking out the latest sources
 
@@ -71,8 +78,9 @@ 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.*
+**individual** projects underneath.  *Note: do **not** (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.*
 
 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
@@ -100,46 +108,55 @@ import it into Eclipse as your default f
 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.
+".bndrun" file.  
+To start a project, right-click the "bndrun" file and select "Run As" -> "Bnd OSGi
Run 
+Launcher" or "Debug As" -> "Bnd OSGi Run Launcher".
+
+There are several projects that can be run which we outline in the next sections.
+
+##### ACE target
+
+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.
+
+To run or debug the ACE server, use the "<tt>target.bndrun</tt>" file in the
+"run-target" project. 
 
 ##### 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 -&gt; Bnd OSGi Run Launcher" or "Debug
-As -&gt; Bnd OSGi Run Launcher".
-
-##### ACE obr
-
-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 -&gt; Bnd OSGi Run Launcher" or "Debug As -&gt;
Bnd
-OSGi Run Launcher".
+This project allows you to start a plain ACE server *without* 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>.
+
+To run or debug the ACE server, use the "<tt>server.bndrun</tt>" file in the
+"run-server" project. 
+
+##### ACE OBR
+
+This will start an OBR for your artifacts. By default, its endpoints can be reached through
+port <tt>8082</tt>. 
+
+To run or debug the ACE OBR, use the "<tt>obr.bndrun</tt>" file in the "run-obr"
+project.
 
 ##### ACE client
 
-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 -&gt; Bnd OSGi Run Launcher" or "Debug
-As -&gt; Bnd OSGi Run Launcher".
+This project allows you to start the web-based client. The web UI can be reached by opening
+[localhost:8081/](http://localhost:8081/) 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>.
+
+To run or debug the ACE client, use the "<tt>client.bndrun</tt>" file in the
+"run-client" project.
 
 ##### ACE server-allinone
 
-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 -&gt; Bnd OSGi Run Launcher" or "Debug
-As -&gt; Bnd OSGi Run Launcher".
+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>.
 
-##### ACE target
-
-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.
+To run or debug the "all in one" ACE server, use the
+"<tt>server-allinone.bndrun</tt>" file in the "run-server-allinone" project.
 
 ##### Unit tests
 
@@ -148,53 +165,37 @@ As -&gt; TestNG Test" or "Debug As -&gt;
 
 ##### Integration tests
 
-The integration tests of ACE are placed in separate projects that are -by convention-
+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 -&gt; OSGi
-JUnit Test" or "Debug As -&gt; OSGi JUnit Test".
+framework up and running. To run one or all integration tests, use "Run As -&gt; Bnd
OSGi
+Test Launcher (JUnit)" or "Debug As -&gt; Bnd OSGi Test Launcher (JUnit)".
 
 ### Command line build
 
-#### Prerequisites
-
-For developing ACE using Ant, 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 command line build for Apache ACE is based on [Gradle](http://gradle.org/).
 
 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.
+1. `cnf` -- Which is collection of repositories that contain all the required dependencies
for building and running Apache ACE;
+2. `build` -- A project that contains the necessary scripts and tools to do source and binary
releases.
 
-So, to build Apache ACE, we issue the following commands:
+So, to build Apache ACE, we issue the following command:
 
     :::sh
-    $ cd build
-    $ ant
+    $ ./gradlew build
 
-In the end, this leaves us with a set of bundles (in the <tt>generated</tt> folder
of each
-project).
+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).
 
 The following targets are available:
 
 * <tt>clean</tt> -- Cleans up any files in the current project that were generated
during a build;
 * <tt>build</tt> -- Build the current project;
-* <tt>test</tt> -- Run the integration tests in the *current* project;
-* <tt>testng</tt> -- Run the unit tests in the *current* project;
-* <tt>deepclean</tt> -- Cleans up any files in the current project and all its
dependencies;
-* <tt>deeptestng</tt> -- Runs the unit tests in the current project and all its
dependencies;
-* <tt>deeptest</tt> -- Runs the integration tests in the current project and
all its dependencies.
+* <tt>rat</tt> -- Run the release audit tool that reports any license violations,
such as incompatible licenses or missing license headers;
+* <tt>export</tt> -- Exports all "bndrun" files into runnable JAR files in <tt>generated/distributions/executable</tt>
of each "runnable" project.
 
-There actually are a few more, but these are the most important ones.
+There actually are a few more (use the <tt>tasks</tt> target for that), but these
are the most important ones.
 
 ## How to...
 
@@ -223,28 +224,6 @@ and a couple of builds to get rid of all
 please drop a line on the [mailing lists](/get-involved/mailing-lists.html) to get
 additional help.
 
-### ...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:
-
-    :::sh
-    $ cd build
-    $ ant package-bin
-
-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:
-
-    :::sh
-    $ cd apache-ace-1.0.0-bin
-    $ unzip apache-ace-1.0.0-bin/.zip
-    $ cd server-allinone/
-    $ java -jar server-allinone.jar
-
-For other projects, the steps are similar to this: just go into the correct folder and
-launch the jar file.
-
 ### ...add an OSGi bundle
 
 The easiest way to add an OSGi bundle, is to drag it onto the "Local Repository" entry in
@@ -265,12 +244,7 @@ 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 *before*
 the version-string of the JAR;
-2. Update the `repository.xml`. 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:
-
-        :::sh
-        $ cd cnf
-        $ ant build
-        $ java -cp bin org.apache.ace.bnd.LibraryIndexer
+2. Refresh the repositories in Bnd by invoking "Bndtools -&gt; Refresh Repositories".
 
+Your library should be now available "Repositories" view and can be used normally in
+any OSGi project.



Mime
View raw message