3.0.11-rc1. soname bump.
[libffi.git] / README
1 Status
2 ======
3
4 libffi-3.0.11 was released on *****************. Check the libffi web
5 page for updates: <URL:http://sourceware.org/libffi/>.
6
7
8 What is libffi?
9 ===============
10
11 Compilers for high level languages generate code that follow certain
12 conventions. These conventions are necessary, in part, for separate
13 compilation to work. One such convention is the "calling
14 convention". The "calling convention" is essentially a set of
15 assumptions made by the compiler about where function arguments will
16 be found on entry to a function. A "calling convention" also specifies
17 where the return value for a function is found.
18
19 Some programs may not know at the time of compilation what arguments
20 are to be passed to a function. For instance, an interpreter may be
21 told at run-time about the number and types of arguments used to call
22 a given function. Libffi can be used in such programs to provide a
23 bridge from the interpreter program to compiled code.
24
25 The libffi library provides a portable, high level programming
26 interface to various calling conventions. This allows a programmer to
27 call any function specified by a call interface description at run
28 time.  
29
30 FFI stands for Foreign Function Interface.  A foreign function
31 interface is the popular name for the interface that allows code
32 written in one language to call code written in another language. The
33 libffi library really only provides the lowest, machine dependent
34 layer of a fully featured foreign function interface. A layer must
35 exist above libffi that handles type conversions for values passed
36 between the two languages.
37
38
39 Supported Platforms
40 ===================
41
42 Libffi has been ported to many different platforms.
43 For specific configuration details and testing status, please
44 refer to the wiki page here:
45
46  http://www.moxielogic.org/wiki/index.php?title=Libffi_3.0.11
47
48 At the time of release, the following basic configurations have been
49 tested:
50
51 |--------------+------------------|
52 | Architecture | Operating System |
53 |--------------+------------------|
54 | Alpha        | Linux            |
55 | Alpha        | Tru64            |
56 | ARM          | Linux            |
57 | ARM          | iOS              |
58 | AVR32        | Linux            |
59 | HPPA         | HPUX             |
60 | IA-64        | Linux            |
61 | M68K         | RTEMS            |
62 | MIPS         | IRIX             |
63 | MIPS         | Linux            |
64 | MIPS         | RTEMS            |
65 | MIPS64       | Linux            |
66 | PowerPC      | Linux            |
67 | PowerPC      | Mac OSX          |
68 | PowerPC      | FreeBSD          |
69 | PowerPC64    | Linux            |
70 | S390         | Linux            |
71 | S390X        | Linux            |
72 | SPARC        | Linux            |
73 | SPARC        | Solaris          |
74 | SPARC64      | Linux            |
75 | SPARC64      | FreeBSD          |
76 | X86          | FreeBSD          |
77 | X86          | Interix          |
78 | X86          | kFreeBSD         |
79 | X86          | Linux            |
80 | X86          | Mac OSX          |
81 | X86          | OpenBSD          |
82 | X86          | OS/2             |
83 | X86          | Solaris          |
84 | X86          | Windows/Cygwin   |
85 | X86          | Windows/MingW    |
86 | X86-64       | FreeBSD          |
87 | X86-64       | Linux            |
88 | X86-64       | OpenBSD          |
89 | X86-64       | Windows/MingW    |
90 |--------------+------------------|
91
92 Please send additional platform test results to
93 libffi-discuss@sourceware.org and feel free to update the wiki page
94 above.
95
96 Installing libffi
97 =================
98
99 First you must configure the distribution for your particular
100 system. Go to the directory you wish to build libffi in and run the
101 "configure" program found in the root directory of the libffi source
102 distribution.
103
104 You may want to tell configure where to install the libffi library and
105 header files. To do that, use the --prefix configure switch.  Libffi
106 will install under /usr/local by default. 
107
108 If you want to enable extra run-time debugging checks use the the
109 --enable-debug configure switch. This is useful when your program dies
110 mysteriously while using libffi. 
111
112 Another useful configure switch is --enable-purify-safety. Using this
113 will add some extra code which will suppress certain warnings when you
114 are using Purify with libffi. Only use this switch when using 
115 Purify, as it will slow down the library.
116
117 It's also possible to build libffi on Windows platforms with
118 Microsoft's Visual C++ compiler.  In this case, use the msvcc.sh
119 wrapper script during configuration like so:
120
121 path/to/configure CC=path/to/msvcc.sh LD=link CPP=\"cl -nologo -EP\"
122
123 For 64-bit Windows builds, use CC="path/to/msvcc.sh -m64".
124 You may also need to specify --build appropriately. When building with MSVC
125 under a MingW environment, you may need to remove the line in configure
126 that sets 'fix_srcfile_path' to a 'cygpath' command. ('cygpath' is not
127 present in MingW, and is not required when using MingW-style paths.)
128
129 For iOS builds, refer to the build-ios.sh script for guidance.
130
131 Configure has many other options. Use "configure --help" to see them all.
132
133 Once configure has finished, type "make". Note that you must be using
134 GNU make.  You can ftp GNU make from prep.ai.mit.edu:/pub/gnu.
135
136 To ensure that libffi is working as advertised, type "make check".
137 This will require that you have DejaGNU installed.
138
139 To install the library and header files, type "make install".
140
141
142 History
143 =======
144
145 See the ChangeLog files for details.
146
147 3.0.11 MMM-DD-YY
148         ??????????
149
150 3.0.10 Aug-23-11
151         Add support for Apple's iOS.
152         Add support for ARM VFP ABI.
153         Add RTEMS support for MIPS and M68K.
154         Fix instruction cache clearing problems on
155           ARM and SPARC.
156         Fix the N64 build on mips-sgi-irix6.5.
157         Enable builds with Microsoft's compiler.
158         Enable x86 builds with Oracle's Solaris compiler.
159         Fix support for calling code compiled with Oracle's Sparc
160           Solaris compiler.
161         Testsuite fixes for Tru64 Unix.
162         Additional platform support.
163
164 3.0.9 Dec-31-09
165         Add AVR32 and win64 ports.  Add ARM softfp support.
166         Many fixes for AIX, Solaris, HP-UX, *BSD.
167         Several PowerPC and x86-64 bug fixes.
168         Build DLL for windows.
169
170 3.0.8 Dec-19-08
171         Add *BSD, BeOS, and PA-Linux support.
172
173 3.0.7 Nov-11-08
174         Fix for ppc FreeBSD.
175         (thanks to Andreas Tobler)
176
177 3.0.6 Jul-17-08
178         Fix for closures on sh.
179         Mark the sh/sh64 stack as non-executable.
180         (both thanks to Kaz Kojima)
181
182 3.0.5 Apr-3-08
183         Fix libffi.pc file.
184         Fix #define ARM for IcedTea users.
185         Fix x86 closure bug.
186
187 3.0.4 Feb-24-08
188         Fix x86 OpenBSD configury.
189
190 3.0.3 Feb-22-08
191         Enable x86 OpenBSD thanks to Thomas Heller, and
192         x86-64 FreeBSD thanks to Björn König and Andreas Tobler.
193         Clean up test instruction in README.
194
195 3.0.2 Feb-21-08
196         Improved x86 FreeBSD support.
197         Thanks to Björn König.
198
199 3.0.1 Feb-15-08
200         Fix instruction cache flushing bug on MIPS.
201         Thanks to David Daney.
202
203 3.0.0 Feb-15-08
204         Many changes, mostly thanks to the GCC project.
205         Cygnus Solutions is now Red Hat.
206
207   [10 years go by...]
208
209 1.20 Oct-5-98
210         Raffaele Sena produces ARM port.
211
212 1.19 Oct-5-98
213         Fixed x86 long double and long long return support.
214         m68k bug fixes from Andreas Schwab.
215         Patch for DU assembler compatibility for the Alpha from Richard
216         Henderson.
217
218 1.18 Apr-17-98
219         Bug fixes and MIPS configuration changes.
220
221 1.17 Feb-24-98
222         Bug fixes and m68k port from Andreas Schwab. PowerPC port from
223         Geoffrey Keating. Various bug x86, Sparc and MIPS bug fixes.
224
225 1.16 Feb-11-98
226         Richard Henderson produces Alpha port.
227
228 1.15 Dec-4-97
229         Fixed an n32 ABI bug. New libtool, auto* support.
230
231 1.14 May-13-97
232         libtool is now used to generate shared and static libraries.
233         Fixed a minor portability problem reported by Russ McManus
234         <mcmanr@eq.gs.com>.
235
236 1.13 Dec-2-96
237         Added --enable-purify-safety to keep Purify from complaining
238         about certain low level code.
239         Sparc fix for calling functions with < 6 args.
240         Linux x86 a.out fix.
241
242 1.12 Nov-22-96
243         Added missing ffi_type_void, needed for supporting void return 
244         types. Fixed test case for non MIPS machines. Cygnus Support 
245         is now Cygnus Solutions. 
246
247 1.11 Oct-30-96
248         Added notes about GNU make.
249
250 1.10 Oct-29-96
251         Added configuration fix for non GNU compilers.
252
253 1.09 Oct-29-96
254         Added --enable-debug configure switch. Clean-ups based on LCLint 
255         feedback. ffi_mips.h is always installed. Many configuration 
256         fixes. Fixed ffitest.c for sparc builds.
257
258 1.08 Oct-15-96
259         Fixed n32 problem. Many clean-ups.
260
261 1.07 Oct-14-96
262         Gordon Irlam rewrites v8.S again. Bug fixes.
263
264 1.06 Oct-14-96
265         Gordon Irlam improved the sparc port. 
266
267 1.05 Oct-14-96
268         Interface changes based on feedback.
269
270 1.04 Oct-11-96
271         Sparc port complete (modulo struct passing bug).
272
273 1.03 Oct-10-96
274         Passing struct args, and returning struct values works for
275         all architectures/calling conventions. Expanded tests.
276
277 1.02 Oct-9-96
278         Added SGI n32 support. Fixed bugs in both o32 and Linux support.
279         Added "make test".
280
281 1.01 Oct-8-96
282         Fixed float passing bug in mips version. Restructured some
283         of the code. Builds cleanly with SGI tools.
284
285 1.00 Oct-7-96
286         First release. No public announcement.
287
288
289 Authors & Credits
290 =================
291
292 libffi was originally written by Anthony Green <green@redhat.com>.
293
294 The developers of the GNU Compiler Collection project have made
295 innumerable valuable contributions.  See the ChangeLog file for
296 details.
297
298 Some of the ideas behind libffi were inspired by Gianni Mariani's free
299 gencall library for Silicon Graphics machines.
300
301 The closure mechanism was designed and implemented by Kresten Krab
302 Thorup.
303
304 Major processor architecture ports were contributed by the following
305 developers:
306
307 alpha           Richard Henderson
308 arm             Raffaele Sena
309 cris            Simon Posnjak, Hans-Peter Nilsson
310 frv             Anthony Green
311 ia64            Hans Boehm
312 m32r            Kazuhiro Inaoka
313 m68k            Andreas Schwab
314 mips            Anthony Green, Casey Marshall
315 mips64          David Daney
316 pa              Randolph Chung, Dave Anglin, Andreas Tobler
317 powerpc         Geoffrey Keating, Andreas Tobler, 
318                          David Edelsohn, John Hornkvist
319 powerpc64       Jakub Jelinek
320 s390            Gerhard Tonn, Ulrich Weigand
321 sh              Kaz Kojima
322 sh64            Kaz Kojima
323 sparc           Anthony Green, Gordon Irlam
324 x86             Anthony Green, Jon Beniston
325 x86-64          Bo Thorsen
326
327 Jesper Skov and Andrew Haley both did more than their fair share of
328 stepping through the code and tracking down bugs.
329
330 Thanks also to Tom Tromey for bug fixes, documentation and
331 configuration help.
332
333 Thanks to Jim Blandy, who provided some useful feedback on the libffi
334 interface.
335
336 Andreas Tobler has done a tremendous amount of work on the testsuite.
337
338 Alex Oliva solved the executable page problem for SElinux.
339
340 The list above is almost certainly incomplete and inaccurate.  I'm
341 happy to make corrections or additions upon request.
342
343 If you have a problem, or have found a bug, please send a note to the
344 author at green@moxielogic.com, or the project mailing list at
345 libffi-discuss@sourceware.org.