The Falcon Programming Language

                                0.9.6.8
                                
                          BUILDING INSTRUCTION


INTRODUCTION
============

  This document refers to building Falcon source package as it distributed
in bleeding edge and official releases.

  Starting from 9.6.6.7, the package can be configured, built and tested 
directly from an "unguarded prompt". It's not necessary to use script or 
special configuration settings to develop Falcon, even in case that there
is a different development-enabled version of Falcon on the target system.
 

PRE-REQUISITE
=============

  To build Falcon, it is necessary to have installed a recent version of a
c/c++ compiler supporting your platform and cmake, available at

   http://www.cmake.org

  Other than that, it is optionally required to provide development files
correctly installed and configured for the following well known libraries:

  - ZLIB
  - PCRE


THE BUILD PROCESS
=================

  The build process happens under a standard CMAKE build session. Most of the
times,

  mkdir build
  cd build
  cmake ..       
  ccmake .       (*) 
  make install
  make 

  is enough to create the core Falcon installation. The line indicated with a (*) is a 
manual on-screen configuration of the falcon build elements. The ccmake command will
open up a menu through which you can cherry-pick the components to be built and installed.

  Many complex components, as SDL and DBI require a finetune configuration after their
switch on. To do that, first perform a configuration (use the 'c' key) and then change the
new settings that appear.

  Relevant variables affecting the outcome of the build and installation processes
are:

  - CMAKE_INSTALL_PREFIX: where Falcon will be placed on target systems. It is
      very relevant in POSIX systems. Defaults to "/usr/local".
  - FALCON_BIN_DIR: Directory under prefix for binary installation. Defaults
      to "bin".
  - FALCON_INC_DIR: Where to store include files. Defaults to
      "include/falcon<ver>"
  - FALCON_LIB_DIR: Where to store library files. Defaults to "lib".
  - FALCON_MOD_DIR: Default location for installation modules. Defaults to
      "$FALCON_LIB_DIR/falcon" on POSIX system, and "bin" on others.
  - FALCON_WITH_MANPAGES: Creates and install also manual pages for POSIX
      man command. It's "ON" by default on POSIX systems, "OFF" on others.
  - FALCON_MAN_DIR: Where to install man pages. Defaults to "share/man/man1".
  - FALCON_CMAKE_DIR: Where to install cmake configuration settings that can
      be used to create third party Falcon modules or application embedding
      falcon.
  - FALCON_SHARE_DIR: Where README and other distribution related
      documentation files are to be placed.

  The "make install" step can be directed to place Falcon in a temporary
empty location where it will be picked for separate packaging via the default
"DESTDIR=" setting:

   cmake -DCMAKE_INSTALL_PREFIX="/opt/falcon"
   make install DESTDIR="/tmp/falcon"

  This will move the needed files in /tmp/falcon, but will internally configure
falcon to run from /opt/falcon/bin


*NOTE: You'll usually want to ship your Falcon version built with

        -DCMAKE_BUILD_TYPE=Release

IDE Hints
=========

If using an IDE to create Falcon, like Xcode or Visual Studio, you may
want to use cmake install script "cmake_install.cmake" which is located in the
root of the build directory. The script usually installs the "Release" target
but you can tweak it by setting the script like the following:

   $ echo 'set(CMAKE_INSTALL_CONFIG_NAME "Debug" )' >> debug_install.cmake
   $ cat cmake_install.cmake >> debug_install.cmake
   $ DESTDIR=/tmp/falcon cmake -P debug_install.cmake

To be able to run the install target directly from the IDE, you'll need to tweak
some manual settings in the project files; keep in mind that CMAKE will destroy 
those project files when a setting is changed, and thus CMAKE is re-run, so you'll
need to re-enter this setting manually after each re-configuration.

On XCODE, just add a "DESTDIR" User-Defined setting in the "build" tab of the 
global project settings.

On Eclipse, set the DESTDIR variable as an environment setting under the build/make
project category.

