--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/R/rdyncall/inst/doc/ANNOUNCEMENT.txt	Thu Mar 19 22:26:28 2015 +0100
@@ -0,0 +1,284 @@
+Initial Announcement: Package rdyncall released on CRAN. (Version 0.7.3)
+
+Short Introduction
+------------------
+The package facilities dynamic R bindings to the C interface of some common 
+shared libraries and a flexible Foreign Function Interface for the 
+interoperability between R and C. 
+
+Since the initial presentation of the package at Use!R 2009, a number of
+improvements have been done to rdyncall, the low-level DynCall libraries
+and the build system for an official release on CRAN.
+
+Overview
+--------
+The package comprises a toolkit to work with C interfaces to native code from 
+within the dynamic R interpreter without the need for C wrapper compilation:
+
+  - Dynamic R bindings to some common C shared libraries, across platforms.
+  - Foreign Function Interface that supports almost all C arg/return types
+    and has built-in type-checking facility.
+  - Portable naming and loading of shared libraries across platforms.
+  - Handling of aggregate C struct and union data types.
+  - Wrapping of R functions as C callbacks.
+  - Binding of C functions to R in batches.
+
+The intended audience for this package are developers experienced with C, that
+
+ .. need complete R bindings of C libraries.
+ .. want to write cross-platform portable system-level code in R.
+ .. need a FFI that supports almost all C fundamental types for arguments 
+    and return types and thus does not need compilation of wrapper C code
+ .. want to work with C struct/union types directly in R
+ .. are interested in dynamic binding techniques between static and dynamic
+    languages and cross-platform binding strategies.
+
+
+Brief Tour 1/2: Dynamic R Bindings to C Libraries
+-------------------------------------------------
+
+The dynamic binding interface consists of a single function, similar to
+'library' or 'require':
+
+  > dynport(portname)
+
+portname refers to a 'DynPort' file name that represents an R binding to a
+common C interface and library.
+The function the above has the side effect of attaching a newly created R name 
+space, populated with thin R helper objects to C entities of the underlying 
+C library:
+
+  - call wrapper to C functions
+  - symbolic constants of C macros and enums,
+  - type information objects for C struct and union data types.
+
+The package contains a repository of the following DynPort files:
+
+  Port Name   | Description of C Shared Library/API
+  ------------+-------------------------------------------------
+  expat       | Expat XML Parser Library
+  GL          | OpenGL 1.1 API
+  GLU         | OpenGL Utility Library
+  SDL         | Simple DirectMedia Layer library        
+  SDL_image   | Loading of image files (png,jpeg..)
+  SDL_mixer   | Loading/Playing of ogg/mp3/mod music files.
+  SDL_ttf     | Loading/Rendering of True Type Fonts.
+  glew        | OpenGL Extension Wrangler (includes OpenGL 3.0)
+  gl3         | strict OpenGL 3 (untested)
+  R           | R shared library
+  ode         | Open Dynamics (Physics-) Engine (untested)
+  cuda        | NVIDIA Cuda (untested)
+  opencl      | OpenCL (untested)
+  stdio       | C Standard Library I/O Functions
+
+In order to use a DynPort on a host system, the shared C libraries 
+need to be installed first.
+
+See manual page on 'rdyncall-demos' (type ?'rdyncall-demos') for a detailed 
+description of the installation notes for several libraries the above,
+collected for a large range of operating-systems and OS distributions. 
+
+Since the rdyncall package is alredy ported across major R platforms, code
+that uses a DynPort can run cross-platform without compilation.
+
+Here is a small example for using the SDL and OpenGL for multimedia/3D:
+
+-- snip
+
+# load SDL and OpenGL bindings
+dynport(SDL)  
+dynport(GL)  
+
+# initialize video sub-system
+SDL_Init(SDL_INIT_VIDEO)
+
+# open double-buffered OpenGL window surface
+surface <- SDL_SetVideoMode(640,480,32,SDL_OPENGL+SDL_DOUBLEBUF)
+
+# print dimension by accessing fields external C pointer to struct SDL_Surface
+print( paste("dimenstion:", surface$w, "x", surface$h ))
+
+# clear buffer
+glClearColor(0.3,0.6,0.8,0)
+glClear(GL_COLOR_BUFFER_BIT)
+
+# update display
+SDL_GL_SwapBuffers()
+
+-- snap
+
+A more detailed version including user-interface handling is available
+in 'demo(SDL)'.
+
+
+Brief Tour 2/2: Alternative FFI via '.dyncall'
+----------------------------------------------
+
+The alternative foreign function interface offered by '.dyncal' has a similar 
+intend such as '.C'. It allows to call shared library functions directly from R,
+but without additional wrapper C code needed, because it supports almost all 
+fundamental C data types and uses a function type signature text specification
+for type-checking and flexible conversions between R and C values.
+
+The interface is as following:
+
+  > .dyncall(address, signature, ...)
+
+'signature' is a character string that encodes the arguments and return-type of 
+a C function. 
+Here is an example of C function from the OpenGL API:
+
+   void glClearColor(float red, float green, float blue, float alpha);
+
+one would specify the function type via "ffff)v" as type signature and 
+pass additional arguments for '...':
+
+  > .dyncall(addressOf_glClearColor, "ffff)v", 0.3,0.7,1,0)
+
+Support for pointers (low-level void and typed pointers to struct/union) and
+wrapping of R functions to first-level C function pointers is also available.
+
+-- snip
+
+# load C math library across major platforms (Windows,Mac OS X,Linux)
+mathlib <- dynfind(c("msvcrt","m","m.so.6"))
+
+# resolve symbol 'sqrt'
+x <- .dynsym(mathlib,"sqrt")
+
+# C function call 'double sqrt(double x)' with x=144
+.dyncall(x, "d)d", 144)
+
+# .dyncall uses complex mapping of types, same works with 'integer' argument:
+.dyncall(x, "d)d", 144L)
+
+-- snap
+
+
+Implementation Details
+----------------------
+
+This package contains low-level services related to the generic invocation
+of machine-code functions using official calling convention specifications 
+as the binary interface. A similar service exists for the oppositve direction 
+in order to write R functions and wrap them as first-level C function callback 
+pointers.
+
+The implementation is based on libraries from the DynCall Project that
+implement a small amount of code in Assembly and have to play closely 
+together with the calling conventions of various processor-architectures and 
+platforms.
+The implementation can be tricky has to be done on a calling-convention
+basis. The efforts legitimate this non-portsble approach due to a 
+very small code size and a generic machine-call solution designed for
+dynamic interpreters. (total size of shared lib object in rdyncall is ~60kb )
+
+
+Portability and Platforms
+-------------------------
+
+A large set of platforms and calling conventions are already supported and a 
+suite of testing tools ensure a stable implementation at low-level.
+
+Processor-Architectures:
+- Intel i386 32-bit and AMD 64-bit Platforms
+- PowerPC 32-bit (support for callbacks on System V systems not yet implemented)
+- ARM 32-bit (with support for Thumb)
+- MIPS 32- and 64-bit (support for callbacks not yet implemented)
+- SPARC 32-bit and 64-bit (support for callbacks not yet implemented)
+
+The DynCall libraries are tested on Linux, Mac OS X, Windows, BSD derivates,
+Solaris and more exotic platforms such as game consoles, Plan9, Haiku and Minix.
+The R Package has been tested on several major 32- and 64-bit R platforms
+including Windows 32/64-bit, Linux (i386,amd64,ppc,arm), NetBSD (i386,amd64),
+Solaris (i386,amd64).
+
+As of this release, no support for callbacks is available on MIPS or SPARC.
+Callbacks on PowerPC 32-bit for Mac OS X work fine, for other
+ELF/System V-based PowerPC systems, callbacks are not yet implemented.
+
+
+Known Bugs
+----------
+
+* PowerPC/Mac OS X 10.4: Building Universal Binaries are broken.. in particular 
+  the as for i386 assembler. 
+  Workaround for PowerPC users: install with "--no-multiarch" or use prebuilt 
+  binaries built on OS X >= 10.5.
+
+* SPARC Assembly sources are currently implemented for GNU assembler and do 
+  not assemble using the 'fbe' Assembler tool on Solaris. 
+
+
+More Information
+----------------
+
+More demos and examples are in the package.
+A 20-page vignette with the title "Foreign Library Interface" is available via
+  > vignette("FLI")
+
+A cross-platform audio/visual OpenGL-based demo-scene production 
+written in 100% pure R is available here:
+
+  http://dyncall.org/demos/soulsalicious/
+
+A video of demo is also at the website.
+
+
+The website of the DynCall Project is at
+
+  http://dyncall.org/
+
+
+Help and Feedback
+-----------------
+The package contains new methods for dynamic binding of native code to R
+that were designed to work cross-platform. Thus the package required intensive 
+testing on a large range of processor/OS/tool-chain combinations.
+It was (and still is!) also very helpful to run tests on different 
+'distributions' of the same OS for checking e.g. the search algorithm for
+locating shared libraries by a short name across operating-systems 
+(see '?dynfind' for details on this).
+
+I am very thankful for any feedback including bug-reports, success and 
+failure stories or ideas of improvements. If you feel that an important 
+architecture, platform or build-tool is missing here please let me know too.
+
+The DynCall authors appreciate any support for porting the DynCall libraries 
+and the R package e.g. remote development accounts, qemu/gxemul images, 
+hardware. In particular we are currently looking for the following 
+arch/os/compilers environment for porting the DynCall libraries and rdyncall:
+
+  - Sparc/Solaris/SunPro
+  - PowerPC/AIX/XL C 
+  - MIPS/IRIX/MIPSpro
+
+If you can help us out, please get in contact us.
+
+
+ChangeLog
+---------
+
+0.7.3: [2011-07-19] Added vignette, new ports, new tool-chain an fixes for bugs
+ o bugfix for Fedora/x64: added search path 'lib64' folder for 'dynfind'.
+ o added support for Sun make, DynCall uses Makefile.embedded.
+ o added sparc and sparc64 support using gcc tool-chain.
+ o added support for amd64 using solaris tool-chain.
+ o added vignette "foreign library interface".
+ o bugfix for solaris/x64: added search path 'amd64' folder for 'dynfind'.
+ o bugfix in examples for libm using 'm.so.6' besides 'm' on unix 
+   (needed by debian 6 sid unstable)
+
+0.7.2: [2011-04-27] Minor fixes 
+ o added win64/mingw64 support.
+
+0.7.1: [2011-04-26] Minor fixes      
+ o minor Makevars fix for parallel builds.
+
+0.7.0: [2011-04-20] Initial Release 
+ o first upload to CRAN.
+
+
+enjoy,
+- Daniel
+