/*
 * $Id$
 */

HARBOUR
=======

   "The Harbour Project is a Free Open Source Software effort to build
   a multiplatform Clipper language compiler. Harbour consists of the
   xBase language compiler and the runtime libraries with different
   terminal plugins and different databases (not just DBF)"

                                       http://www.harbour-project.org/


HOW TO BUILD AND INSTALL HARBOUR
================================

   For all platforms you'll need:

   * Supported ANSI C compiler
   * GNU Make (3.81 or upper)

   Linux/Darwin/BSD/HP-UX/Solaris
   ------------------------------
      $ export HB_COMPILER=<[gcc]|owatcom|icc|gpp>
      $ export HB_INSTALL_PREFIX=<DIR>
      $ ./make_gnu.sh
      $ sudo ./make_gnu.sh install

      To test it, go to <DIR>/bin directory and type:
      $ ./hbmk2 ../tests/hello.prg
      $ ./hello
      You should see 'Hello world!' on screen.

   Windows
   -------
      Platform specific prerequisites:

      1.) Windows NT or compatible system is required to build Harbour.
      2.) Make sure to have your C compiler of choice properly installed.
          Refer to your C compiler installation and setup instructions for
          details. It's recommended to make sure no tools in your PATH
          belonging to other C compilers are interfering with your setup.
          For the list of supported compilers, please look up the
          relevant section in this file.
      3.) Make sure to have GNU Make. Certain older versions and builds
          are untested and may not work. We recommend the one distributed
          by MinGW team. Use this link to get it:
            https://sourceforge.net/project/showfiles.php?group_id=2435&package_id=23918
          If you have it, you have three choices:
          - Copy mingw32-make.exe or make.exe into a separate directory
            and add that directory to the beginning of your PATH.
            (recommended)
          - Put mingw32-make.exe anywhere in your PATH.
          - Put mingw32-make.exe in Harbour source root dir.
          If you're using MinGW compiler, you don't have to bother with
          all this.

      > set HB_COMPILER=<mingw|msvc|owatcom|bcc|pocc|...>
      > set HB_INSTALL_PREFIX=<DIR>
      > make_gnu.bat install

      To test it, go to <DIR>\bin directory and type:
      > hbmk2 ..\tests\hello.prg
      > hello
      You should see 'Hello world!' on screen.

      NOTE: <DIR> is your destination directory where executables,
            libraries and headers will be created. Use absolute paths
            only. For a peace of mind, avoid using spaces, quotes
            in the name. You can leave it empty, in this case the
            results will be created under the current directory tree.

   Windows with MinGW + msys
   -------------------------
      Make sure to have msys and MinGW properly configured.
      msys should be put in PATH _before_ MinGW.

      > set HB_INSTALL_PREFIX=<DIR>
      > sh make_gnu.sh install

      To test it, go to <DIR>/bin directory and type:
      > hbmk2 ../tests/hello.prg
      > hello
      You should see 'Hello world!' on screen.

   Windows with Cygwin
   -------------------
      Make sure to have Cygwin properly configured.

      > set HB_INSTALL_PREFIX=<DIR>
      > sh make_gnu.sh install

      To test it, go to <DIR>/bin directory and type:
      > hbmk2 ../tests/hello.prg
      > hello
      You should see 'Hello world!' on screen.

      NOTE: <DIR> should use Cygwin drive notation: /cygdrive/c for C:

   DOS
   ---
      > set HB_COMPILER=<[djgpp]|owatcom>
      > set HB_INSTALL_PREFIX=<DIR>
      > make_gnu.bat install

   OS/2
   ----
      > set HB_COMPILER=<[gcc]|owatcom>
      > set HB_INSTALL_PREFIX=<DIR>
      > make_gnu_os2.cmd install


