_______________________________________________________________________________
Copyright (c) 2010 by Maren Enterprises, Inc.
All rights reserved
Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions are met:
- Redistributions of source code must retain the above copyright notice,
this list of conditions and the following disclaimer.
- Redistributions in binary form must reproduce the above copyright notice,
this list of conditions and the following disclaimer in the documentation
and/or other materials provided with the distribution.
- Neither the name Maren Enterprises, Inc., nor the names of its contributors
may be used to endorse or promote products derived from this software
without specific prior written permission.
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
POSSIBILITY OF SUCH DAMAGE.
File: README
Author: Randall A. Maddox (maddoxr@acm.org)
Description: Top level README file for RAM library.
_______________________________________________________________________________
Welcome to the RAM library for C++ developers. As you can see from the above,
the RAM library is available under the BSD License, as approved by the Open
Source Initiative (www.opensource.org). The project itself is hosted on
SourceForge (sourceforge.net/projects/ramlibrary/) and is available there as
a .zip file. It is also available via subversion at:
http://ramlibrary.svn.sourceforge.net/svnroot/ramlibrary.
My goal for the RAM library is to provide C++ developers with some, hopefully,
useful bits of code, and to improve the usefulness of those bits over time as
more developers work with them. My other goal is to have fun writing code and
seeing it get some use.
The name RAM can be taken as "Randy At Maren" since Maren Enterprises is the
company I work for. Or it could be taken as my initials. In any case, it
makes a nice short tag for the namespace the RAM library code lives in.
The code, and documentation, resides in the following directory structure.
ram_lib - base of directory tree
|
+- branches - branched releases, if any
|
+- tags - each tagged version release
|
+- trunk - main line of development
|
+- docs - text file for each component
|
+- inc - subdirectory for each component's header files
|
+= make - for building RAM library test code
|
+- out - for building RAM library test code
|
+- src - subdirectory for each component's source files
|
+- test - for building RAM library test code
If you download the .zip file you get an exported copy of one of the tagged
release versions ram_lib/trunk directory structure. A tagged release is a
snapshot of the mainline development trunk directory that is internally
consistent.
If you check out the source from its Subversion repository you can get any
tagged version you want, or the trunk mainline development in progess. If
you work with the trunk mainline development version, it should always build,
but some parts of it may still be under development and testing.
Suggested usage is to install the RAM library as shown above and set your
compiler include path to point to .../trunk/inc. Then include header files
as needed using the following form as an example:
#include <Log/Log.hpp>
The next place to look is the docs directory where you will find a text file
describing each component of the RAM library. That document will begin with
a quick start usage guide that says whether the component is header file only,
or not. If it is not, then you will need to compile and linke the associated
.cpp files with your application that uses that component.
NOTE: External documentation in .txt files explains concepts, design, intended
use, etc. But the header file is where details on calling parameters, return
value, and error handling are found. So the .txt files are like an overview,
while the header files are the reference manual.
The general scheme is that each component has:
- a subdirectory in the .../inc directory that contains its public header files
- a text file in the .../docs directory with the same name and a .txt
extension that describes the component and its intended use.
- for components that are not header-file-only, a subdirectory in the .../src
directory containing the .cpp source file(s) that need to be compiled and
linked with your application using that component.
- a subdirectory in the .../test directory that contains the test driver used
to test the component.
- a subdirectory in the .../make directory that contains the Makefile used
to build the test driver for the component.
As an example, consider the Log class, which is described in docs/Log.txt,
has its header files in inc/Log/*.hpp, its source files in src/Log/*.cpp, and
its test driver in test/Log/TestLog.cpp.
Since the Log component does have a src/Log subdirectory, it is not a header-
file-only component, and the src/Log/*.cpp files must be compiled and linked
with your application that uses class Log.
Components that are header-file-only have no corresponding subdirectory in the
src directory. So if there is no corresponding src subdirectory you will know
that component is header-file-only and there are no *.cpp files that need to
be compiled and linked with your application thst uses that component.
All this code has been tested, using the test drivers provided, under Mac OS X,
OpenSUSE Linux, and Ubuntu Linux, using the GCC toolchain and valgrind to test
for memory errors (www.valgrind.org). The code has also been tested on
Windows XP using the MS VC++ tool chain.
If you find any bug not caught by that testing, please do drop me an email
describing the bug so it can be fixed and the tests updated.
All test drivers return EXIT_SUCCESS if and only if the expected number of
tests complete, and all tests that complete pass. Otherwise EXIT_FAILURE is
returned.
In the .../trunk/make directory are two scripts to aid with testing, with the
non-.bat form of the name for Mac OS X, Linux and Unix, and the .bat form for
Windows:
BuildAndRunTests[.bat] - Builds and runs all RAM Library test drivers.
Returns zero if everything completes with no error.
CleanAll[.bat] - Cleans up everything generated by the above script.
NOTE: On Windows be sure to run vcvars[32,64].bat to set environment
variables appropriately for command-line build.
NOTE: The BuildAndRunTest[.bat] script automatically copies over the right
file into Makefile.base. Manually that would be:
For Mac OS X, Linux, Unix -> cp Makefile.NIX Makefile.base
For Windows -> copy Makefile.WINDOWS Makefile.base
The lower level Makefiles that include Makefile.base need no other change.
Enjoy.
Randy Maddox
March 2010
BTW, I am available for corp-to-corp contract software engineering work.
Drop me an email if you want more information.
# end of this file
