BINARY INSTALL, BUILD, TOOLS, LOCALIZING  (last updated 2011-11-14
-------------------------------------------------------------------

CONTENTS

 (1) WIN32 BINARY DISTRIBUTION INSTALLATION
 (2) Mac OS X BINARY DISTRIBUTION INSTALLATION
 (3) UBUNTU Linux DEBIAN DISTRIBUTION INSTALLATION
 (4) MINIMUM INSTALL
 (5) BUILD, TEST AND INSTALL newLISP FROM SOURCE
 (6) COMMENTS FOR COMPILING AND LINKING
 (7) LOCALIZATION
 (8) UNINSTALL
 (9) RUNNING newLISP IN A SHELL OR CONSOLE WINDOW
(10) RUNNING THE newLISP-GS GRAPHICAL FRONTEND
(11) INSTRUCTIONS FOR CUSTOMIZED INSTALL AND PACKAGE CREATORS
(12) COMMENTS ABOUT LIBFFI


(1) WIN32 BINARY DISTRIBUTION INSTALLATION
------------------------------------------

The Win32 binary distribution comes packed as a Win32 installer
application. After downloading a file:

    newlisp-xxxx-win-gs-xxx.exe

double click on the downloaded file and follow instructions. xxxx and xxx 
are the version numbers for newLISP and the newLISP-GS the GUI frontend. 
On Win32 a ASCII version of newlisp.exe capable of ISO/IEC 8859 code pages 
is installed. A UTF-8 capable version is available from the newlisp download 
directory at: http://www.newlisp.org/downloads/UTF-8_win32/


(2) Mac OS X BINARY DISTRIBUTION INSTALLATION
---------------------------------------------

After downloading double-click on the Mac OS X disk image file:

    newlisp-xxxx-ppc.dmg     # for older PPC type Macs
or
    newlisp-xxxx-intel.dmg   # since at least end of 2007
    
This installs an applications icon in the Mac OS X Applications folder.
On Mac OS X a UTF-8 capable version is installed by default. On both,
Intel and PPC architectures Mac OS X v10.5 Leopard is minimum.


(3) UBUNTU Linux DEBIAN DISTRIBUTION INSTALLATION
-------------------------------------------------

Double click the file:

    newlisp-xxxx-x_i386.deb
or
    newlisp-xxxx-utf8_i386.deb
    
This will bring up the debian installer application.

On some UBUNTU libraries libreadline and libffi may have to be installed
when making from source:

    sudo apt-get install libreadline6 libreadline6-dev  
and
    apt-get install libffi-dev 


(4) MINIMUM INSTALL
-------------------

For a minumum install, only the executable file: newlisp (or newlisp.exe
on Win32) needs to be moved to a directory in the executable path, i.e. 
/usr/bin/newlisp on Unix. No other files are required. This installation
is recommended for ISPs and other server installations. If modules are
installed the environment NEWLISPDIR should be defined to point to
the modules parent directory. If NEWLISPDIR is not defined, newLISP sets
it to /usr/share/newlisp during startup.

To reduce an exisiting UNIX install to a minimum installation, remove all 
files in /usr/share/newlisp and /usr/share/doc/newlisp and the executable 
files /usr/bin/newlisp-edit and /usr/bin/newlispdoc.

On Mac OX X remove also the files under the Applications icon in the 
Applications folder. On Windows remove all file except newlisp.exe in 
C:/Program Files/newlisp.


(5) BUILD AND INSTALL newLISP FROM SOURCE
-----------------------------------------

Un-tar/gunzip the distribution file newlisp_9.x.x.tgz :

    tar xzvf newlisp_9.x.x.tgz

Change the current directory in to newlisp_x.x.x/

and check what OS flavor make would detect, type:

    ./configure

This will automatically detect the platforms Linus, MacOS X, FreeBSD,
OpenBSD, NetBSD, SunOS/Solaris and Win32. To build on Win32 a MinGW
installation hosted by MSYS is required. See http://mingw.org.

If you agree with the platform detected by configure type:

    make
 
After building has finished type:

    make testall

or for a shorter version

    make test

when all tests are passed OK do a

    sudo make install
    
or if already in superuser mode:

    make install

to find out all make options, use:

    make help

For shorter ouput, 'make test' can be used instead of 'make check'.
Using 'make testall' or 'make checkall' more tests and a speed
benchmark are performed.


(6) COMMENTS FOR COMPILING AND LINKING
--------------------------------------

If skipping the ./configure step and just doing make, the
configure script will be called automatically if no makefile_build
can be found, or else the existing makefile_build will be used.

The standard configure script assumes READLINE support, discovers 
the default memory model (32 bit vs 64 bit) and copies one of the 
pre-fabricated makefiles to makefile_build. The standard 
configure forces 32-bit on MacOS X even if 64-bit is
detected. To force compile for 64-bit either choose an appropiate
make file manually or use configure-alt.

If compiling with READLINE fails on Linux , it may be due to missing 
readline.h and history.h include files. In this case the package 
'libreadline5-dev' has to be installed.

On some platforms the warning message "ANSI does not support long long"
will be issued for every file compiled. This message can be discarded 
and does not occur on newer versions of GCC. The 'long long' data type 
is not used anywhere in the newLISP source but part of some header files 
of the GCC installation.

Most of the makefile_xxxxx can also be used this way:

    make -f makefile_xxxxx

but always read the contents of makefile_xxxxx first, as it sometimes
contains specific instructions.


configure-alt script
--------------------
This script can be used as an alternative to the standard configure
script. Instead of creating a makefile_build from existing pre-
configured makefile configure-alt does an analysis of the capabilities
found on the target platform and then custom generates a makefile_build.

Numerous options can be configured. To find all options use:

    ./configure-alt --help 

For questions and support for configure-alt, please contact:

     Ted Walther <ted@reactor-core.org>.

Note thet configure-alt uses a version-numbered directory for the 
installation. By default it also uses /usr/local instead of /usr
as a prefix for the bin, man, share/newlisp and share/doc/newlisp
directories.

Avoid having installs from the standard 'configure' and alternate
'configure-alt' script on the same machine!

NOTE, that newLISP can only be compiled for the IPL32 and LP64 memory
models.

configure-alt will configure a 64-bit (LP64) application by default 
if the platform and tools are capable. The standard configure script
will configure a makefile for 32-bit (ILP32) by default. This may 
change in the future.

Compiling and running newlisp-x.x.x/util/types.c will produce:

IPL32 memory model
------------------
type      bytes
---------------
char        1
char *      4
void *      4
short int   2
int         4
long        4
long int    4
long long int  8
size_t      4
float       4
double      8
long double 16
wchar_t     4
size_t      4
off_t       8
time_t      4


LP64 memory model
-----------------
type      bytes
---------------
char        1
char *      8
void *      8
short int   2
int         4
long        8
long int    8
long long int  8
size_t      8
float       4
double      8
long double 16
wchar_t     4
size_t      8
off_t       8
time_t      8


(7) LOCALIZATION
----------------

The PCRE Regular Expressions code can be localized to your country/language 
It comes with default character tables for English, but should work well
for other languages when using the UTF-8 version of newLISP. For correct working of 
other string functions in your country/language a localizable 'C' library/OS 
may have to be used. The names of newLISP functions can be localized during 
runtime without performance loss, (see newlisp_manual.html).

There are UTF-8 versions/makefiles available in the source distribution.
See the chapter about 'Customization, localization and UTF-8' in the manual.


(8) UNINSTALL
-------------

On Win32 use the uninstall application from the newlisp applications
menu.

On Mac OS X double click on the uninstall script in the diskimage of
the installer package.

On UBUNTU Linux execute:

    sudo dpkg -r newlisp

On all other UNIX, to uninstall if installed with make install do:

    sudo make uninstall

or if installed with: make install_home

    make uninstall_home
    
To manually uninstall on Win32 remove all files in c:\Program files\newlisp

On Mac OS X and other UNIX remove all files in /usr/share/newlisp and
/usr/share/doc/newlisp and the executable files /usr/bin/newlisp,
/usr/bin/newliso-edit and /usr/bin/newlispdoc. On Mac OX X also remove
the newLISP icon in the Applications folder.

   
(8) RUNNING newLISP IN A SHELL OR CONSOLE WINDOW
------------------------------------------------

On all platforms simply execute:
 
    newlisp

On Win32 the execution path of newlisp.exe was added to the environment 
during installation. On all other platforms the newlisp binary is in 
/usr/bin/newlisp or when using the home install in $HOME/bin
where $HOME is the the home directory of the user taken from the environment
variable HOME.


(10) RUNNING THE newLISP-GS GRAPHICAL FRONTEND
----------------------------------------------

On Win32 and Mac OS X a Java based syntaxhighlighting editor is installed in
in the Applications menus. In other UNIX execute:
    
    newlisp-edit
 
from the command line in a terminal window.
The editor needs a Java runtime environment JRE version 1.5 as a minimum. 
In case it is not installed it can be obtained from:
http://www.oracle.com/technetwork/java/javase/downloads/index.html

Since Mac OS X 10.7 Lion, Java is not installed by default. Install
Java for OS X 10.7 Lion from here: http://support.apple.com/kb/DL1421

(11) INSTRUCTIONS FOR CUSTOMIZED INSTALL AND PACKAGE CREATORS
-------------------------------------------------------------

By default the configure script uses the following install directories:

/usr/bin/
/usr/share/newlisp
/usr/share/doc/newlisp

As an alternative the configure-alt script can be used. Do a:

    ./configure-alt --help

To see all the options available. Options for install directories, 
readline support, UTF-8 support and memory model used are available.

Like configure, configure-alt creates a makefile_build and makefile_install. 
Both makefiles are used by Makefile when doing:

    make
    make install
    make test

or for a bigger testsuite

    make testall

These are the standard configuration options recommended by newlisp.org:

- use ILP32 memory model as a default, use LP64 only when ILP32 is not 
available on the platform (configure-alt will take the default offered
on the platform)
 
- use the default IPV4 support IPV6 has not been thoroughly tested yet
although it passes the standard qa-net test script (configure-alt
defaults to IPV4.

- use readline support if possible (configure-alt uses it if available)

- offer both packages, one with and one without UTF-8 support on UNIX
installations. newlisp.org ships UTF-8 support on MAC OSX by default and 
ships without UTF-8 support on Win32 (offering UTF-8 binaries on the
newlisp.org website).

- for a brief, one line description of the package, use:

newLISP is a LISP like, general purpose scripting language

- for a longer description of the package, use:
 
newLISP is a scripting language for developing web applications and
programs in general and in the domains of artificial intelligence (AI)
and statistics.


(12) COMMENTS ABOUT LIBFFI
--------------------------

Here some general comments for usage of libffi in newLISP:

The extended ffi requiring libffi and ffi.h for compiling, was only 
introduced a short time ago in February of 2012. Except for module/gsl.lsp 
all other modules shipped in the distributions work with the older simple 
form of import not requiring libffi.

The configure utility will pick libffi enabled makefiles only for Windows, 
OSX and Linux. For all other OS it will pick makefiles not requiring libffi.

Ted Walther's configure-alt utility, which automatically configures the 
memory model (32-bit or 64-bit) never configures for the new extended ffi 
using libffi.

The path for ffi.h chosen in newlisp.h, is only valid for OSX and UBUNTU 
Linux, for all other OSs the path might be different and has to be adjusted. 

In any case, libffi from http://sourceware.org/libffi/ is pretty easy to make 
for most platforms. On Windows, Mac OSX and UBUNTU Linux it is already 
installed by default.


                                 +++
