Commit 078079be authored by thomas's avatar thomas
Browse files

revised the documentation

git-svn-id: https://svn.grrrr.org/ext/trunk@958 4d9ac71a-51e6-0310-8455-cad1006bcd31
parent 203bdf44
Thomas Grill
\ No newline at end of file
Thomas Grill (gr@grrrr.org)
These are instructions for the autoconf building system.
For the native flext build system, please see the build.txt document.
-----------------------------------------------------------------------
Basic Installation
==================
......
@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
#! /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
......
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.
#!/usr/bin/bash
#! /bin/bash
build=${0%/*}/
......
#!/usr/bin/bash
#! /bin/bash
build=${0%/*}/
......
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 )
......@@ -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
# 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"
###############################################################
......
# 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)
......
# 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"
###############################################################
......
# where is PD?
PDPATH=/cygdrive/c/programme/audio/pd
PDPATH=/cygdrive/c/programme/pd
###############################################################
......
# where is PD?
PDPATH=c:\programme\audio\pd
PDPATH="%ProgramFiles%\pd"
###############################################################
......
# 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"
###############################################################
......
......@@ -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:
......
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
Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.