HOW TO ENABLE OPTIONAL COMPONENTS BEFORE BUILD
==============================================

   Some Harbour parts (typically contrib libraries) depend on 3rd
   party components. To make these Harbour parts built, you need
   to tell Harbour where to find the required 3rd party components
   (typically headers).

   On *nix systems most of these 3rd party components will
   automatically be picked up if installed in some well-known
   standard system locations.

   You only need to use manual setup if the dependency isn't available
   on your platform on a system location, or you wish to use
   a non-standard location. Typically you need to do that on non-*nix
   (Windows/DOS/OS2) systems for all packages and for a few packages on
   *nix which aren't available through official package managers
   (ADS Client f.e.). Please see a list of official packages in
   doc/linux1st.txt.

   You can set these environment variables before starting
   the build. Make sure to adjust them to your own directories:

   HB_INC_ADS=C:\ads\acesdk
   HB_INC_ALLEGRO=C:\allegro\include
   HB_INC_BLAT=C:\blat\full\source
   HB_INC_CURL=C:\curl\include
   HB_INC_FIREBIRD=C:\Firebird\include
   HB_INC_FREEIMAGE=C:\FreeImage\Dist
   HB_INC_GD=C:\gd\include
   HB_INC_LIBHARU=C:\libharu\include (defaults to locally hosted version)
   HB_INC_LIBPNG=C:\libpng (defaults to locally hosted version on win/os2/dos)
   HB_INC_MYSQL=C:\mysql\include
   HB_INC_OPENSSL=C:\openssl\inc32
   HB_INC_PGSQL=C:\pgsql\include
   HB_INC_QT=C:\Qt\4.5.1\include
   HB_INC_SQLITE3=C:\sqlite3 (defaults to locally hosted version on win/os2)

   NOTES: - For mingw+msys and cygwin you have to use forward slashes
            and also cygwin drive notation for cygwin.
          - Spaces in directory names isn't currently supported.
          - Don't put the dir inside double quotes.
          - Use absolute paths.

   Darwin (OS X)
   -------------
   1.) Install MacPorts, follow their instructions:
       http://www.macports.org/
   2.) sudo port install allegro freeimage gd2 mysql5-devel postgresql83


SUPPORTED C COMPILERS UNDER DIFFERENT PLATFORMS
===============================================

   You can use abbreviations below as HB_COMPILER values.

   Linux
   -----
   gcc      - GNU C
   gpp      - GNU C++
   owatcom  - Open Watcom C++
   icc      - Intel(R) C/C++

   Darwin/BSD/HP-UX/Solaris
   ------------------------
   gcc      - GNU C

   Windows (recommended)
   -------
   mingw    - MinGW GNU C
   mingw64  - MinGW GNU C x64
   msvc     - Microsoft Visual C++
   msvc64   - Microsoft Visual C++ x64
   msvcia64 - Microsoft Visual C++ IA64

   Windows (supported, but not recommended, features may be missing)
   -------
   owatcom  - Open Watcom C++
   icc      - Intel(R) C/C++
   iccia64  - Intel(R) C/C++ IA64
   bcc      - Borland/CodeGear C++ 4.x and above
   pocc     - Pelles C 4.5 and above
   pocc64   - Pelles C 5.0 x64
   xcc      - Pelles C for xhb
   cygwin   - Cygwin GNU C

   Windows CE
   ----------
   mingwarm - MinGW GNU C ARM
   msvcarm  - Microsoft Visual C++ ARM
   poccarm  - Pelles C 5.0 ARM

   DOS (32-bit)
   ---
   djgpp    - Delorie GNU C
   owatcom  - Open Watcom C++ 9.x and above

   OS/2
   ----
   gcc      - EMX GNU C
   owatcom  - Open Watcom C++


