1BINARY INSTALL, BUILD, TOOLS, LOCALIZING  (last updated 2019-02-22)
2-------------------------------------------------------------------
3
4CONTENTS
5
6 (1) MINIMUM INSTALL
7 (2) BUILD, TEST AND INSTALL newLISP FROM SOURCE
8 (3) UNINSTALL
9 (4) COMMENTS FOR COMPILING AND LINKING
10 (5) LOCALIZATION
11 (6) RUNNING newLISP IN A SHELL OR CONSOLE WINDOW
12 (7) COMMENTS ABOUT LIBFFI
13
14
15(1) MINIMUM INSTALL
16-------------------
17
18For a minumum install, only the executable file, newlisp iin on UNIX like
19operating systems or newlisp.exe on Win32/64, needs to be moved to a directory
20in the executable path, i.e.  /usr/local/bin/newlisp on Unix.
21No other files are required.
22
23If modules are installed the environment NEWLISPDIR can be defined to point to
24the modules parent directory. If NEWLISPDIR is not defined, newLISP sets
25it to /usr/local/share/newlisp during startup on MacOS, Linux, BADs and other
26UNIX.
27
28To reduce an exisiting UNIX install to a minimum installation, remove all
29files in /usr/share/newlisp and /usr/local/share/doc/newlisp and the executable
30files /usr/local/bin/newlisp-edit and /usr/local/bin/newlispdoc.
31
32On Mac OX X remove also the files under the Applications icon in the
33Applications folder. On Windows remove all file except newlisp.exe in
34C:/Program Files/newlisp.
35
36
37(2) BUILD AND INSTALL newLISP FROM SOURCE
38-----------------------------------------
39
40Un-tar/gunzip the distribution file newlisp_9.x.x.tgz :
41
42    tar xzvf newlisp_9.x.x.tgz
43
44Change the current directory in to newlisp_x.x.x/
45
46and check what OS flavor make would detect, type:
47
48    ./configure
49
50This will automatically detect the platforms Linus, MacOS X, FreeBSD,
51OpenBSD, NetBSD, SunOS/Solaris and Win32. To build on Win32 a MinGW
52installation hosted by MSYS is required. See http://mingw.org.
53
54If you agree with the platform detected by configure type:
55
56    make
57
58After building has finished type:
59
60    make testall
61
62or for a shorter version
63
64    make test
65
66when all tests are passed OK do a
67
68    sudo make install
69
70or if already in superuser mode:
71
72    make install
73
74to find out all make options, use:
75
76    make help
77
78For shorter ouput, 'make test' can be used instead of 'make check'.
79Using 'make testall' or 'make checkall' more tests and a speed
80benchmark are performed.
81
82
83(3) UNINSTALL
84-------------
85
86On MacOS, Linux, BSDs and other UNIX:
87
88    sudo make uninstall
89
90or if installed with: make install_home
91
92    make uninstall_home
93
94To manually uninstall on Windows remove all files in
95c:\Program files\newlisp
96
97
98(4) COMMENTS FOR COMPILING AND LINKING
99--------------------------------------
100
101If skipping the ./configure step and just doing make, the
102configure script will be called automatically if no makefile_build
103can be found, or else the existing makefile_build will be used.
104
105The standard configure script assumes READLINE support, discovers
106the default memory model (32 bit vs 64 bit) and copies one of the
107pre-fabricated makefiles to makefile_build. The standard
108configure forces 32-bit on MacOS X even if 64-bit is
109detected. To force compile for 64-bit either choose an appropiate
110make file manually or use configure-alt.
111
112If compiling with READLINE fails on Linux , it may be due to missing
113readline.h and history.h include files. In this case the package
114'libreadline5-dev' or a later version has to be installed.
115
116Most of the makefile_xxxxx can also be used this way:
117
118    make -f makefile_xxxxx
119
120but always read the contents of makefile_xxxxx first, as it sometimes
121contains specific instructions.
122
123
124configure-alt script
125--------------------
126This script can be used as an alternative to the standard configure
127script. Instead of creating a makefile_build from existing pre-
128configured makefile configure-alt does an analysis of the capabilities
129found on the target platform and then custom generates a makefile_build.
130
131Numerous options can be configured. To find all options use:
132
133    ./configure-alt --help
134
135For questions and support for configure-alt, please contact:
136
137     Ted Walther <ted@reactor-core.org>.
138
139Note thet configure-alt uses a version-numbered directory for the
140installation.
141
142Avoid having installs from the standard 'configure' and alternate
143'configure-alt' script on the same machine!
144
145NOTE, that newLISP can only be compiled for the IPL32 and LP64 memory
146models.
147
148configure-alt will configure a 64-bit (LP64) application by default
149if the platform and tools are capable. The standard configure script
150will configure a makefile for 32-bit (ILP32) by default. This may
151change in the future.
152
153Compiling and running newlisp-x.x.x/util/types.c will produce:
154
155IPL32 memory model
156------------------
157type      bytes
158---------------
159char        1
160char *      4
161void *      4
162short int   2
163int         4
164long        4
165long int    4
166long long int  8
167size_t      4
168float       4
169double      8
170long double 16
171wchar_t     4
172size_t      4
173off_t       8
174time_t      4
175
176
177LP64 memory model
178-----------------
179type      bytes
180---------------
181char        1
182char *      8
183void *      8
184short int   2
185int         4
186long        8
187long int    8
188long long int  8
189size_t      8
190float       4
191double      8
192long double 16
193wchar_t     4
194size_t      8
195off_t       8
196time_t      8
197
198
199(5) LOCALIZATION
200----------------
201
202The PCRE Regular Expressions code can be localized to your country/language
203It comes with default character tables for English, but should work well
204for other languages when using the UTF-8 version of newLISP. For correct working of
205other string functions in your country/language a localizable 'C' library/OS
206may have to be used. The names of newLISP functions can be localized during
207runtime without performance loss, (see newlisp_manual.html).
208
209There are UTF-8 versions/makefiles available in the source distribution.
210See the chapter about 'Customization, localization and UTF-8' in the manual.
211
212(6) RUNNING newLISP IN A SHELL OR CONSOLE WINDOW
213------------------------------------------------
214
215On all platforms simply execute:
216
217    newlisp
218
219On Windows the execution path of newlisp.exe should be added to the environment
220during installation. On all other platforms the newlisp binary should be in
221/usr/local/bin/newlisp or /usr/bin/newlisp.
222
223
224(7) COMMENTS ABOUT LIBFFI
225-------------------------
226
227Here some general comments for usage of libffi in newLISP:
228
229The extended ffi requiring libffi and ffi.h for compiling, was only
230introduced a short time ago in February of 2012. Except for module/gsl.lsp
231all other modules shipped in the distributions work with the older simple
232form of import not requiring libffi. Both are documented in the manual.
233
234The configure utility will pick libffi enabled makefiles only for Windows,
235MacOS and Linux. For all other OS it will pick makefiles not requiring libffi.
236
237Ted Walther's configure-alt utility, which automatically configures the
238memory model (32-bit or 64-bit) never configures for the new extended ffi
239using libffi.
240
241The path for ffi.h chosen in newlisp.h, is only valid for OSX and UBUNTU
242Linux, for all other OSs the path might be different and has to be adjusted.
243
244In any case, libffi from http://sourceware.org/libffi/ is pretty easy to make
245for most platforms. On Windows, Mac OSX and UBUNTU Linux it is already
246installed by default.
247
248
249                                 +++
250