File	Date	Author	Commit
build	2009-07-15	arcwf	[835117] build modified to NOT use STLport by default an...
dep	2009-07-08	arcwf	[354b7f] first add of build/, dep/, and top-level files
LICENSE	2009-07-08	arcwf	[354b7f] first add of build/, dep/, and top-level files
NOTICE	2009-07-08	arcwf	[5835d2] diagnostics framework elminated; logger classes...
README	2009-07-15	arcwf	[835117] build modified to NOT use STLport by default an...
doxyfile	2009-07-08	arcwf	[354b7f] first add of build/, dep/, and top-level files
make_include_parent	2009-07-15	arcwf	[835117] build modified to NOT use STLport by default an...
makefile	2009-07-08	arcwf	[354b7f] first add of build/, dep/, and top-level files

Read Me

===============================================================================

   Copyright 1996-2009 (c) World Fusion (r)

   Licensed under the Apache License, Version 2.0 (the "License");
   you may not use this file except in compliance with the License.
   You may obtain a copy of the License at

       http://www.apache.org/licenses/LICENSE-2.0

   Unless required by applicable law or agreed to in writing, software
   distributed under the License is distributed on an "AS IS" BASIS,
   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
   See the License for the specific language governing permissions and
   limitations under the License.

===============================================================================

Beach C++ Frameworks

Beach is a group of C++ frameworks that are 100% platform independent,
implementing many useful object-oriented design patterns and general
purpose mechanisms that provide the fundamental building blocks for
applications and higher level frameworks.

------
source
------

The C++ source code depends only on ISO Standard C++ and its standard
libraries. The source code may contain conditional compilation
preprocessor directives in a few places, but only for coping with
specific compiler idosyncracies where necessary, not to distinguish
operating systems. The source code should be compatible with any ISO
Standard C++ compiler, however, the GCC (GNU Compiler Collection) C++
is the preferred and intended tool set.

Much of the source code has been documented with Doxygen markup. HTML
files can be generated by running 'doxygen' at the project directory.

Unit test coverage is far and few between. We hope to increase this
greatly over time along with complete Doxygen coverage.

The Beach project is the foundation of a larger code base for a project
of epic proportions that has evolved over many years. During that time,
new naming and style conventions were adopted, but not all of the code
has yet been rennovated to these newer standards. Rennovation has
mostly only been done when existing code needed to be changed for
functional purposes. With this code being released to the public,
we hope to make the code base more consistent and eliminate
redundancies.

--------
building
--------

Only the C++ source code is platform independent, not the build system.
The accompaning build system scripts and configuration (make) files
are designed for GNU make (gmake). The Beach build system is quite
minimal at this time, lacking auto-configure, auto-make, and dependency
generatione. The build system currently supports and runs on the
following platforms:

    - gcc 4.2.1 on FreeBSD for amd64 or i386 
    - gcc 4.1.2 on GNU/Linux for x86_64 or x86
    - gcc 3.4.5 on MinGW for Win32

Other versions of GCC are yet unverified and thus may or may not be
supported.

Building and using the libraries does not rely on any other project
beyond the C++ toolset. Nevertheless, a compatible version of STLport
is included in the dep/stlport subdirectory and beach can be built to
use it by defining the make variable OCEAN_STLPORT (see
make_include_parent). In that case you must first build STLport for
your platform by running the 'shbuild' script in dep/stlport.

Building the unit tests relies on the CppUnit project which has also
been included in the dep/cppunit subdirectory. Likewise, you must first
build CppUnit for your platform by running the 'shbuild' script in
dep/cppunit. 

Ocean is the pseudo-project name of the collection of open source
projects that Beach and Coast depend on.

--------------
subdirectories
--------------

build/  build support (make include files)
dep/    project dependencies (a.k.a. Ocean)

dox/    generated Doxygen documentation
out/    generated libraries and intermediate files
run/    generated executable targets (unit tests)

src/    C++ source, by framework
test/   C++ unit test source, by framework

----------
frameworks
----------

The Beach C++ Frameworks form the most fundamental layer of a
multilayer architecture for building portable applications in C++.
These frameworks provide rudimentary objects that are domain (subject
matter) and platform independent. The design and implementation of
every piece of code is purely object-oriented, not just C++ wrappers
around a functional/structural design. Many widely used design patterns
are implemented with names and structure that is consistent with the
published pattern literature. Many of the design pattern
implementations have significant enhancements from years of practical
application. The following is a list of the current frameworks, their
purpose, and some of the design pattern implementations they include:

1. Atoms: typedefs and simple objects.
       patterns: Encapsulated Context, Extension Object

2. Collections: enhanced, reference-based STL collections.
       patterns: Iterator

3. Externalization: mechanisms for externalizing object state.
       patterns: Serializer

4. Invocation: dynamic method invocation.
       patterns: Command

5. Lifecycle: object life-cycle mechanisms.
       patterns: Counted Pointer, Diagnostic Logger, Handle/Body,
                 Identity Field, Name, Object Registry

6. Math: support for 3-D calculations.

7. Notification: inter-object communication.
       patterns: Forwarder/Receiver, Observer

8. Splash: regular expression parsing.
       (forked from the public domain SPLASH code that is
        no longer supported anywhere).

----------------------

The frameworks are layered with the following dependencies:

  externalization
    |              
    \---> notification
    |       |
    \-------\---> lifecycle
    |       |       |   
    \-------\-------\---> invocation
    |       |       |       |
    \-------\-------\-------\---> collections
    |       |       |       |       |
    \------ \-------\-------\------ | --> splash
    |       |       |       |       |       |
    |       |       |       |       |       |     math
    |       |       |       |       |       |       |
    \-------\-------\-------\-------\-------\-------\---> atoms

===============================================================================
(end of document)