1 Introduction
==============

BlitzMax Extended is an attempt to clean up and improve
the core runtime to ease and guide development.

Summarized the changes include renamed non-public variables
and functions to improve readability, additional API as well
as low-level functions to provide more control over internal
processes, implementation of all classes in C for faster
execution as well as easier interfacing from C/C++.

For the complete list of changes from the official BRL version
please see the file 'CHANGES.txt'.


2 Directory Structure
=====================

asm	Contains all assembly files for the specific platform
c	Contains all C files that implement the runtime API of BlitzMax
src	BlitzMax source files used for documentation (bbdoc)
doc	BlitzMax documentation files
docs	C API documentation (doxygen)

3 Configuration
===============

In the file 'blitz.bmx' you find two 'ModuleInfo' commands that
can be used to configure the build.

BB_ENABLE_EXPERIMENTAL	(default: off)

	Changes to the runtime to make it faster.

	Might cause problems with legacy code when enabled.

BB_DISABLE_DEPRECATED	(default: off)

	Removes functionality that is considered to be outdated, unused or
	was RENAMED to be more coherent with the naming scheme.

	e.g BBRETAIN(obj) is now BB_RETAIN(obj)

	Might cause problems with legacy code when enabled.


4 Requirements
==============

To compile this module, you need the usual BlitzMax toolchain
with a recent version of the GCC (with C99 support).

NOTE: Some macros may not be available when not using the GCC.

To build the C documentation you need doxygen (www.doxygen.org)


Changes
=======

The changes below are in no way a complete list. Only the most important ones,
that affect handling of the API are named here.

Assembly
--------

- moved all assembly files to 'asm' directory

C API
-----

- changed all function parameters to constant pointers where possible
- added documentation for doxygen (in 'docs' directory)
- moved all C related files to 'c' directory
- added file 'blitz_macros.h' to include checking and general purpose
  macros used throughout the module
- added file '_common.h' that includes standard library headers
- moved 'BBClass' definition from 'blitz_object.h' to 'blitz_class.h'


blitz_app.h

	- changed initial value of 'bbAppTitle' to be compile time object

blitz_array.h

	- added macros to ease working with arrays
	 e.g. BBARRAY_SIZE(), BBARRAY_DATAPTR()
	  
	- added helper structures for the specific array type
	  BBByteArray, BBShortArray, BBIntArray, BBLongArray,
	  BBFloatArray, BBDoubleArray, BBObjectArray, BBStringArray, BBArrayArray
	- added functions bbArrayEquals and bbArrayClone
	- added function bbArrayReverse
	- added function bbArrayRotate
	- added functions bbArrayFindInt, bbArrayFindLong, bbArrayFindFloat,
	  bbArrayFindDouble, bbArrayFindObject, bbArrayFindString
	- added functions bbArrayStartsWith and bbArrayEndsWith

blitz_class.h

	- added named virtual function 'Clone' to the BBClass struct
	- changed type of 'instance_size' member to BBSize
	- renamed bbObjectRegisterType to bbClassRegister
	- renamed bbObjectRegisteredTypes to bbClassAllRegistered
	- added function bb_class_register_multiple
	- added check for maximum number of registered classes in debug mode
	- added check for maximum instance size of a class in debug mode

blitz_debug.h

	- changed type of 'local_offset' and 'global_offset' members of
	  BBDebugDecl's union to unsigned int
	- added BB_ASSERT macro and bb_assert function that give more detailed information
	- deprecated bbassert macro

blitz_gc.h

	- added enum BBGCMode (BBGC_AUTOMATIC, BBGC_MANUAL and BBGC_AGGRESSIVE)
	- added bbGCGetMode
	- added enum BBGCDebugMode (BBGC_NODEBUG, BBGC_STDOUTDEBUG)
	- added enum BBGCAllocFlags (BBGC_DEFAULT, BBGC_ATOMIC, BBGC_FINALIZE)
	- changed 'size' parameter of bbGCMalloc and bbGCAllocObject to type BBSize
	- added a check for maximum number of suspensions for GC
	- added bbGCIsSuspended
	- renamed BBRETAIN(), BBRELEASE(), BBINCREFS() and BBDECREFS() to
	  BB_RETAIN(), BB_RELEASE(), BB_INCREFS() and BB_DECREFS() respectively
	- changed 'size' parameter of bbGCDeallocObject to type BBSize

blitz_incbin.h

	- added check for maximum file size to bbIncbinAdd
	- changed 'size' param of bbIncbinAdd to type BBSize
	- changed return type of bbIncbinLength to BBSize

blitz_macros.h

	- added BB_BEGIN_DECLS and BB_END_DECLS for usage from C++
	- added BB_OS_LINUX, BB_OS_MACOS, BB_OS_WIN32, BB_CPU_PPC, BB_CPU_X86 for
	  BlitzMax-like compile-time checking
	- added BB_DEBUG and BB_THREADED to check compilation mode

blitz_memory.h

	- added check for maximum allocation size to bbMemAlloc in debug mode

blitz_object.h

	- added generic function bbObjectClone
	- moved BBClass to blitz_class.h

blitz_string.h

	- added macros to ease working with strings,
	  e.g. BBSTRING_SIZE(), BBSTRING_ALLOC()
	- changed type of 'length' member of BBString to BBSize
	- added check for maximum string length in all creating functions
	  via BB_ASSERT() and reduction to maximum length when created
	- added enum BBStringSide (BBSTRING_SIDE_BOTH, BBSTRING_SIDE_LEFT and BBSTRING_SIDE_RIGHT)
	- added parameter 'side' to bbStringTrim
	- added BBSTRING_NOTFOUND for convenience
	- added function bbStringClone
	- added function bbStringEquals
	- added function bbStringCount
	- added function bbStringReverse
	- added function bbStringTimes
	- added function bbStringSub
	- added function bbStringFindAll
	- added function bbStringFindAny
	- added function bbStringIsLower
	- added function bbStringIsUpper
	- added function bbStringIsASCII

blitz_thread.h

	- renamed BB_THREADREGS to BBTHREAD_NUM_REGS
	- (experimental) replaced helper macros with inline functions
	  e.g. bb_mutex_init

blitz_types.h

	- added BBByte, BBShort, BBInt, BBLong, BBFloat and BBDouble types
	- deprecated BBBYTE, BBSHORT, BBINT, BBLONG, BBFLOAT, BBDOUBLE,
	  BBCLASS, BBOBJECT, BBSTRING and BBARRAY types
	- added BBBool convenience type (compatible with BBInt)
	- added BBSize convenience type (compatible with BBInt)
	
blitz_unicode.h

	- moved bbToLowerData and bbToUpperData to blitz_unicode.c