You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@etch.apache.org by gr...@apache.org on 2010/09/23 16:58:23 UTC
svn commit: r1000489 - in /incubator/etch/trunk: BUILD.txt README.txt
RELEASE_NOTES.txt
Author: grandyho
Date: Thu Sep 23 14:58:23 2010
New Revision: 1000489
URL: http://svn.apache.org/viewvc?rev=1000489&view=rev
Log:
ETCH-100
ETCH-85
ETCH-84
READMEs updated to match new trunk structure
Modified:
incubator/etch/trunk/BUILD.txt
incubator/etch/trunk/README.txt
incubator/etch/trunk/RELEASE_NOTES.txt
Modified: incubator/etch/trunk/BUILD.txt
URL: http://svn.apache.org/viewvc/incubator/etch/trunk/BUILD.txt?rev=1000489&r1=1000488&r2=1000489&view=diff
==============================================================================
--- incubator/etch/trunk/BUILD.txt (original)
+++ incubator/etch/trunk/BUILD.txt Thu Sep 23 14:58:23 2010
@@ -26,6 +26,7 @@ This is the source tree for Etch. It is
util/ - shared java classes
tests/ - functional tests
examples/ - Etch application examples
+ helloworld/ - classic example
chat/ - simple IM application
distmap/ - example implementation of a distributed map in etch
perf/ - etch client/server performance test
@@ -35,6 +36,7 @@ This is the source tree for Etch. It is
binding-xml - xml binding
binding-java - java-language binding
binding-csharp - C#-language binding
+ binding-c - C-language binding
About the Structure of Etch bindings
@@ -78,19 +80,84 @@ To compile NSIS installers:
* NSIS 2.23
+To compile the C binding:
+
+ * Apache APR 1.3.12
+ * Apache APR Util 1.3.12
+ * Apache APR iconv
+ * Cunit 2.1
+ * Apache Ant CMake 1.0 (cmakeant.jar)
+
+Setting up your ETCH_EXTERNAL_DEPENDS folder:
+---------------------------------------------
+
+Set up a folder containing all external dependencies of the Etch build (all languages).
+This folder will be called ETCH_EXTERNAL_DEPENDS later on.
+
+To ease the download of the APR dependencies, we have created scripts/apr-install.sh
+and scripts/apr-install.bat for linux and windows. Those scripts provide you a complete
+APR installation folder for the directory structure below. See also binding-c/runtime/c/README.txt
+for more details on this.
+
+You can use the workspace contents of our continous integration server as a reference
+for you machine, e.g. for Win32:
+https://hudson.apache.org/hudson/view/etch/job/etch-trunk-windows-x86/ws/externals/
+
+You should have the following structure, if you want to compile and build for all language bindings
+(newer version could, but do not have to, work):
+
+ ETCH_EXTERNAL_DEPENDS/
+ javacc/
+ 4.0/
+ javacc.jar
+ junit /
+ 4.3.1/
+ junit-4.3.1.jar
+ nunit/
+ 2.4.7/
+ [contents of nunit 2.4.7 release tgz/zip]
+ velocity/
+ 1.5/
+ velocity-dep-1.5.jar
+ apache-ant/
+ 1.7.0/
+ [contents of apache ant 1.7 release tgz/zip]
+ apache-ant-cmake/
+ 1.0/
+ cmakeant.jar
+ apache-ant-dotnet/
+ 1.0/
+ [contents of apache ant dotnet 1.0 release tgz/zip]
+ apr/
+ 1.3.2/
+ [apr binary installation, see above]
+ cmake/
+ 2.8.2/
+ [contents of cmake standalone 2.8.2 release tgz/zip]
+ cunit/
+ 2.1/
+ [built cunit version,
+ on linux: you can skip this and use system libraries on your machine, e.g. apt-get install libcunit1 libcunit1-dev
+ on win32: see binding-c/runtime/c/README.txt for instructions on building cunit on Win32]
+ nsis/ (WINDOWS ONLY)
+ 2.23/
+ [skip if you want no installer built, else: contents of nsis 2.23 standalone zip/tgz]
+
Setup development environment
-----------------------------
The primary development environments for the Etch committers are Win32 and
-*nix (Mac OS X). As such we have attempted to make the build process platform
-neutral. In addition, Etch builds are done daily on our internal Bamboo server
-here at Cisco on the win32 platform. This means that we tend to have a bias
-towards a working Win32 build. To further complicate matters, we have much
-development-environment divergence in our committer base, some of us being very
-shell-centric (dixson) while others of us being firmly rooted in Eclipse (sccomer).
-So the compromise has been to attempt to structure the build such it can be
-friendly and productive to both groups and keep the sectarian violence to
-a minimum. :-)
+*nix (Linux, Mac OS X). As such we have attempted to make the build process platform
+neutral.
+
+The build is running contiously for Windows and Linux on our build server at Apache:
+https://hudson.apache.org/hudson/view/etch/
+
+To further complicate matters, we have much development-environment divergence in
+our committer base, some of us being very shell-centric while others of us
+being firmly rooted in Eclipse. So the compromise has been to attempt to structure
+the build such it can be friendly and productive to both groups and keep the
+sectarian violence to a minimum. :-)
1. Install JDK. Make certain that you set your JAVA_HOME environment variable
to point to the correct location.
@@ -100,37 +167,17 @@ Building from ANT
1. Install Apache ANT (version 1.7 or later).
-2. Put /path/to/apache-ant-1.7/bin in your PATH.
-
-3. If you have Mono, make certain MONO_HOME is set correctly. If you have .NET
- framework, make certain msbuild.exe is in your PATH.
-
-4. If building C#, make certain NUNIT_HOME is set correctly.
-
-5. If building on Win32 and you want to build the NSIS installers, set
- NSIS_HOME to /path/to/nsis/2.23.
+2. on Win32:
+ set ETCH_EXTERNAL_DEPENDS=<YOUR_EXTERNAL_DEPENDS_FOLDER>
+ Execute scripts/antSetup.bat
+ on Linux:
+ export ETCH_EXTERNAL_DEPENDS=<YOUR_EXTERNAL_DEPENDS_FOLDER>
-6. [IMPORTANT] Update 'build.dependencies' with the correct paths to the jar's
- this project depends upon:
+3. Check 'build.dependencies' with the correct paths to the jar's this project depends upon.
- * javacc.home=/path/to/javacc-4.0
- ('${javacc.home}/bin/lib/javacc.jar' should exist)
-
- * junit.lib=/path/to/junit-4.3.1
- ('${junit.lib}/junit-4.3.1.jar' should exist)
-
- * velocity.lib=/path/to/velocity-1.5
- ('${velocity.lib}/velocity-dep-1.5.jar' should exist)
+4. At the shell prompt type:
- --OPTIONAL--
- * ant-dotnet.lib=/path/to/apache-ant-dotnet-1.0
-
-(dixson) This is a hack until I get autoconf working. Just not there yet :-(
-
-
-7. At the shell prompt type:
-
- > ant release
+ > ant Debug
This will build all compilers and all the bindings for which you have setup
dependencies. It will also build and run all unit/functional tests and build
@@ -241,6 +288,8 @@ Tools / Organize Favorites... Click Add.
You should see a nice output in the Console reporting successful compilation
of a bunch of etch files. Eclipse should then rebuilt the project.
+(alternative: do ant debug in examples directory)
+
Finally, you can check things out by running the unit tests.
Right click on the etch project, select Run as... / Junit test.
@@ -249,5 +298,4 @@ You'll get some output on the console wi
traces. That's ok. JUnit runner should tell you that 1197 tests passed, 22
ignored, with 0 errors and 0 failures. This takes 66 seconds for me (sccomer).
-You're done, start exploring. Check out examples, perf or chat.
-
+You're done, start exploring. Check out examples: helloworld, perf or chat.
Modified: incubator/etch/trunk/README.txt
URL: http://svn.apache.org/viewvc/incubator/etch/trunk/README.txt?rev=1000489&r1=1000488&r2=1000489&view=diff
==============================================================================
--- incubator/etch/trunk/README.txt (original)
+++ incubator/etch/trunk/README.txt Thu Sep 23 14:58:23 2010
@@ -16,7 +16,7 @@ development and consumption.
The jumping off point for Etch information and help is here:
- http://cwiki.apache.org/ETCH
+ http://incubator.apache.org/etch
= Binary Distribution =
@@ -25,13 +25,17 @@ The top-level structure of the install i
ChangeLog.txt
DISCLAIMER.txt
LICENSE.txt
+ LICENSE_THIRD_PARTY.txt
NOTICE.txt
+ NOTICE_THIRD_PARTY.txt
README.txt
RELEASE_NOTES.txt
bin/
examples/
lib/
- maven/
+ binding-c/
+ binding-csharp/
+ binding-java/
uninst.exe (for windows use only)
Please take a moment to review the RELEASE_NOTES.txt, ChangeLog.txt and
@@ -41,11 +45,11 @@ The Windows installer (apache-etch-1.1.0
user environment variable (ETCH_HOME) which points to the Etch installation
directory. If you installed Etch using either
- apache-etch-1.1.0-incubating-bin.tar.gz
+ apache-etch-1.1.0-incubating-windows-x86-bin.zip
or
- apache-etch-1.1.0-incubating-bin.zip
+ apache-etch-1.1.0-incubating-linux-x86-bin.tgz
you will want to create this environment variable yourself:
@@ -83,32 +87,82 @@ unix:
bash-3.2$ etch -v
Etch version is Apache Etch 1.1.0-incubating (some build info)
-The lib directory contains the various jar files, zipped sources, and a C# dll
-with associated symbols and source:
+The lib directory contains the various jar files for the compiler and the Apache Velocity dependency jar:
- ApacheEtchCsharpIncubating.dll
- ApacheEtchCsharpIncubating.pdb
- ApacheEtchCsharpIncubatingSrc.zip
- ...
- apache-etch-java-runtime-1.1.0-incubating-src.zip
- apache-etch-java-runtime-1.1.0-incubating.jar
+ apache-etch-java-compiler-1.1.0-incubating.jar
+ apache-etch-java-compiler-1.1.0-incubating-src.jar
...
-The main items of interest, shown above, are the language binding runtimes,
-which you need to link with your projects.
+The top level folders binding-c, binding-java and binding-csharp contain the language specific
+runtime libraries:
-For java you need to put the etch java runtime jar on the classpath of your
-projects:
+= Binding for Java =
- apache-etch-java-runtime-1.1.0-incubating.jar
+binding-java is organized as follows:
+
+ apache-etch-java-runtime-1.1.0-incubating-src.zip
+ lib/
+ apache-etch-java-runtime-1.1.0-incubating.jar
+The generated java source from the etch compiler needs apache-etch-java-runtime-1.1.0-incubating.jar.
There is source code to go with it in apache-etch-java-runtime-1.1.0-incubating-src.zip.
-The C# (.NET 2.0 and later) ApacheEtchCsharpIncubating.dll should be added to
-any C# projects.
+= Binding for C# =
+
+binding-csharp is organized as follows:
+
+ apache-etch-csharp-runtime-1.1.0-incubating-src.zip
+ lib/
+ ApacheEtchCsharpIncubating.dll
+ ApacheEtchCsharpIncubating.pdb
+
+The generated c# source from the etch compiler needs ApacheEtchCsharpIncubating.dll
+The C# (.NET 2.0 and later) ApacheEtchCsharpIncubating.dll should be added to any C# projects.
+There is source code to go with it in apache-etch-csharp-runtime-1.1.0-incubating-src.zip.
+
+= Binding for C =
+
+binding-c is organized as follows:
+
+ bin/
+ apr-1-config (on linux)
+ apriconv (on linux)
+ include/
+ [etch-*].h (on win32)
+ apr-1 (on linux)
+ lib/
+ etch.lib (on win32)
+ etch.pdb (on win32)
+ libetch.a (on linux)
+ extern/
+ apr/
+ bin/
+ libapr-1.dll (on win32)
+ libapr-1.pdb (on win32)
+ libapriconv-1.dll (on win32)
+ libapriconv-1.pdb (on win32)
+ iconv/
+ [iconv*]-stuff
+ include/
+ [apr-*].h
+ lib/
+ libapr-1.lib (on win32)
+ libapriconv-1.lib (on win32)
+ libapr-1.so (on linux)
+ libapriconv-1.so (on linux)
+ apache-etch-c-runtime-1.1.0-incubating-src.zip
+
+Generated C source depends on the dlls/so/a/h files mentioned above. The best choice to
+build generated code using the c binding is cmake. You can use the examples/helloworld
+example as a reference. The C binding has external dependencies to the Apache Portable
+Runtime (APR). We ship dll/so/h for the apr in the extern folder. There is source code
+to go with it in apache-etch-c-runtime-1.1.0-incubating-src.zip
+
+= Ant Plugin =
There is an ant plugin which you can use with ant 1.7.0 or later to invoke the
-compiler as a task. It is documented on the wiki referenced above.
+compiler as a task. It is documented on the wiki referenced above. You can also see examples
+of its usage in the build.xml files in the examples folder
= Maven =
@@ -133,7 +187,8 @@ contribute.
= Examples =
-Examples have been provided in the examples/ subdirectory. There is a readme
+Examples have been provided in the examples/ subdirectory. Start with the HelloWorld
+example, it contains code for all three language bindings. There is a readme
file in each example's directory which explains how to build and run it.
= Tests =
@@ -141,7 +196,7 @@ file in each example's directory which e
Unit tests can be had by checking out the source code from the subversion
repository and performing a complete build:
- https://svn.apache.org/repos/asf/incubator/etch/releases/release-1.1.0
+ http://svn.apache.org/repos/asf/incubator/etch/releases/release-1.1.0-incubating
= Help =
Modified: incubator/etch/trunk/RELEASE_NOTES.txt
URL: http://svn.apache.org/viewvc/incubator/etch/trunk/RELEASE_NOTES.txt?rev=1000489&r1=1000488&r2=1000489&view=diff
==============================================================================
--- incubator/etch/trunk/RELEASE_NOTES.txt (original)
+++ incubator/etch/trunk/RELEASE_NOTES.txt Thu Sep 23 14:58:23 2010
@@ -4,10 +4,11 @@ us here:
Project info:
http://incubator.apache.org/projects/etch.html
+ http://incubator.apache.org/etch
Documentation info:
- http://cwiki.apache.org/ETCH/
+ http://incubator.apache.org/etch
Issues:
@@ -17,6 +18,10 @@ SVN:
http://svn.apache.org/repos/asf/incubator/etch/
+Continous Integration Server (Hudson):
+
+ https://hudson.apache.org/hudson/view/etch
+
Mailing lists:
mailto:etch-dev@incubator.apache.org (etch developers)
@@ -27,20 +32,24 @@ Subscribing to the mailing lists:
mailto:etch-dev-subscribe@incubator.apache.org (etch developers)
mailto:etch-user-subscribe@incubator.apache.org (etch users)
-This release of Apache Etch resolves issues related to our new home at Apache.
-One Apache requirement is that the java (and csharp) name spaces look something
+This release is the first fully ASF compliant release of Apache Etch.
+
+The release consists of the three stable language bindings of Etch
+- Java
+- C#
+- C
+
+One Apache requirement is that the java, csharp and c name spaces look something
like org.apache.etch... These changes have been made, however, they will break
existing users of etch. All that need be done for java is to correct the package
names from etch.* to org.apache.etch.*. For C#, the namespace has changed from
Etch.* to Org.Apache.Etch.*. In both cases, you will need to re-etch your *.etch
source files.
-There are also some new components in this release, the biggest of which are the
-contribution of the python and c bindings from Cisco. There is also an
-interoperability testing framework, also from Cisco. While these components are
-not yet fully functional, getting them here is an important milestone. There is
-still some work to be done, interested parties should send inquiries to
-etch-dev@incubator.apache.org.
+There are also some new components in this release, the biggest of which is the
+contribution of the python and c bindings from Cisco and the stabilization of the C binding.
+For the python binding, there is still some work to be done, interested parties should
+send inquiries to etch-dev@incubator.apache.org.
There are a few bugs fixed in this release, too, as detailed below. Some of
these fixes are compiler changes. Please be sure to recompile all your etch
@@ -48,43 +57,87 @@ source files.
Here are the issues resolved in this release:
-Key Summary
---- -------
-** Bug
- * [ETCH-56] - UnwantedMessage.ToString method attempts to format using the
- java style formatting instead of csharp style
- * [ETCH-57] - Sometimes closing a TlsConnection normally will result in an
- IOException with Socket is closed.
- * [ETCH-69] - Compiler throws URISyntaxException if there are spaces in the
- classpath
- * [ETCH-76] - Build problems if Etch source is downloaded to a path with
- spaces
+Sub-task
+
+ * [ETCH-33] - create directory structure for c binding
+ * [ETCH-34] - import the c binding code into the new directory structure
+ * [ETCH-36] - create the directory structure for the python binding
+ * [ETCH-37] - import the python binding into the new directory structure
+ * [ETCH-39] - create directory structure for interoperability tester
+ * [ETCH-40] - import the code for the interoperability tester
+ * [ETCH-41] - import the java example test
+ * [ETCH-42] - create a csharp example test
+ * [ETCH-43] - create a interoptest script which combines java and csharp
+ * [ETCH-45] - put java header comments in order per apache standard
+ * [ETCH-46] - put csharp header comments in order per apache standard
+ * [ETCH-47] - put python header comments in order per apache standard
+ * [ETCH-48] - put c header comments in order per apache standard
+ * [ETCH-50] - merge changes from 1.0.2 branch to trunk - 738635 update version string
+ * [ETCH-51] - merge changes from 1.0.2 branch to trunk - 738652 make examples more tolerant
+ * [ETCH-52] - merge changes from 1.0.2 branch to trunk - 739277 update eclipse build
+ * [ETCH-53] - merge changes from 1.0.2 branch to trunk - 739282 updates to unit tests
+ * [ETCH-55] - merge changes from 1.0.2 branch to trunk - 739287 fix for selector under linux
+
+Bug
+
+ * [ETCH-56] - UnwantedMessage.ToString method attempts to format using the java style formatting instead of csharp style
+ * [ETCH-57] - Sometimes closing a TlsConnection normally will result in an IOException with Socket is closed.
+ * [ETCH-69] - Compiler throws URISyntaxException if there are spaces in the classpath
+ * [ETCH-76] - Build problems if Etch source is downloaded to a path with spaces
* [ETCH-77] - Incompatibility in the READMEs for the bundled examples
+ * [ETCH-80] - Windows 7 / .NET 3.5 SP1 runtime setsockopt error
+
+Improvement
-** Improvement
- * [ETCH-54] - TransportFactory.newTransport returns stack topped by
- DeliveryService which makes it hard to implement meta transports
- * [ETCH-59] - Listener stack is built 1/2 upside down and strange inhibiting
- name service and other transport filters
+ * [ETCH-54] - TransportFactory.newTransport returns stack topped by DeliveryService which makes it hard to implement meta transports
+ * [ETCH-59] - Listener stack is built 1/2 upside down and strange inhibiting name service and other transport filters
* [ETCH-63] - Change maven groupId to "org.apache.etch" from "etch.etch"
-** New Feature
- * [ETCH-15] - design and implement a framework for interoperability testing,
- plus a simple demonstration test
+New Feature
+
+ * [ETCH-15] - design and implement a framework for interoperability testing, plus a simple demonstration test
+ * [ETCH-64] - Implement the compiler portion of the c-binding, to generate code for the etch c runtime
+ * [ETCH-65] - Integrate the c-binding into the windows build.
+ * [ETCH-66] - Port the c-binding to linux, resolve differences between windows and linux.
+ * [ETCH-79] - Implementation of Etch C Binding (Runtime + Compiler)
-** Task
+Task
+
+ * [ETCH-4] - Map http://cwiki.apache.org/ETCH to http://incubator.apache.org/etch
* [ETCH-22] - Change Java (and C#) package names to org.apache.etch
* [ETCH-32] - import the c binding
* [ETCH-35] - import the python binding
* [ETCH-38] - import interoperability tester
* [ETCH-44] - put header comments in order per apache standard
* [ETCH-49] - merge changes from 1.0.2 branch to trunk
- * [ETCH-70] - Rename jar file build products to include incubating in the
- name.
+ * [ETCH-70] - Rename jar file build products to include incubating in the name.
* [ETCH-71] - repair license header in c binding
* [ETCH-72] - repair license header in interop tester
* [ETCH-73] - repair license header in tests
* [ETCH-74] - repair license header in scripts
+ * [ETCH-81] - Setup CMake based build environment for C binding
+ * [ETCH-82] - Merge etch-c into trunk
+ * [ETCH-83] - Setup Hudson Build Configuration for continous Etch builds
+ * [ETCH-84] - Provide getting started Setup documentation
+ * [ETCH-85] - Provide Documentation for Examples
+ * [ETCH-86] - Provide 1.1. release package
+ * [ETCH-87] - Provide 1.1. release package for Win32 + Installer
+ * [ETCH-88] - Provide 1.1. release package for Linux
+ * [ETCH-89] - Extend C# and Java Compilers to generate Wireshark keyfiles
+ * [ETCH-90] - Ant Build using ETCH_EXTERNAL_DEPENDS
+ * [ETCH-91] - Clean up / re-create examples/HelloWorld for all bindings
+ * [ETCH-92] - Integrate C binding to NSIS installer and packaging
+ * [ETCH-94] - Provide Documentation for Etch's binary protocol
+ * [ETCH-97] - Add public PGP KEY (CODE SIGNING KEY) to etch KEYS (fitzner)
+ * [ETCH-98] - Add CMake makefiles to exambles for binding-c
+ * [ETCH-100] - update BUILD.txt on top level
+ * [ETCH-101] - Integrate HelloWorld C Binding example into top level ant build
+ * [ETCH-103] - Add documentation regarding APR_ICONV_PATH to documentation
+ * [ETCH-104] - Create NOTICE_THIRD_PARTY.txt and LICENSE_THIRD_PARTY.txt
+
+Test
+
+ * [ETCH-96] - Change CWiki etch confluence template
Here are the outstanding bugs in this release: