revised the documentation

git-svn-id: https://svn.grrrr.org/ext/trunk@958 4d9ac71a-51e6-0310-8455-cad1006bcd31

AUTHORS

-Thomas Grill
\ No newline at end of file
+Thomas Grill (gr@grrrr.org)

INSTALL

+These are instructions for the autoconf building system.
+For the native flext build system, please see the build.txt document.
+
+-----------------------------------------------------------------------
+
 Basic Installation
 ==================
 

NEWS

+see changes.txt

build.bat

-@set flext=%~dp0
-
-@rem Arguments:
-@rem %1 - platform (win/lnx/mac)
-@rem %2 - system (pd/max)
-@rem %3 - compiler (msvc/gcc/mingw/cygwin/bcc/icc)
-@rem %4 - target (build/clean/install)
-
-@set platform=%1
-@set rtsys=%2
-@set compiler=%3
-@set target=%4
-
-@rem --- The subbatch knowns which make utility to use ---
-@set subbatch=%flext%buildsys\build-%compiler%.bat
-
-@if "%platform%"=="" @goto syntax
-@if "%rtsys%"=="" @goto syntax
-@if "%compiler%"=="" @goto syntax
-
-@if not exist %subbatch% @goto syntax
-
-@call %subpatch% %subbatch% %platform% %rtsys% %target% %5 %6 %7 %8 %9
-
-@goto end
-
-@rem -----------------------------------------
+@echo off
+
+rem
+rem flext - C++ layer for Max/MSP and pd (pure data) externals
+rem
+rem Copyright (c) 2001-2005 Thomas Grill (gr@grrrr.org)
+rem For information on usage and redistribution, and for a DISCLAIMER OF ALL
+rem WARRANTIES, see the file, "license.txt," in this distribution.  
+rem
+rem more information on http://grrrr.org/ext
+rem ------------------------------------------------------------------------
+rem
+rem To build flext or flext-based externals simply run this script.
+rem Running it without arguments will print some help to the console.
+rem
+rem ------------------------------------------------------------------------
+
+set flext=%~dp0
+
+rem Arguments:
+rem %1 - platform (win/lnx/mac)
+rem %2 - system (pd/max)
+rem %3 - compiler (msvc/gcc/mingw/cygwin/bcc/icc)
+rem %4 - target (build/clean/install)
+
+set platform=%1
+set rtsys=%2
+set compiler=%3
+set target=%4
+
+rem --- The subbatch knowns which make utility to use ---
+set subbatch=%flext%buildsys\build-%compiler%.bat
+
+if "%platform%"=="" goto syntax
+if "%rtsys%"=="" goto syntax
+if "%compiler%"=="" goto syntax
+
+if not exist %subbatch% goto syntax
+
+call %subpatch% %subbatch% %platform% %rtsys% %target% %5 %6 %7 %8 %9
+
+goto end
+
+rem -----------------------------------------
 :syntax
 
-@echo .
-@echo SYNTAX: build [platform] [system] [compiler] {target}
-@echo platform ... win / lnx / mac
-@echo system   ... pd / max
-@echo compiler ... msvc / gcc / mingw / cygwin / bcc / icc
-@echo target   ... all (default) / clean / install
-@echo .
-@echo Please make sure that your make program and compiler can be accessed with the
-@echo system path and that all relevant environment variables are properly set.
-@echo .
+echo .
+echo SYNTAX: build [platform] [system] [compiler] {target}
+echo platform ... win / lnx / mac
+echo system   ... pd / max
+echo compiler ... msvc / gcc / mingw / cygwin / bcc / icc
+echo target   ... all (default) / clean / install
+echo .
+echo Please make sure that your make program and compiler can be accessed with the
+echo system path and that all relevant environment variables are properly set.
+echo .
 
 :end

build.sh

-#! /usr/bin/bash
+#! /bin/bash
+
+# flext - C++ layer for Max/MSP and pd (pure data) externals
+#
+# Copyright (c) 2001-2005 Thomas Grill (gr@grrrr.org)
+# For information on usage and redistribution, and for a DISCLAIMER OF ALL
+# WARRANTIES, see the file, "license.txt," in this distribution.  
+#
+# more information on http://grrrr.org/ext
+# ------------------------------------------------------------------------
+#
+# To build flext or flext-based externals simply run this script.
+# Running it without arguments will print some help to the console.
+#
+# ------------------------------------------------------------------------
 
 flext=${0%/*}/
 if [ "$flext" = "$0"/ ]; then flext=./ ; fi

build.txt

+flext - C++ layer for Max/MSP and pd (pure data) externals
+
+Copyright (c) 2001-2005 Thomas Grill (gr@grrrr.org)
+For information on usage and redistribution, and for a DISCLAIMER OF ALL
+WARRANTIES, see the file, "license.txt," in this distribution.  
+
+----------------------------------------------------------------------------
+
+This document consists of the following parts:
+
+1) Using the flext build system
+1.1) Building flext
+1.2) Building externals
+
+2) Using autoconf
+
+3) Other ways to compile flext and flext-based externals
+
+----------------------------------------------------------------------------
+
+1) Using the flext build system
+===============================
+
+flext provides a universal build system which supports
+
+- various operating systems
+	Windows (win)
+	Linux (lnx)
+	MacOSX (mac)
+- various real-time systems
+	Pure Data (pd)
+	Max/MSP (max)
+- various make programs
+	GNU make (gnumake)
+	Microsoft nmake (nmake)
+	Borland make (bmake)
+- various compilers
+	Microsoft Visual C/C++ 6.0 or .NET 2002/2003 (msvc)
+	GNU gcc 2.95 and above (gcc,cygwin,mingw)
+	Borland bcc32 (bcc)
+
+Useful combinations of the above are
+
+win pd msvc, using nmake
+win pd cygwin, using gnumake
+win pd mingw, using gnumake
+win max msvc, using nmake
+win pd bcc, using bmake
+mac pd gcc, using gnumake
+mac max gcc, using gnumake - Mach-O externals only (Max 4.5 upwards)
+
+
+There are two central scripts in the flext folder which invoke the building process:
+- build.sh for bash shells (Linux, MacOSX, cygwin)
+- build.bat for the Windows command prompt
+
+A project needs to provide some information in order to be built properly.
+By default, this resides in a file called package.txt
+
+
+Please note, that the build system is shell-oriented, which means, that you'll have
+to launch a command prompt (cmd.exe under Windows) and probably also set some
+environment variables for your development system (e.g. run vcvars32.bat for Microsoft Visual Studio)
+
+By invoking one of the build scripts (e.g. with "bash build.sh" under unix, 
+or just "build" unter Windows) you'll get some lines of help.
+Operating System, real-time system and compiler need to be provided as arguments.
+
+
+See buildsys/readme.txt for developer-centered information.
+
+
+1.1) Building flext
+===================
+
+Flext can build itself using the build system.
+From the flext main directory, run the build script
+
+e.g. under Windows
+	build win pd msvc
+or under unix with
+	bash build.sh lnx pd gcc
+
+When you run it for the first time, one or more configuration files will be created 
+from templates - you will get a message on the console. 
+You should edit the files to adapt it to your system.
+
+Then install flext with (under Windows)
+	build win pd msvc install
+or (under unix)
+	bash build.sh lnx pd gcc install
+
+
+1.2) Building externals
+=======================
+
+The flext build system can be used to compile flext-based externals or also
+native PD and Max/MSP externals, provided there is a package.txt file in the project folder.
+
+In the shell, change to the project folder.
+Then, simply run the flext build script, 
+
+e.g. under Windows
+	..\flext\build win pd msvc
+Then install your newly built external with
+	..\flext\build win pd msvc install
+
+or under unix with
+	bash ../flext/build.sh lnx pd gcc
+Then install your external with
+	bash ../flext/build.sh lnx pd gcc install
+
+
+----------------------------------------------------------------------------
+
+2) Using autoconf
+=================
+
+Thanks to Tim Blechmann, flext can also be built using autoconf.
+This only works under unix shells.
+
+When starting from a fresh cvs-based copy of flext first run
+./bootstrap.sh
+
+then you can run
+./configure --help 
+to get a page of options.
+
+You need to pass the path to the PD source files to the ./configure script, e.g. with
+./configure --with-sysdir=/usr/local/src/pd/src
+
+Then build flext with
+make
+and install it with
+su -c "make install"
+
+----------------------------------------------------------------------------
+
+3) Other ways to compile flext and flext-based externals
+========================================================
+
+- Windows - Microsoft Visual Studio projects (.vcproj files)
+
+Please have a look at the projects delivered with flext and flext-based externals.
+
+
+- MacOSX - Apple Xcode projects (.xcode bundles)
+
+Please have a look at the projects delivered with flext and flext-based externals.
+
+
+- MacOSX - Metrowerks Codewarrior (.mcp files)
+
+You should have the following "Source Trees" (CW preferences, not project specific!) defined:
+"OS X Volume" - Pointing to your OSX boot drive
+"flext" - Pointing to the flext main directory
+"Cycling74 OSX" - Pointing to the SDK for Max/MSP - the path should end with /c74support
+
+With your project using flext use the prefix file "flcwmax-x.h" or, 
+alternatively "flcwmax-x-thr.h" for threading support.
+
+
+- MacOS9 - Metrowerks Codewarrior (.mcp files)
+
+You should have the following "Source Trees" (CW preferences, not project specific!) defined:
+"flext" - Pointing to the flext main directory
+"Cycling74" - Pointing to the Cycling 74 SDK
+"MP SDK" - Pointing to the Multiprocessing SDK (for threading support)
+
+With your project using flext use the prefix file "flcwmax.h" or, 
+alternatively "flcwmax-thr.h" for threading support.

buildsys/build-cygwin.sh

-#!/usr/bin/bash
+#! /bin/bash
 
 build=${0%/*}/
 

buildsys/build-gcc.sh

-#!/usr/bin/bash
+#! /bin/bash
 
 build=${0%/*}/
 

buildsys/readme.txt

+flext - C++ layer for Max/MSP and pd (pure data) externals
+
+Copyright (c) 2001-2005 Thomas Grill (gr@grrrr.org)
+For information on usage and redistribution, and for a DISCLAIMER OF ALL
+WARRANTIES, see the file, "license.txt," in this distribution.  
+
+----------------------------------------------------------------------------
+
+At the moment this is more like a sketchboard, but i'll promise to bring some
+order into it some fine day in the not too distant future.
+
+----------------------------------------------------------------------------
+
+Build scripts
+=============
+
+Depending on platform the build process is run with
+build.sh
+or
+build.bat
+
+
+Arguments: PLATFORM SYSTEM COMPILER {TARGET} {definitions}
+
+PLATFORM: win / lnx / mac
+SYSTEM:   pd / max
+COMPILER: msvc / gcc / mingw / cygwin / bcc / icc
+
+TARGET: (default is all)
+	all, build - build package in default style
+	install - install package
+	clean - clean build products
+
+	config - test if configuration needs refreshing
+
+or
+	build-MODE-TYPE
+	install-MODE-TYPE
+	clean-MODE-TYPE
+
+with
+	MODE: default, all, release, debug
+	TYPE: default, all, single, multi, shared
+
+
+Additional definitions can be passed to the make program
+like
+	"PKGINFO=info.txt"   (defines new filename for package information)
+or
+	"PKGINFO="           (package information will be skipped - only for config target)
+
+For more macro names, see below
+
+
+For each of the supported combinations of PLATFORM, SYSTEM and COMPILER 
+a MAKE program has been chosen, normally the one that comes with the compiler.
+
+For gcc it is GNU make (gnumake)
+For msvc it is Microsoft make (nmake)
+For bcc it is Borland make (bmake)
+
+
+
+Package info (package.txt)
+==========================
+
+Package information contains vital information for the build process.
+Obligatory are only:
+
+NAME: resulting filename of the build product
+SRCS: list of source files
+
+
+Normally also used are:
+
+HDRS: used header files, which SRCS files are dependent upon
+SRCDIR: source folder (relative to project folder), default is .
+
+
+Other settings:
+
+PRECOMPILE: prefix header file (in SRCDIR) for all source files, 
+	will be precompiled if supported by the compiler
+
+BUILDCLASS: can currently be flext or ext, default is ext.
+	flext will build the flext system
+	ext will build a flext-based external
+
+BUILDMODE: release or debug, default is release
+	if release, optimization flags will be used
+	if debug, debug information will be generated
+
+BUILDTYPE: single, multi or shared, default is single
+	if single, it will be linked against the single-threaded static flext library
+	if multi, it will be linked against the multi-threaded static flext library
+	if shared, it will be linked against the shared flext library
+
+BUILDDIR: relative folder with additional build settings
+
+
+
+Additional build settings (BUILDDIR)
+====================================
+
+If BUILDDIR is defined, all PLATFORM-SYSTEM-COMPILER combinations to support
+must are mirrored by the respective .def and .inc files in the BUILDDIR.
+
+
+config-PLATFORM.def files (e.g. config-lnx.def) :
+
+	These files can contain additional macro definitions, that are private
+	to the project.
+	The definitions should be strictly in the form SETTING=value, without any
+	make-specific macros etc.
+	The .def files work as templates that get copied to a user-editable 
+	config.txt file when the build process is first started.
+
+
+MAKE-PLATFORM-COMPILER.inc files 
+(e.g. gnumake-lnx-gcc.inc or nmake-win-msvc.inc):
+
+	These files (which are no considered to be edited by the user) can contain 
+	specific modifications to compiler flags, include file paths etc.
+
+	For gnumake this would e.g. be
+	INCPATH += -I/usr/local/include/python2.3
+
+	for nmake or bmake e.g.
+	INCPATH = $(INCPATH) -I"c:\program files\Python2.3\include"
+
+
+Structure of build system
+=========================
+
+The build system has several levels of information, which are evaluated in the
+following order (see also buildsys/MAKE-sub.mak)
+
+Project level:
+- PKGINFO file (e.g. package.txt)
+- USRCONFIG file (e.g. config.txt)
+- USRMAKE file (e.g. build/gnumake-lnx-gcc.inc)
+
+General definitions (in buildsys):
+
+- MAKE.inc (e.g. buildsys/gnumake.inc)
+	contains evaluation of flext library name, build directory etc.
+- MAKE-BUILDCLASS.inc (e.g. buildsys/gnumake-ext.inc)
+	contains some more flag settings
+
+Real-time-system-dependent definitions (in buildsys/PLATFORM/SYSTEM):
+
+- MAKE-COMPILER.inc (e.g. buildsys/lnx/pd/gnumake-gcc.inc)
+	contains general real-time-system dependent info (e.g. paths, FLEXT_SYS setting)
+- MAKE-COMPILER-BUILDCLASS.inc (e.g. buildsys/lnx/pd/gnumake-gcc-ext.inc)
+	contains specific real-time-system dependent info (e.g. extension of binary)
+
+Platform-dependent definitions (in buildsys/PLATFORM):
+
+- MAKE-COMPILER.inc (e.g. buildsys/lnx/gnumake-gcc.inc)
+	contains general platform-specific flags
+- MAKE-COMPILER-BUILDCLASS.inc (e.g. buildsys/lnx/gnumake-gcc-ext.inc)
+	contains the actual make targets (_build_,_clean_ and _install_)
+
+
+Macro names
+===============
+
+PKGINFO - filename for package information (must reside in project folder)
+
+CFLAGS - compiler flags
+LDFLAGS - linker flags
+
+INCPATH - include file path (must come with e.g. -I )
+LIBPATH - library path (must come with e.g. -L )
+
+LIBS - libraries to link in (must come with e.g. -l )

buildsys/win/bmake-bcc-flext.inc

@@ -54,24 +54,11 @@ FLEXTLIBINST=$(FLEXTSHLIB)
 FLEXTLIBINST=$(FLEXTLIB)
 !endif
 
-$(FLEXTINC):
-	if not exist $@ mkdir $@ > nul
-
-!if "$(FLEXTINC)" != "$(FLEXTLIB)"
-$(FLEXTLIB):
-	if not exist $@ mkdir $@ > nul
-
-_install_:: $(FLEXTLIB)
-!endif
-
-!if "$(FLEXTLIBINST)" != "$(FLEXTLIB)" && "$(FLEXTLIBINST)" != "$(FLEXTINC)"
-$(FLEXTLIBINST):
-	if not exist $@ mkdir $@ > nul
-
-_install_:: $(FLEXTLIBINST)
-!endif
+_install_:
+	@if not exist $@ mkdir $(FLEXTINC) > nul
+	@if not exist $@ mkdir $(FLEXTLIB) > nul
+	@if not exist $@ mkdir $(FLEXTLIBINST) > nul
 
-_install_:: $(FLEXTINC)
 	copy $(TARGET) $(FLEXTLIBINST) > nul
 !ifdef SHARED
 # copy import library
@@ -80,4 +67,4 @@ _install_:: $(FLEXTINC)
 # copy headers
 	for %%i in ($(HDRS)) do @copy $(SRCDIR)\%%i $(FLEXTINC) > nul	
 # copy import libraries
-	for %%i in ($(PDTARGETS)) do @copy %%i $(FLEXTLIBINST) > nul	
+	for %%i in ($(PDTARGETS)) do @copy %%i $(FLEXTLIB) > nul	

buildsys/win/max/config-mingw.def

 # where are the Max/MSP SDK header files?
 # you should have the latest version!
-MAXSDKPATH="c:/data/prog/audio/maxmspsdk_win/4.5 headers/c74support"
+MAXSDKPATH="%ProgramFiles%\MaxMSP 4.5/maxmspsdk_win/4.5 headers/c74support"
 
 ###############################################################
 
@@ -12,7 +12,7 @@ FLEXTLIB=$(FLEXTINC)
 
 # where do/should the flext shared libraries reside/be built?
 # (a good place is the MaxMSP program folder)
-FLEXTSHLIB="%ProgramFiles%\audio\MaxMSP 4.5"
+FLEXTSHLIB="%ProgramFiles%\MaxMSP 4.5"
 
 ###############################################################
 

buildsys/win/max/config-msvc.def

 # where are the Max/MSP SDK header files?
 # you should have the latest version!
-MAXSDKPATH="c:\data\prog\audio\maxmspsdk_win\4.5 headers\c74support"	
+MAXSDKPATH="%ProgramFiles%\MaxMSP 4.5\maxmspsdk_win\4.5 headers\c74support"	
 
 # where is MS VC++?
 # (not necessary if the build is run with the compiler environment)

buildsys/win/pd/config-bcc.def

 # where is PD?
-PDPATH=c:\programme\audio\pd		
+PDPATH="c:\program files\pd"
 
 # where is BorlandC++?
-BCCPATH=C:\Programme\prog\bcc55
+BCCPATH="c:\program files\bcc55"
 
 ###############################################################
 

buildsys/win/pd/config-cygwin.def

 # where is PD?
-PDPATH=/cygdrive/c/programme/audio/pd
+PDPATH=/cygdrive/c/programme/pd
 
 ###############################################################
 

buildsys/win/pd/config-mingw.def

 # where is PD?
-PDPATH=c:\programme\audio\pd
+PDPATH="%ProgramFiles%\pd"
 
 ###############################################################
 

buildsys/win/pd/config-msvc.def

 # where is PD?
-PDPATH=c:\programme\audio\pd	
+PDPATH="%ProgramFiles%\pd"
 
 # where is MS VC++?
 # (not necessary if the build is run with the compiler environment)
-# MSVCPATH=C:\Programme\Microsoft Visual Studio .NET 2003\Vc7
+# MSVCPATH="%ProgramFiles%\Microsoft Visual Studio .NET 2003\Vc7"
 
 ###############################################################
 

changes.txt

@@ -321,16 +321,10 @@ Porting to new compilers/platforms:
 
 TODO list:
 
-for 0.4.8:
-- SIMD for gcc
-- Max/MSP MachO support
-
-for 0.5.0:
 - optimizations for object initialization and messaging
+- SIMD for gcc
 
 bugs:
-- recreation of object with different argument line forgets about eventually present attributes
-
 - can't use MFC libraries because of global new and delete overloadings
 
 TEST:

license.txt

 flext - C++ layer for Max/MSP and pd (pure data) externals
-Copyright (C) 2001-2003 Thomas Grill
+Copyright (C) 2001-2005 Thomas Grill
 
 This program is free software; you can redistribute it and/or
 modify it under the terms of the GNU General Public License
@@ -16,34 +16,4 @@ along with this program; if not, write to the Free Software
 Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA  02111-1307, USA.
 
 In the official flext distribution, the GNU General Public License is
-in the file gpl.txt
-
----------------------------------------------------------
-
-             OTHER COPYRIGHT NOTICES
-
----------------------------------------------------------
-This package uses a lot of code from GEM by Mark Danks 
-See the license text below:
-
---- GEM --------------------------------------
-GEM - Graphics Environment for Multimedia
-Copyright (C) 1997-2000 Mark Danks
-
-This program is free software; you can redistribute it and/or
-modify it under the terms of the GNU General Public License
-as published by the Free Software Foundation; either version 2
-of the License, or (at your option) any later version.
-
-This program is distributed in the hope that it will be useful,
-but WITHOUT ANY WARRANTY; without even the implied warranty of
-MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
-GNU General Public License for more details.
-
-You should have received a copy of the GNU General Public License
-along with this program; if not, write to the Free Software