README: forth-gmpfr distribution, version 0.9.2 -- dnw, 05-Feb-2021 This source release includes bindings and tests known to work with gmp 6.2.1 and mpfr 4.1.0 and 64-bit intel systems. Our experience with the upward compatibility of new releases of gmp and mpfr has been very good, so we have no reason to think that future versions of gmp and mpfr would not continue to work with this version of forth-gmpfr. It might also still work with gmp 5.x.y and mpfr 3.x.y, except that the word RFA-UROOT now calls the mpfr function mpfr_rootn_ui instead of mpfr_root, deprecated (since mpfr 4.0.y) but still present in mpfr 4.1.0. TESTS We have tested under macOS 11.2 (Big Sur) and Linux Mint 19.3 with gforth 0.7.9_20191226, iForth 6.9.35, and pfe 0.33.73w. That version of pfe is from the dnw branch at Guido Draheim's SourceForge site: https://sourceforge.net/projects/pfe/ https://sourceforge.net/p/pfe/code/HEAD/tree/branches/dnw/pfe-33/ To run the tests, load gmpfr-test.fs from any of the three forth's, in the directory into which forth-gmpfr-x.x.x.zip inflates, after installing libgmp, libmpfr, and the platform specific bindings. GMP AND MPFR INSTALLATION The gmp and mpfr bindings require that libgmp and libmpfr be compiled and installed in an appropriate directory tree. It is important to have access to the include file gmp.h. We prefer the default /usr/local tree, in spite of the fact that one has to temporarily disable System Integrity Protection in macOS Catalina and later to get write access, even for root. Here are the links: http://gmplib.org https://www.mpfr.org The html or pdf documentation at these sites is indispensable for using the gmp and mpfr parts of forth-gmpfr, and is also the best source for the compilation and installation of libgmp and libmpfr. It is essential to install gmp first, because mpfr links to it and has to include gmp.h. For some time now, the gcc in macOS Xcode has used either LLVM or CLANG, which are problematic for pfe and/or its external loadable modules. Fortunately there is a High Performance Computing (HPC) binary distribution of gcc for macOS which works fine: http://hpc.sourceforge.net BINDING LIBRARY INSTALLATION gforth ------ With gforth, the binding libraries are built and installed the first time the binding description files libgmp-gforth.fs and libmpfr-gfoth.fs are loaded. This can done be by running gforth directly on them, or by running gforth on gmpfr.fs, which includes them. The C source files for the bindings and resultant object files and dynamic libraries end up in ~/.cache/gforth/amd64/libccc-tmp on our macOS and linux systems. They are not regenerated on subsequent runs, which saves loading time. When modifying the binding description files, things can get out of sync, resulting in failure to recognize the c-function names. That can be correct by running once with CLEAR-LIBS uncommented in libgmp-gforth.fs and/or libmpfr-gfoth.fs, then commenting out CLEAR-LIBS for subsequent runs of gmpfr-fs. Or one can skip the uncommenting and manually delete the files in libcc-tmp. In normal usage, there is nothing to do beyond simply loading gmpfr.fs, as long as the binding and other dependent files are in the load path. iForth ------ With iForth, gmpfr.fs loads the binding description files libgmp-iforth.frt and libmpfr-iforth.frt. It is assumed that two supplemental C libraries, libgmp_iforth and libmpfr_iforth, have been compiled and installed beforehand. They contain gmp and mpfr functions that need special treatment in the binding process. Scripts are provided for that under macOS and linux. pfe ---- With pfe, C binding libraries libgmp-pfe.so and libmpfr-pfe.so must be preinstalled as pfe loadable modules. Scripts are provided for that under macOS and linux. FILES The forth-gmpfr.zip archive inflates into a folder named forth-gmpfr, which contains all of the files below plus this README. When it is the current working directory, the folder is intended to be a complete runtime environment for its forth source files and system executable scripts, assuming that libgmp and libmpfr have been installed. gmpfr ----- gmpfr.fs This is the main library, which defines the forth-gmpfr glossary, written in ANS Forth. It loads the bindings, gcrstack.fs, parsing.fs, and mstrings.fs. See its introductory comments for how to select any subset of its five sublibraries: MULTI-INTEGERS, MULTI-RATIONALS, MULTI-FLOATS, RELIABLE-FLOATS, RANDOMS. gmpfr-test.fs Loads gmpfr.fs and all the testers, including display and errors. garbage collected record stack ------------------------------ gcrstack.fs Required by gmpfr.fs. gcrstack-test.fs Loads gcrstack.fs, ttester-xf, xtester-errors, tester-display. gforth bindings --------------- libgmp-gforth.fs Binding descriptions for gforth's C-function libmpfr-gforth.fs interface, loaded by gmpfr.fs. iForth bindings --------------- libgmp-iforth.frt Binding descriptions for iForth's dynlibs, libgmp-iforth.c plus supplementary C source that has to libmpfr-iforth.frt be compiled and installed. These require libmpfr-iforth.c current versions of dynlibs.frt and miscutil.frt. mklibgmp-iforth-macos Scripts to compile supplementary libraries, mklibgmp-iforth-linux with default installation under /usr/local. mklibmpfr-iforth-macos mklibmpfr-iforth-linux pfe bindings ------------ libgmp-pfe.fs Binding descriptions for pfe's bindlib. They libmpfr-pfe.fs load bindlib.fs. libgmp-pfe.c C source for gmp and mpfr bindings, generated libgmp-pfe-dll.c by bindlib.fs/ libmpfr-pfe.c libmpfr-pfe-dll.c bindlib.fs C binding source generator. To generate bindlib-example.fs the C files above, load the binding bindlib-example.c descriptions above with bindlib.fs in the path. Loads dstrings.fs and dstring-utils.fs when the forth is not pfe. mklibgmp-pfe-macos Scripts to compile pfe bindings, with mklibgmp-pfe-linux default installation under /usr/local. mklibmpfr-pfe-macos mklibmpfr-pfe-linux miscellaneous ------------- libgmp-test.fs Incomplete direct tests for the gmp bindings. applications ------------ complex-rf.fs Port of the FSL complex lexicon and tests complex-rf-test.fs to forth-gmpfr and rftester. zgamma-rf.fs Reliable float version of the complex gamma function by Marcel Hendrix, ported to standard Forth by Krishna Myneni. testers ------- ttester-xf.fs tester-display.fs xtester-errors.fs ftester-errors.fs btester.fs btester-errors.fs qtester.fs qtester-errors.fs mftester.fs mftester-errors.fs rftester.fs rftester-errors.fs strings and parsing ------------------- mstrings.fs Loaded by gmpfr.fs. parsing.fs Loaded by mstrings.fs. dstrings.fs Used by... dstring-utils.fs ...bindlib-pfe.fs. logs ---- gmpfr.log gmplib-ext.log gcrstack.log