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 appare. 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%"