OPTIONS AVAILABLE WHEN BUILDING HARBOUR
=======================================

   You can fine-tune Harbour builds with below listed
   environment variables. All of these are optional.

   General
   -------
   - HB_USER_PRGFLAGS          User Harbour compiler options
   - HB_USER_CFLAGS            User C compiler options
   - HB_USER_LDFLAGS           User linker options for executables
   - HB_USER_AFLAGS            User linker options for libraries
   - HB_USER_MAKEFLAGS         User GNU Make options

   - HB_BIN_INSTALL            Target directory to install executables
   - HB_LIB_INSTALL            Target directory to install libraries
   - HB_INC_INSTALL            Target directory to install language headers
   - HB_DOC_INSTALL            Target directory to install documentation

   Special
   -------
   - HB_BUILD_DLL=yes          To create a full build with .dlls.
                               This is only needed and available for
                               non-GNU Windows compilers. When using this,
                               full clean + install cycles will automatically
                               be executed, so you don't have to explicitly
                               pass them to make_gnu.bat.
   - HB_BUILD_DEBUG=yes        Create a debug build.
   - HB_BUILD_OPTIM=no         Disable C compiler optimizations.
   - HB_CONTRIBLIBS=no         Don't build any contrib libraries.
   - HB_CONTRIBLIBS=[<list>]   Build space separated <list> of contrib
                               libraries. Build all if left empty.
   - HB_CONTRIB_ADDONS=<list>  Build additional libraries stored
                               in the contrib directory.
   - HB_EXTERNALLIBS=no        Don't build any external libraries.
   - HB_EXTERNALLIBS=[<list>]  Build space separated <list> of external
                               libraries. Build all if left empty.
   - HB_EXTERNAL_ADDONS=<list> Build additional libraries stored
                               in the external directory.
   - HB_VISUALC_VER_PRE80=yes  Set this if you're using a pre-8.0
                               (= pre-MSVS 2005) version of MSVC compiler.
   - HB_REBUILD_PARSER=yes     To rebuild the language parsers. Typically
                               you only need this if your are Harbour core
                               developer modifying the parser.
                               This requires GNU Bison 1.28 or upper.

   Cross building
   --------------

   when using make_gnu_xmingwce.sh:
      HB_COMP_PATH=<HARBOUR_NATIVE_BUILD_DIR>\bin\harbour.exe
      HB_PPGEN_PATH=<HARBOUR_NATIVE_BUILD_DIR>\bin\hbpp.exe
   with rest of compilers:
      HB_BIN_COMPILE=<HARBOUR_NATIVE_BUILD_DIR>\bin
      HB_PPGEN_PATH=<HARBOUR_NATIVE_BUILD_DIR>\bin

   You need these when building for a platform different than host.
   For this to work, you will need to point above envvars to
   a native Harbour build available on your system. You don't need
   a full native build, harbour, hbpp and hbmk2 executables are
   enough for the process to succeed.


