UNMAINTAINED

This library is unmaintained.

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

Purpose

Base library for BBC Audio Toolbox

Contains miscellaneous debug, file and position functions

Dependencies

jsoncpp - https://github.com/open-source-parsers/jsoncpp (see Notes on Windows builds, below)

Files

autogen.sh - simple autotools script
bbcat-common - a set of common files for all bbcat-* libraries (will be installed by CMake to /usr/local/share)
CMakeLists.txt - CMake configuration
configure.ac - configure configuration for autotools
COPYING - information on copying this library
debian/ - Debian control and version information
doxygen.am - Doxygen automake file
doxygen.cfg - Doxygen configuration
m4 - folder for autotools
Makefile.am - makefile for automake
README - this file
src/ - source folder containing C/C++ source and header files
test/ - unit test files

bbcat-common/CMakeLibrary.txt			| Common CMake configuration for the libraries

bbcat-common/CMakeProject.txt			| Common CMake configuration for all projects

bbcat-common/Config.cmake.in			| Input files for CMake .cmake configuration file auto-generation
bbcat-common/ConfigVersion.cmake.in		|

bbcat-common/FindPortAudio.cmake		| Various CMake file utilities
bbcat-common/FindThreads.cmake			|
bbcat-common/FindwxWidgets.cmake		|

bbcat-common/findregisterfunctions.sh	| Shell script to auto-generate the register.cpp file

bbcat-common/include/catch/catch.hpp	| Catch unit testing framework

bbcat-common/pkgconfig.in				| Input file for pkg-config auto-generation

src/3DPosition.cpp                      | 3D position, rotation and transformation classes
src/3DPosition.h                        |

src/BackgroundFile.cpp                  | A class derived from EnhancedFile that allows writing to file in a background thread
src/BackgroundFile.h                    |

src/ByteSwap.cpp                        | Byte swapping for endianness control
src/ByteSwap.h                          |

src/CallbackHook.h                      | A simple callback object for sequenced callbacks

src/CMakeLists.txt						| CMake configuration for source files

src/DistanceModel.cpp                   | A model for level and delay calculations based on distance 
src/DistanceModel.h                     |

src/EnhancedFile.cpp                    | A wrapper for FILE * operations which provides some extra functionality 
src/EnhancedFile.h                      |

src/json.cpp                            | Abstraction and support for JSON
src/json.h                              |

src/LoadedVersions.cpp					| A singleton class to hold a list of the loaded versions of libraries and applications
src/LoadedVersions.h					|

src/LockFreeBuffer.h                    | A simple lock-free circular buffer mechanism

src/Makefile.am                         | Makefile for automake

src/misc.cpp                            | Miscelleanous functions and definitions, especially debugging functions
src/misc.h                              |

src/NamedParameter.cpp					| An interface, template and macro that create a named parameter with an optional default value with JSON support
src/NamedParameter.h					|

src/ObjectRegistry.cpp                  | A register of objects that can create themselves (see SelfRegisteringParametricObject.h)
src/ObjectRegistry.h                    |

src/OSCompiler.h                        | Header for determining compiler and OS

src/ParameterSet.cpp                    | A generic key=value handler with operators and comparators
src/ParameterSet.h                      |

src/PerformanceMonitor.cpp              | A multi-point logging runtime performance monitor (with outputs suitable for gnuplot)
src/PerformanceMonitor.h                |

src/RefCount.h							| A simple ref-counting template that allows easy ref-counting object support

src/SelfRegisteringParametricObject.cpp | A base class for objects that can be created from a textual name and parameters (using ParameterSet objects)
src/SelfRegisteringParametricObject.h   |

src/SystemParameters.cpp				| A global registry for system level parameters and paths
src/SystemParameters.h					|

src/Thread.cpp							| Simple thread class that can run a thread via a derived class or callback
src/Thread.h							|

src/ThreadLock.cpp                      | Thread locking classes
src/ThreadLock.h                        |

src/UDPSocket.cpp                       | Simple UDP transmitter/receiver
src/UDPSocket.h                         |

src/UniversalTime.h                     | A simple fraction based timebase with arbitrary numerator and denominator

src/WindowsNet.h						| Windows networking initialisation

src/Windows_uSleep.cpp					| Windows implementation of usleep()
src/Windows_uSleep.h					|

src/register.cpp						| Registration function (see below)

test/CMakeLists.txt						| CMake configuration for tests

test/Makefile.am						| Makefile for automake 

test/jsontests.cpp						| Tests for JSON

test/stringfromtests.cpp				| Tests for StringFrom() functions

test/testbase.cpp						| Test base file

--------------------------------------------------------------------------------
Initialising the Library (IMPORTANT!)

Compilers are clever and try to remove unused code whilst linking applications.
However, sometimes they are too clever and remove some code that *appears* not
to be used but is.  Uses of the SelfRegisteringParametricObject class may
particularly suffer from this as it appears as though nothing is using the
code.

To stop this, each library includes a register.cpp file which explicitly calls a
set of initilisation and registration functions. This file also calls the
registration functions of any libraries it is dependant upon.

For this to work, any application *must* call the registration function of most
dependant library it uses.

For example, for an application using only this library:
#include <bbcat-base/register.h>

using namespace bbcat;

int main(int argc, char *argv[])
{
  // ensure libraries are set up
  bbcat_register_bbcat_base();
}

register.cpp is included in repo but will be updated by the script
bbcat-common/findregisterfunctions.sh if autotools is used.  The CMake process
is also capable of autogenerating this file if the original in the source
directory does not exist.

--------------------------------------------------------------------------------
Building on Windows (Visual Studio)

Download and install CMake (https://cmake.org/download/) *first*
Download and install git (https://git-scm.com/download/win)

Use git-bash to change to the directory where the libraries are to be cloned to

Clone source code, if necessary:
git clone git@github.com:bbcrd/bbcat-base.git

cd bbcat-base
mkdir build
cd build
cmake -G "Visual Studio 14 2015 Win64" .. && cmake --build . --target INSTALL --config Release
(or whatever version of Visual Studio you are using)

Notes on Windows builds

As there is no standardised directories for cmake files, libraries, etc. the build *assumes* that:
1. Library includes, libs and shared files will be stored in c:\local
2. CMake configuration files will be stored in c:\local
3. http://sourceforge.net/projects/pthreads4w/ has been downloaded and extracted to c:\local\pthreads (rename unzip folder to 'pthreads')
4. For JSON support:
4.1. Download the source code, use CMake to generate a solution and build it as x64/Release (install may fail due to privileges)
4.2. Find the .lib file (e.g. in build\src\lib_json\Release) and copy it to c:/local/lib (creating that directory if necessary)
--------------------------------------------------------------------------------

--------------------------------------------------------------------------------
Building on Mac and Linux

There are two build mechanisms supported: autotools and cmake

autotools:
./autogen.sh && configure && make && sudo make install

cmake:
mkdir build ; cd build ; cmake .. && make && sudo make install
--------------------------------------------------------------------------------

--------------------------------------------------------------------------------
Building without cmake or autotools

Using the libraries with other build environments is possible, simply throw the
files into the build environment BUT certain defines must be set to enable
features.

bbcat-base uses the following defines:
ENABLE_JSON=1 		 - enables json support
OLD_JSON_CPP  		 - define if old version of jsoncpp (version 0.6.0, for example) used
_FILE_OFFSET_BITS=64 - enable 64-bit file operations
INSTALL_PREFIX=...   - locations of installation (e.g. /usr/local, c:/local, etc)
USE_PTHREADS         - define if using pthreads rather than std::thread
--------------------------------------------------------------------------------