remove stray quote
[libffi.git] / README
1 Status
2 ======
3
4 libffi-4?? was released on TBD.  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.2
47
48 At the time of release, the following basic configurations have been
49 tested:
50
51 |-----------------+------------------+-------------------------|
52 | Architecture    | Operating System | Compiler                |
53 |-----------------+------------------+-------------------------|
54 | AArch64 (ARM64) | iOS              | Clang                   |
55 | AArch64         | Linux            | GCC                     |
56 | Alpha           | Linux            | GCC                     |
57 | Alpha           | Tru64            | GCC                     |
58 | ARC             | Linux            | GCC                     |
59 | ARM             | Linux            | GCC                     |
60 | ARM             | iOS              | GCC                     |
61 | AVR32           | Linux            | GCC                     |
62 | Blackfin        | uClinux          | GCC                     |
63 | HPPA            | HPUX             | GCC                     |
64 | IA-64           | Linux            | GCC                     |
65 | M68K            | FreeMiNT         | GCC                     |
66 | M68K            | Linux            | GCC                     |
67 | M68K            | RTEMS            | GCC                     |
68 | M88K            | OpenBSD/mvme88k  | GCC                     |
69 | Meta            | Linux            | GCC                     |
70 | MicroBlaze      | Linux            | GCC                     |
71 | MIPS            | IRIX             | GCC                     |
72 | MIPS            | Linux            | GCC                     |
73 | MIPS            | RTEMS            | GCC                     |
74 | MIPS64          | Linux            | GCC                     |
75 | Moxie           | Bare metal       | GCC                     |
76 | Nios II         | Linux            | GCC                     |
77 | OpenRISC        | Linux            | GCC                     |
78 | PowerPC 32-bit  | AIX              | IBM XL C                |
79 | PowerPC 64-bit  | AIX              | IBM XL C                |
80 | PowerPC         | AMIGA            | GCC                     |
81 | PowerPC         | Linux            | GCC                     |
82 | PowerPC         | Mac OSX          | GCC                     |
83 | PowerPC         | FreeBSD          | GCC                     |
84 | PowerPC 64-bit  | FreeBSD          | GCC                     |
85 | PowerPC 64-bit  | Linux ELFv1      | GCC                     |
86 | PowerPC 64-bit  | Linux ELFv2      | GCC                     |
87 | S390            | Linux            | GCC                     |
88 | S390X           | Linux            | GCC                     |
89 | SPARC           | Linux            | GCC                     |
90 | SPARC           | Solaris          | GCC                     |
91 | SPARC           | Solaris          | Oracle Solaris Studio C |
92 | SPARC64         | Linux            | GCC                     |
93 | SPARC64         | FreeBSD          | GCC                     |
94 | SPARC64         | Solaris          | Oracle Solaris Studio C |
95 | TILE-Gx/TILEPro | Linux            | GCC                     |
96 | VAX             | OpenBSD/vax      | GCC                     |
97 | X86             | FreeBSD          | GCC                     |
98 | X86             | GNU HURD         | GCC                     |
99 | X86             | Interix          | GCC                     |
100 | X86             | kFreeBSD         | GCC                     |
101 | X86             | Linux            | GCC                     |
102 | X86             | Mac OSX          | GCC                     |
103 | X86             | OpenBSD          | GCC                     |
104 | X86             | OS/2             | GCC                     |
105 | X86             | Solaris          | GCC                     |
106 | X86             | Solaris          | Oracle Solaris Studio C |
107 | X86             | Windows/Cygwin   | GCC                     |
108 | X86             | Windows/MingW    | GCC                     |
109 | X86-64          | FreeBSD          | GCC                     |
110 | X86-64          | Linux            | GCC                     |
111 | X86-64          | Linux/x32        | GCC                     |
112 | X86-64          | OpenBSD          | GCC                     |
113 | X86-64          | Solaris          | Oracle Solaris Studio C |
114 | X86-64          | Windows/Cygwin   | GCC                     |
115 | X86-64          | Windows/MingW    | GCC                     |
116 | X86-64          | Mac OSX          | GCC                     |
117 | Xtensa          | Linux            | GCC                     |
118 |-----------------+------------------+-------------------------|
119
120 Please send additional platform test results to
121 libffi-discuss@sourceware.org and feel free to update the wiki page
122 above.
123
124 Installing libffi
125 =================
126
127 First you must configure the distribution for your particular
128 system. Go to the directory you wish to build libffi in and run the
129 "configure" program found in the root directory of the libffi source
130 distribution.
131
132 If you're building libffi directly from version control, configure won't
133 exist yet; run ./autogen.sh first.
134
135 You may want to tell configure where to install the libffi library and
136 header files. To do that, use the --prefix configure switch.  Libffi
137 will install under /usr/local by default. 
138
139 If you want to enable extra run-time debugging checks use the the
140 --enable-debug configure switch. This is useful when your program dies
141 mysteriously while using libffi. 
142
143 Another useful configure switch is --enable-purify-safety. Using this
144 will add some extra code which will suppress certain warnings when you
145 are using Purify with libffi. Only use this switch when using 
146 Purify, as it will slow down the library.
147
148 If you don't want to build documentation, use the --disable-docs
149 configure switch.
150
151 It's also possible to build libffi on Windows platforms with
152 Microsoft's Visual C++ compiler.  In this case, use the msvcc.sh
153 wrapper script during configuration like so:
154
155 path/to/configure CC=path/to/msvcc.sh CXX=path/to/msvcc.sh LD=link CPP="cl -nologo -EP"
156
157 For 64-bit Windows builds, use CC="path/to/msvcc.sh -m64" and
158 CXX="path/to/msvcc.sh -m64".  You may also need to specify --build
159 appropriately.
160
161 It is also possible to build libffi on Windows platforms with the LLVM
162 project's clang-cl compiler, like below:
163
164 path/to/configure CC="path/to/msvcc.sh -clang-cl" CXX="path/to/msvcc.sh -clang-cl" LD=link CPP="clang-cl -EP"
165
166 When building with MSVC under a MingW environment, you may need to
167 remove the line in configure that sets 'fix_srcfile_path' to a 'cygpath'
168 command.  ('cygpath' is not present in MingW, and is not required when
169 using MingW-style paths.)
170
171 For iOS builds, the 'libffi.xcodeproj' Xcode project is available.
172
173 Configure has many other options. Use "configure --help" to see them all.
174
175 Once configure has finished, type "make". Note that you must be using
176 GNU make.  You can ftp GNU make from ftp.gnu.org:/pub/gnu/make .
177
178 To ensure that libffi is working as advertised, type "make check".
179 This will require that you have DejaGNU installed.
180
181 To install the library and header files, type "make install".
182
183
184 History
185 =======
186
187 See the git log for details at http://github.com/libffi/libffi.
188
189 4.0 TBD
190         New API in support of GO closures.
191
192 3.2.1 Nov-12-14
193         Build fix for non-iOS AArch64 targets.
194
195 3.2 Nov-11-14
196         Add C99 Complex Type support (currently only supported on
197           s390).
198         Add support for PASCAL and REGISTER calling conventions on x86
199           Windows/Linux.
200         Add OpenRISC and Cygwin-64 support.
201         Bug fixes.
202
203 3.1 May-19-14
204         Add AArch64 (ARM64) iOS support.
205         Add Nios II support.
206         Add m88k and DEC VAX support.
207         Add support for stdcall, thiscall, and fastcall on non-Windows
208           32-bit x86 targets such as Linux.
209         Various Android, MIPS N32, x86, FreeBSD and UltraSPARC IIi
210           fixes.
211         Make the testsuite more robust: eliminate several spurious
212           failures, and respect the $CC and $CXX environment variables.
213         Archive off the manually maintained ChangeLog in favor of git
214           log.
215
216 3.0.13 Mar-17-13
217         Add Meta support.
218         Add missing Moxie bits.
219         Fix stack alignment bug on 32-bit x86.
220         Build fix for m68000 targets.
221         Build fix for soft-float Power targets.
222         Fix the install dir location for some platforms when building
223           with GCC (OS X, Solaris).
224         Fix Cygwin regression.
225
226 3.0.12 Feb-11-13
227         Add Moxie support.
228         Add AArch64 support.
229         Add Blackfin support.
230         Add TILE-Gx/TILEPro support.
231         Add MicroBlaze support.
232         Add Xtensa support.
233         Add support for PaX enabled kernels with MPROTECT.
234         Add support for native vendor compilers on
235           Solaris and AIX.
236         Work around LLVM/GCC interoperability issue on x86_64.
237
238 3.0.11 Apr-11-12
239         Lots of build fixes.
240         Add support for variadic functions (ffi_prep_cif_var).
241         Add Linux/x32 support.
242         Add thiscall, fastcall and MSVC cdecl support on Windows.
243         Add Amiga and newer MacOS support.
244         Add m68k FreeMiNT support.
245         Integration with iOS' xcode build tools.
246         Fix Octeon and MC68881 support.
247         Fix code pessimizations.
248
249 3.0.10 Aug-23-11
250         Add support for Apple's iOS.
251         Add support for ARM VFP ABI.
252         Add RTEMS support for MIPS and M68K.
253         Fix instruction cache clearing problems on
254           ARM and SPARC.
255         Fix the N64 build on mips-sgi-irix6.5.
256         Enable builds with Microsoft's compiler.
257         Enable x86 builds with Oracle's Solaris compiler.
258         Fix support for calling code compiled with Oracle's Sparc
259           Solaris compiler.
260         Testsuite fixes for Tru64 Unix.
261         Additional platform support.
262
263 3.0.9 Dec-31-09
264         Add AVR32 and win64 ports.  Add ARM softfp support.
265         Many fixes for AIX, Solaris, HP-UX, *BSD.
266         Several PowerPC and x86-64 bug fixes.
267         Build DLL for windows.
268
269 3.0.8 Dec-19-08
270         Add *BSD, BeOS, and PA-Linux support.
271
272 3.0.7 Nov-11-08
273         Fix for ppc FreeBSD.
274         (thanks to Andreas Tobler)
275
276 3.0.6 Jul-17-08
277         Fix for closures on sh.
278         Mark the sh/sh64 stack as non-executable.
279         (both thanks to Kaz Kojima)
280
281 3.0.5 Apr-3-08
282         Fix libffi.pc file.
283         Fix #define ARM for IcedTea users.
284         Fix x86 closure bug.
285
286 3.0.4 Feb-24-08
287         Fix x86 OpenBSD configury.
288
289 3.0.3 Feb-22-08
290         Enable x86 OpenBSD thanks to Thomas Heller, and
291         x86-64 FreeBSD thanks to Björn König and Andreas Tobler.
292         Clean up test instruction in README.
293
294 3.0.2 Feb-21-08
295         Improved x86 FreeBSD support.
296         Thanks to Björn König.
297
298 3.0.1 Feb-15-08
299         Fix instruction cache flushing bug on MIPS.
300         Thanks to David Daney.
301
302 3.0.0 Feb-15-08
303         Many changes, mostly thanks to the GCC project.
304         Cygnus Solutions is now Red Hat.
305
306   [10 years go by...]
307
308 1.20 Oct-5-98
309         Raffaele Sena produces ARM port.
310
311 1.19 Oct-5-98
312         Fixed x86 long double and long long return support.
313         m68k bug fixes from Andreas Schwab.
314         Patch for DU assembler compatibility for the Alpha from Richard
315         Henderson.
316
317 1.18 Apr-17-98
318         Bug fixes and MIPS configuration changes.
319
320 1.17 Feb-24-98
321         Bug fixes and m68k port from Andreas Schwab. PowerPC port from
322         Geoffrey Keating. Various bug x86, Sparc and MIPS bug fixes.
323
324 1.16 Feb-11-98
325         Richard Henderson produces Alpha port.
326
327 1.15 Dec-4-97
328         Fixed an n32 ABI bug. New libtool, auto* support.
329
330 1.14 May-13-97
331         libtool is now used to generate shared and static libraries.
332         Fixed a minor portability problem reported by Russ McManus
333         <mcmanr@eq.gs.com>.
334
335 1.13 Dec-2-96
336         Added --enable-purify-safety to keep Purify from complaining
337         about certain low level code.
338         Sparc fix for calling functions with < 6 args.
339         Linux x86 a.out fix.
340
341 1.12 Nov-22-96
342         Added missing ffi_type_void, needed for supporting void return 
343         types. Fixed test case for non MIPS machines. Cygnus Support 
344         is now Cygnus Solutions. 
345
346 1.11 Oct-30-96
347         Added notes about GNU make.
348
349 1.10 Oct-29-96
350         Added configuration fix for non GNU compilers.
351
352 1.09 Oct-29-96
353         Added --enable-debug configure switch. Clean-ups based on LCLint 
354         feedback. ffi_mips.h is always installed. Many configuration 
355         fixes. Fixed ffitest.c for sparc builds.
356
357 1.08 Oct-15-96
358         Fixed n32 problem. Many clean-ups.
359
360 1.07 Oct-14-96
361         Gordon Irlam rewrites v8.S again. Bug fixes.
362
363 1.06 Oct-14-96
364         Gordon Irlam improved the sparc port. 
365
366 1.05 Oct-14-96
367         Interface changes based on feedback.
368
369 1.04 Oct-11-96
370         Sparc port complete (modulo struct passing bug).
371
372 1.03 Oct-10-96
373         Passing struct args, and returning struct values works for
374         all architectures/calling conventions. Expanded tests.
375
376 1.02 Oct-9-96
377         Added SGI n32 support. Fixed bugs in both o32 and Linux support.
378         Added "make test".
379
380 1.01 Oct-8-96
381         Fixed float passing bug in mips version. Restructured some
382         of the code. Builds cleanly with SGI tools.
383
384 1.00 Oct-7-96
385         First release. No public announcement.
386
387
388 Authors & Credits
389 =================
390
391 libffi was originally written by Anthony Green <green@moxielogic.com>.
392
393 The developers of the GNU Compiler Collection project have made
394 innumerable valuable contributions.  See the ChangeLog file for
395 details.
396
397 Some of the ideas behind libffi were inspired by Gianni Mariani's free
398 gencall library for Silicon Graphics machines.
399
400 The closure mechanism was designed and implemented by Kresten Krab
401 Thorup.
402
403 Major processor architecture ports were contributed by the following
404 developers:
405
406 aarch64         Marcus Shawcroft, James Greenhalgh
407 alpha           Richard Henderson
408 arm             Raffaele Sena
409 blackfin        Alexandre Keunecke I. de Mendonca
410 cris            Simon Posnjak, Hans-Peter Nilsson
411 frv             Anthony Green
412 ia64            Hans Boehm
413 m32r            Kazuhiro Inaoka
414 m68k            Andreas Schwab
415 m88k            Miod Vallat
416 microblaze      Nathan Rossi
417 mips            Anthony Green, Casey Marshall
418 mips64          David Daney
419 moxie           Anthony Green
420 nios ii         Sandra Loosemore
421 openrisc        Sebastian Macke
422 pa              Randolph Chung, Dave Anglin, Andreas Tobler
423 powerpc         Geoffrey Keating, Andreas Tobler, 
424                          David Edelsohn, John Hornkvist
425 powerpc64       Jakub Jelinek
426 s390            Gerhard Tonn, Ulrich Weigand
427 sh              Kaz Kojima
428 sh64            Kaz Kojima
429 sparc           Anthony Green, Gordon Irlam
430 tile-gx/tilepro Walter Lee
431 vax             Miod Vallat
432 x86             Anthony Green, Jon Beniston
433 x86-64          Bo Thorsen
434 xtensa          Chris Zankel
435
436 Jesper Skov and Andrew Haley both did more than their fair share of
437 stepping through the code and tracking down bugs.
438
439 Thanks also to Tom Tromey for bug fixes, documentation and
440 configuration help.
441
442 Thanks to Jim Blandy, who provided some useful feedback on the libffi
443 interface.
444
445 Andreas Tobler has done a tremendous amount of work on the testsuite.
446
447 Alex Oliva solved the executable page problem for SElinux.
448
449 The list above is almost certainly incomplete and inaccurate.  I'm
450 happy to make corrections or additions upon request.
451
452 If you have a problem, or have found a bug, please send a note to the
453 author at green@moxielogic.com, or the project mailing list at
454 libffi-discuss@sourceware.org.