EXAMPLES
========

   Windows/Windows CE
   ------------------

      NOTES: - All code below should be copied to .bat files.
             - Naturally, you'll need to adapt dirs to valid ones on your system.
               Don't use spaces in dirs.
             - '%1 %2' can be empty, 'clean', 'install' or 'clean install'
               depending on what you want to do.
             - Windows implib creation setup may change in the future.
             - Cross compile setup (HB_BIN_COMPILE, HB_COMP_PATH, HB_PPGEN_PATH)
               is tentative.

      --- MSVC 2008 + SDK
      set WindowsSDKDir=%ProgramFiles%\Microsoft SDKs\Windows\v6.0A\
      call "%ProgramFiles%\Microsoft Visual Studio 9.0\VC\vcvarsall.bat"
      rem
      set HB_COMPILER=msvc
      rem
      set PATH=C:\devl\make-3.81;%PATH%
      set HB_INSTALL_PREFIX=C:\hb-%HB_COMPILER%
      call make_gnu.bat %1 %2 > log-%HB_COMPILER%.txt 2>&1
      ---

      --- MSVC 2008
      call "%ProgramFiles%\Microsoft Visual Studio 9.0\VC\vcvarsall.bat"
      rem
      set HB_COMPILER=msvc
      rem
      set PATH=C:\devl\make-3.81;%PATH%
      set HB_INSTALL_PREFIX=C:\hb-%HB_COMPILER%
      call make_gnu.bat %1 %2 > log-%HB_COMPILER%.txt 2>&1
      ---

      --- MSVC 2008 x64 (requires native x86 Harbour binaries)
      call "%ProgramFiles%\Microsoft Visual Studio 9.0\VC\vcvarsall.bat" x86_amd64
      rem
      set HB_COMPILER=msvc64
      rem
      set HB_BIN_COMPILE=C:\hb-msvc\bin
      set HB_PPGEN_PATH=%HB_BIN_COMPILE%
      rem
      set PATH=C:\devl\make-3.81;%PATH%
      set HB_INSTALL_PREFIX=C:\hb-%HB_COMPILER%
      call make_gnu.bat %1 %2 > log-%HB_COMPILER%.txt 2>&1
      ---

      --- MSVC 2005
      call "%ProgramFiles%\Microsoft Visual Studio 8\VC\vcvarsall.bat"
      rem
      set HB_COMPILER=msvc
      rem
      set PATH=C:\devl\make-3.81;%PATH%
      set HB_INSTALL_PREFIX=C:\hb-%HB_COMPILER%
      call make_gnu.bat %1 %2 > log-%HB_COMPILER%.txt 2>&1
      ---

      --- MSVC .NET 2003 (untested)
      call "%ProgramFiles%\Microsoft Visual Studio .NET 2003\VC7\vcvarsall.bat"
      rem
      set HB_COMPILER=msvc
      set HB_VISUALC_VER_PRE80=yes
      rem
      set PATH=C:\devl\make-3.81;%PATH%
      set HB_INSTALL_PREFIX=C:\hb-%HB_COMPILER%
      call make_gnu.bat %1 %2 > log-%HB_COMPILER%.txt 2>&1
      ---

      --- MinGW GCC
      set PATH=C:\devl\MinGW-433\bin;%PATH%
      rem
      set HB_COMPILER=mingw
      rem
      set HB_INSTALL_PREFIX=C:\hb-%HB_COMPILER%
      call make_gnu.bat %1 %2 > log-%HB_COMPILER%.txt 2>&1
      ---

      --- MinGW GCC with msys
      set PATH=C:\devl\msys\1.0.11\bin;%PATH%
      set PATH=C:\devl\MinGW-433\bin;%PATH%
      rem
      set HB_COMPILER=mingw
      rem
      set HB_INSTALL_PREFIX=C:\hb-%HB_COMPILER%
      sh make_gnu.sh %1 %2 > log-%HB_COMPILER%.txt 2>&1
      ---

      --- MinGW GCC for x64 (requires native x86 Harbour binaries)
      set PATH=C:\devl\MinGW-440-64\bin;%PATH%
      set HB_CCPREFIX=x86_64-pc-mingw32-
      rem
      set HB_COMPILER=mingw64
      rem
      set HB_BIN_COMPILE=C:\hb-mingw\bin
      set HB_PPGEN_PATH=%HB_BIN_COMPILE%
      rem
      set HB_INSTALL_PREFIX=C:\hb-%HB_COMPILER%
      call make_gnu.bat %1 %2 > log-%HB_COMPILER%.txt 2>&1
      ---

      --- MinGW GCC for WinCE/ARM (requires native x86 Harbour binaries)
      set PATH=C:\devl\MinGW-410-ce\opt\mingw32ce\bin;%PATH%
      set HB_CCPREFIX=arm-wince-mingw32ce-
      rem
      set HB_ARCHITECTURE=wce
      set HB_COMPILER=mingwarm
      rem
      set HB_BIN_COMPILE=C:\hb-mingw\bin
      set HB_PPGEN_PATH=%HB_BIN_COMPILE%
      rem
      set HB_INSTALL_PREFIX=C:\hb-%HB_COMPILER%
      call make_gnu.bat %1 %2 > log-%HB_COMPILER%.txt 2>&1
      ---

      --- Open Watcom C++
      SET WATCOM=C:\devl\owatcom-1.8
      SET PATH=%WATCOM%\BINNT;%WATCOM%\BINW;%PATH%
      SET EDPATH=%WATCOM%\EDDAT
      SET INCLUDE=%WATCOM%\H;%WATCOM%\H\NT
      rem
      set HB_COMPILER=owatcom
      rem
      set PATH=C:\devl\make-3.81;%PATH%
      set HB_INSTALL_PREFIX=C:\hb-%HB_COMPILER%
      call make_gnu.bat %1 %2 > log-%HB_COMPILER%.txt 2>&1
      ---

      --- Intel(R) C++
      call "%ProgramFiles%\Intel\Compiler\C++\10.1.014\IA32\Bin\iclvars.bat"
      rem
      set HB_COMPILER=icc
      rem
      set PATH=C:\devl\make-3.81;%PATH%
      set HB_INSTALL_PREFIX=C:\hb-%HB_COMPILER%
      call make_gnu.bat %1 %2 > log-%HB_COMPILER%.txt 2>&1
      ---

      --- Borland/CodeGear C++
      set PATH=C:\devl\bcc55\bin;%PATH%
      rem
      set HB_COMPILER=bcc
      rem
      set PATH=C:\devl\make-3.81;%PATH%
      set HB_INSTALL_PREFIX=C:\hb-%HB_COMPILER%
      call make_gnu.bat %1 %2 > log-%HB_COMPILER%.txt 2>&1
      ---

      --- Pelles C
      set PATH=C:\devl\PellesC-501\bin;%PATH%
      set INCLUDE=C:\devl\PellesC-501\include;C:\devl\PellesC-501\include\win;%INCLUDE%
      set LIB=C:\devl\PellesC-501\lib;C:\devl\PellesC-501\lib\win;%LIB%
      rem
      set HB_COMPILER=pocc
      rem
      set PATH=C:\devl\make-3.81;%PATH%
      set HB_INSTALL_PREFIX=C:\hb-%HB_COMPILER%
      call make_gnu.bat %1 %2 > log-%HB_COMPILER%.txt 2>&1
      ---

      --- Pelles C x64 (requires native x86 Harbour binaries)
      set PATH=C:\devl\PellesC-501-64\bin;%PATH%
      set INCLUDE=C:\devl\PellesC-501-64\include;C:\devl\PellesC-501-64\include\win;%INCLUDE%
      set LIB=C:\devl\PellesC-501-64\lib;C:\devl\PellesC-501-64\lib\win64;%LIB%
      rem
      set HB_COMPILER=pocc64
      rem
      set HB_BIN_COMPILE=C:\hb-pocc\bin
      set HB_PPGEN_PATH=%HB_BIN_COMPILE%
      rem
      set PATH=C:\devl\make-3.81;%PATH%
      set HB_INSTALL_PREFIX=C:\hb-%HB_COMPILER%
      call make_gnu.bat %1 %2 > log-%HB_COMPILER%.txt 2>&1
      ---

      --- Pelles C WinCE/ARM (requires native x86 Harbour binaries)
      set PATH=C:\devl\PellesC-501\bin;%PATH%
      set INCLUDE=C:\devl\PellesC-501\include\wince;C:\devl\PellesC-501\include;%INCLUDE%
      set LIB=C:\devl\PellesC-501\lib;C:\devl\PellesC-501\lib\wince;%INCLUDE%
      rem
      set HB_ARCHITECTURE=wce
      set HB_COMPILER=poccarm
      rem
      set HB_BIN_COMPILE=C:\hb-pocc\bin
      set HB_PPGEN_PATH=%HB_BIN_COMPILE%
      rem
      set PATH=C:\devl\make-3.81;%PATH%
      set HB_INSTALL_PREFIX=C:\hb-%HB_COMPILER%
      call make_gnu.bat %1 %2 > log-%HB_COMPILER%.txt 2>&1
      ---

      --- Cygwin GCC
      set PATH=C:\devl\cygwin\bin;%PATH%
      set C_INCLUDE_PATH=/cygdrive/c/devl/cygwin/usr/include:/cygdrive/c/devl/cygwin/usr/include/w32api
      set LIBRARY_PATH=/cygdrive/c/devl/cygwin/usr/lib:/cygdrive/c/devl/cygwin/usr/lib/w32api
      rem
      set HB_COMPILER=cygwin
      rem
      set HB_INSTALL_PREFIX=/cygdrive/c/hb-%HB_COMPILER%
      sh make_gnu.sh %1 %2 > log-%HB_COMPILER%.txt 2>&1
      ---

      --8<--
      rem ; Add these _before_ above sample scripts to configure 3rd party dependencies.
      rem   For 'mingw' and 'cygwin' you'll have to use forward slashes and
      rem   also cygwin drive notation for 'cygwin'.
      set HB_INC_ADS=C:\ads\acesdk
      set HB_INC_ALLEGRO=C:\allegro\include
      set HB_INC_APOLLO=C:\Apollo\include
      set HB_INC_BLAT=C:\blat\full\source
      set HB_INC_CURL=C:\curl\include
      set HB_INC_FIREBIRD=C:\Firebird\include
      set HB_INC_FREEIMAGE=C:\FreeImage\Dist
      set HB_INC_GD=C:\gd\include
      set HB_INC_MYSQL=C:\mysql\include
      set HB_INC_OPENSSL=C:\openssl\inc32
      set HB_INC_PGSQL=C:\pgsql\include
      set HB_INC_QT=C:\Qt\4.5.1\include
      -->8--

      --8<--
      rem ; Add these _before_ above sample scripts to configure 3rd party dependencies
      rem   for implib generation. This is needed for non-GCC compilers and isn't
      rem   supported for GCC ones.
      set HB_DIR_ADS=C:\ads\acesdk
      set HB_DIR_ALLEGRO=C:\allegro
      set HB_DIR_APOLLO=C:\Apollo
      set HB_DIR_BLAT=C:\blat
      set HB_DIR_CURL=C:\curl
      set HB_DIR_FIREBIRD=C:\Firebird
      set HB_DIR_FREEIMAGE=C:\FreeImage
      set HB_DIR_GD=C:\gd
      set HB_DIR_MYSQL=C:\mysql
      set HB_DIR_OPENSSL=C:\openssl
      set HB_DIR_PGSQL=C:\pgsql
      set HB_DIR_QT=C:\Qt\4.5.1
      rem
      set HB_BUILD_IMPLIB=yes
      -->8--

      --8<--
      rem ; To create installation packages (.exe + .zip),
      rem   replace last line (calling make_gnu.bat) with these two:
      set PATH=C:\devl\NSIS-2.44;%PATH%
      call mpkg_win.bat > log-%HB_COMPILER%.txt 2>&1
      -->8--


FOR MORE INFORMATION
====================

   Home:
   http://www.harbour-project.org/

   Mailing lists:
   http://www.harbour-project.org/mailing.html

   Developers' mail archives:
   http://lists.harbour-project.org/pipermail/harbour/

   Users' mail archives:
   http://lists.harbour-project.org/pipermail/harbour-users/

   Sourceforge page:
   https://sourceforge.net/projects/harbour-project/

   Development timeline:
   https://apps.sourceforge.net/trac/harbour-project/timeline

   Source repository browser:
   http://harbour-project.svn.sourceforge.net/viewvc/harbour-project/

   Source repository checkout (anonymous):
   svn co https://harbour-project.svn.sourceforge.net/svnroot/harbour-project harbour-project

   Miscellaneous documents:
   /doc directory under this dir.



[ Copyright (c) 2009 Viktor Szakats <harbour.01 syenar.hu>
  Licensed under Creative Commons Attribution-ShareAlike 3.0:
  http://creativecommons.org/licenses/by-sa/3.0/
  See COPYING. ]
