*************************************************
*** COMPILING and INSTALLING QORE FROM SOURCE ***
*************************************************

see README-GIT to lean how to build qore from git sources
see README-WINDOWS for info specific to the windows builds

Build Requirements
------------------
*) a C++ compiler with C++11 support

*) flex 2.5.31 (or greater -- 2.5.4 or before will NOT work, sorry.  flex 2.5.37 or greater is recommended)
qore requires this very new version of flex in order to build a reentrant parser.  I was not able to build a reentrant parser with earler versions of flex (including 2.5.4).  many older linux distributions ship with flex 2.5.4; this version will not work and the configure script will exit an error message if only this version is found.  You can download flex 2.5.37 at:
	 http://sourceforge.net/projects/flex
To use a flex in an alternative location, set the environment variable LEX before running configure (i.e.: LEX=/usr/local/bin/flex configure ...)

*) bison 1.85 (or better, 2.* versions are fine)
qore requires bison 1.85+ to be able to interface properly with the scanner produced by flex 2.5.3*+

*) POSIX threads
OS-level POSIX thread support is required to build qore.

*) PCRE 6 or higher (earlier versions will probably work as well)
for Perl-Compatible Regular Expressions, Qore now uses the pcre library for regular expression support instead of relying on POSIX regex functions.  tested with pcre 6.3 & 6.6
	http://www.pcre.org
if you have the PCRE headers and libraries in a location the configure script cannot find, then you can either use the --with-pcre-libs and --with-pcre-libraries options, or set the PCRE_DIR environment variable before running configure

*) openssl 0.9.7 or higher (0.9.8 or better recommended)
	http://www.openssl.org
if you have the open headers and libraries in a location the configure script cannot find, then you can either use the --with-openssl-libs and --with-openssl-libraries options, or set the OPENSSL_DIR environment variable before running configure

*) bzlib 1.0.4 or higher (earlier versions may work as well)

*) zlib 1.1.3 or higher (some earlier versions will work as well)

*) mpfr 2.4.1 or higher (some eariler versions may work but have not been tested) - version 3.1+ recommended + note that the gmp library is also required to build mpfr
   	http://www.mpfr.org/
	http://gmplib.org/
This is for the arbitrary-precision numeric type introduced with Qore 0.8.6

CMAKE Build
-----------

The cmake build is the recommended build method; support for autotools builds will likely be removed in a future
release.

example from the root source directory:

    mkdir build; cd build
    cmake .. -DCMAKE_INSTALL_PREFIX=/usr
    make && make docs && sudo make install

Autotools Build
---------------

Note that the cmake build is the recommended build method; support for autotools builds will likely be removed in a
future release.

"configure" Option Overview
---------------------------
--enable-64bit                      : to build a 64-bit binary (support for x86_64, sparc, and pa-risc architectures)
--disable-static                    : to disable builing a static libqore.a library
--disable-debug                     : to disable debugging code - if you are not planning on debugging the qore language itself then it is highly advised to include this flag, as enabling debugging in qore slows down the language a great deal
--prefix=<dir>                      : default=/usr/local = qore in /usr/local/bin, libraries in /usr/local/lib, modules in /usr/local/lib/qore-module-api-<ver>/
--with-openssl-dir=<dir>            : directory of openssl installation
--with-pcre-dir=<dir>               : directory of pcre installation
--with-zlib-dir=<dir>               : directory of zlib installation
--with-mpfr-dir=<dir>               : directory of mpfr installation
--with-gmp-dir=<dir>                : directory of gmp installation

rarely used options
-------------------
--disable-single-compilation-unit   : to disable building all related files at once in each directory.  This is enabled by default because it normally makes for much quicker compiles and also allows the compiler to optimize based on the entire source at the same time.  However if you don't have enough memory (at least 1G RAM) then you should turn it off, otherwise leave it on.

********************************
recommended configure arguments: configure --disable-static --disable-debug --prefix=/usr
********************************

To build qore, run the following commands:

   ./configure [options]  (for non-debugging builds I recommend: configure --disable-static --disable-debug --prefix=/usr)
   make

Installing Qore
---------------
To install qore once it's been built, run the following commands:

   make install

by default the program will be installed in /usr/local/bin and libraries in /usr/local/lib, with language modules in /usr/local/lib/qore-<ver>.  This can be changed with the --prefix option to configure.  The name of the binary is "qore"

OS-Specific Issues
------------------
*) Linux:
there are no particular issues on Linux, this is one of the main development platforms.
Various distributions have been tested: FC3-8, Gentoo, Ubuntu, ARCH, etc

*) FreeBSD:
building from source - for FreeBSD up to 9.1: flex has to be installed from ports
as long as all the prerequisite libraries are installed, the configure script should set up Qore for building and installing on FreeBSD without the need for any particular configure options or environment variables
note that there is a freebsd port of Qore available (http://www.freebsd.org/cgi/cvsweb.cgi/ports/lang/qore)

*) Darwin - OS/X
One of the main development platforms for Qore.  No particular issues with recent versions of OS/X.  Note that there is a port available for Qore in macports (https://trac.macports.org/browser/trunk/dports/lang/qore/Portfile); there are also ports for the development version and for many binary modules

*) Solaris:
Supported with g++ with c++11 support, Oracle Studio CC not tested recently

*) HP-UX
Qore supported HP-UX in the past, but it has not been tested for a few years.
Itanium should be supported better than PA-RISC.
With aCC, PA-RISC 2.0 32-bit binaries are produced in 32-bit mode, with --enable-64-bit, PA-RISC 2.0 64-bit binaries are produced
With g++, PA-RISC 1.1 32-bit binaries are produced in 32-bit mode, with --enable-64-bit, PA-RISC 2.0 64-bit binaries are produced

*) Windows
A fully functional version of Qore can now be build for Windows; see README-WINDOWS for more information

CPU Support
-----------
*) gcc with i386, x86_64, ppc, sparc32, itanium, aCC with itanium, CC (SunPro or Sun Studio CC) with i386, x86_64, sparc32: fast inline assembly atomic operations are supported for reference counting, as well as a SMP cache invalidation optimization for temporary objects (temporary objects do not require a cache invalidation);
*) CPU stack guard is working on all above combinations and with g++ and aCC with PA-RISC as well
*) all others: a pthread mutex is used to ensure atomicity for reference counting.
The cache invalidation optimization is not safe on platforms without an atomic reference counting implementation, therefore is not implemented for these platforms

Modules
-------
Note that binary modules are delivered separately from the qore library, see the file README-MODULES for more information.
