Source Beach C++ Foundation

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

Copyright 1996-2017 (c) Alkaline Games LLC

This Source Code Form is subject to the terms of the Mozilla Public
License, v. 2.0. If a copy of the MPL was not distributed with this
file, You can obtain one at http://mozilla.org/MPL/2.0/.

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

Beach is a group of C++ packages 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 packages.

---

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 generation. The build system currently supports and runs on the following platforms:

- gcc 4.2.1 on FreeBSD for amd64 or i386 
- gcc 4.2.1 on (Mac) OS X Lion 10.7.5 for x86_64
- gcc 4.4.5 on GNU/Linux for x86_64 or x86
- gcc 4.5.0 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.

Building the unit tests relies on the CppUnit project which has been included in the dep/cppunit subdirectory. 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 package test/ C++ unit test source, by package

---

packages

The Beach C++ Foundation forms the most fundamental layer of a multilayer architecture for building portable applications in C++. These packages 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 packages, their purpose, and some of the design pattern implementations they include:

1. Atoms: fundamental typedefs and simple objects.

2. Chain: linked-list based object association patterns: Encapsulated Context, Extension Object

3. Collection: enhanced, reference-based STL containers. patterns: Iterator

4. Expression: regular expression parsing. (currently forked from the public domain SPLASH code).

5. Geometry: geometric constructs and calculations.

6. Invocation: dynamic method invocation. patterns: Command

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

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

9. Serialization: mechanisms for externalizing object state. patterns: Serializer

10. Taxonomy: type-semantics, a.k.a. meta level support. patterns: Dynamic Object Model, Property List, Reflection, Type Object

---

The packages are layered with the following dependencies:

  taxonomy
    |              
    \--> serialization
    |      |       
    \----- \--> notification
    |      |      |
    \----- \----- \--> lifecycle
    |      |      |      |   
    \----- \----- \----- \--> invocation
    |      |      |      |      |
    |      |      |      |      |    geometry
    |      |      |      |      |      |  
    |      \----- | ---- \----- \----- \--> expression
    |      |      |      |      |      |      |       
    \----- \----- \----- \----- \------------ | --> collection
    |      |      |      |      |      |      |       |
    \----- \----- \----- \----- | ---- | ---- | ----- | --> chain
    |      |      |      |      |      |      |       |       |
    \----- \----- \----- \----- \----- \----- \------ \------ \---> atoms

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