On Visual Studio, there isn't any specific setting, but you can easily set the
DESTDIR varible in the environment prior loading the visual studio from the
command line, like in the following example:

	set DESTDIR=c:\tmp\install\falcon
	vcexpress (or other command to start the visual studio)

A similar approach can be applied to Eclipse, while it's more problematic with XCode.



Running from a temporary directory
==================================

  Falcon just requires its FALCON_LOAD_PATH to be properly set to the location where
modules are to be found. Also, on POSIX systems, the dynamic library loader path
should be directed to load the falcon engine library file from the temporary library
installation path. Finally, it's advisable to add the location where the binary
falcon interpreter is to be found in front of the system PATH.

  All this operations are performed by a script named "falconenv.sh" or "falconenv.bat"
found in devtools/ directory; just pass the temporary installation directory name to the
script as a parameter and it will set the required variables accordingly.

  On POSIX systems remember to include the script instead of just running it, using the
command:
	
		source devtools/falconenv.sh path/to/temp/install/dir

		 

Changing library directory name
===============================

  In some systems, common system libraries for different architectures are
stored on different directories. For example, one may want to store the 64 bit
version of Falcon engine in lib64.


Internal libraries
==================

  By default, Falcon feathers build process tries to find in the system a
build support for PCRE and ZLIB, falling back to build internally shipped
versions if they are not found:

  - PCRE 7.2
  - ZLIB 1.1

  To change this behavior, use the following options

  -DFALCON_WITH_INTERNAL_PCRE=ON    (to build internal PCRE)
  -DFALCON_WITH_INTERNAL_PCRE=OFF   (to force external PCRE)
  -DFALCON_WITH_INTERNAL_ZLIB=ON    (to build internal ZLIB)
  -DFALCON_WITH_INTERNAL_ZLIB=OFF   (to force external ZLIB)


Support for EDITLINE in interactive mode (POSIX)
================================================

  The falcon command line tool can take benefit of an installed editline
library, or use the internally distributed editline in case editline
is not available.

  Currently, both those library cannot interpret international
characters correctly, so they are turned off by default.

  To compile falcon with Editline support use:

   -DFALCON_WITH_EDITLINE=ON
   
  If you want to use a system-wide installation of editline, instead of
the one that is shipped with Falcon, use the following option:

   -DFALCON_WITH_INTERNAL_EDITLINE=OFF

  Notice that, in this case, Falcon build system will detect if you
have a system-wide installation of the edit-line library, and
use that instead.

  Notice that WIN32 console has a built-in interface that allows to
edit the commands inputed in the interactive mode.



RUNNING TEST BUILDS - POSIX
===========================

  On POSIX systems, the script bin/falconenv.sh  configures the
environment so that Falcon is found on a temporary install location instead of
being loaded from the standard system installation location.

  For example, after having installed a Falcon build configured to be
installed on /usr/local and placed in /tmp/falcon, through the following
commands:

   $ cmake <path to source> -DCMAKE_INSTALL_PREFIX=/usr/local
   $ DESTDIR=/tmp/falcon make install

it is possible to launch the following command to run that version of Falcon
and have it accessing (exclusively) the modules installed with it:

   $ falconenv.sh  <command to launch>

  The command may be any binary file in the Falcon /bin installation directory
or any valid shell (i.e. /bin/bash) that will be run with the variables set
to start falcon from the temporary test install directory.

  The script actually sets the following variables:

    - PATH where to find the falcon executables.
    - LD_LIBRARY_PATH (or equivalent) on POSIX to find the engine library.
    - FALCON_LOAD_PATH to the place where falcon modules are installed.

* NOTE: The sole purpose of this script is that of being able to test-run
Falcon during development or before a complete installation. Packagers may
wish to delete it before finally packing Falcon for distribution.


RUNNING TEST BUILDS - MS-WINDOWS
================================

  On MS-Windows system, it's enough to run the following commands:
  
    C:\> set FALCON_LOAD_PATH="<path to your falcon.exe>;."
    C:\> set PATH="%FALCON_LOAD_PATH%;%PATH%"