harbour-core/harbour/doc/gmake.txt

/*
 * $Id$
 */

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

This file explains the philosophy for the GNU-make based build system
for Harbour, and gives instructions on how to use it.


PHILOSOPHY
==========

This build system is based on GNU-make, the idea being that GNU-make
is freely available for every platform you can dream up, and it is
usually more powerful than any native make.

Each directory in the project contains one makefile, called Makefile,
which lists the data (file names, directory names, etc.) that is used
to determine how to bring every target up to date within that
directory. There are no rules in the Makefiles, to keep them
platform-independent. The rules themselves are included from the
"appropriate" configuration file.

For example, the following was the Makefile for an early version
of the VM library:

--  Cut here  ---------------------------------------
#
# $Id$
#

ROOT := ../../

C_SOURCES := \
        dynsym.c \
        hvm.c \
        initsymb.c \

LIB := vm

include $(TOP)$(ROOT)config/lib.mk
--  Cut here  ---------------------------------------

What this means is:

* The root of the source directory is in ../../; that is where the
  config/ directory lives, with all the real rules to make the
  targets.
* The only sources in this directory are C sources (three files).
* The library name is "vm". This will be translated to a real file
  name depending on the rules file: "libvm.a" on Unix, "VM.LIB" on
  DOS.
* The final line includes the rules file. In this case, we include a
  set of rules to build a library.

Let's look at another Makefile, this one for the Harbour compiler:

--  Cut here  ---------------------------------------
#
# $Id$
#

ROOT := ../../

YACC_SOURCE := harbour.y

LEX_SOURCE := harbour.l

C_SOURCES := \
        genobj32.c \

C_MAIN=harbour.c

include $(TOP)$(ROOT)config/bin.mk
--  Cut here  ---------------------------------------

Notice how we now have other kinds of source files: yacc sources and
lex sources. Also, since this is a Makefile for a stand-alone
executable, we indicate the name for the file containing the "main"
function, which also defines the executable name. The rules included
in this Makefile are those appropriate to build a stand-alone binary.

One final Makefile, this one from the source directory:

#
# $Id$
#

--  Cut here  ---------------------------------------
ROOT := ../

DIRS := \
        compiler \
        hbpp \
        rtl \
        vm \
        rdd \
        tools \

include $(TOP)$(ROOT)config/dir.mk
--  Cut here  ---------------------------------------

This Makefile is used to traverse the subdirectories hanging from the
current directory. It simply lists all the subdirectories to be
traversed.

Now. let's take a look at the rules themselves. They all live in the
config/ directory, with the following structure:

  config/: The generic configuration files.
  config/win: Configuration files for Windows platforms.


Finally, you will notice one thing: the build system compiles
everything into a subdirectory (for example, win/gcc for Windows
files compiled with gcc). This has two advantages:

1. It allows you to compile for multiple platforms/compilers at the
   same time.
2. It creates all temporary, object, binary, intermediate, etc. files
   in the subdirectory; cleaning up is very easy.


USAGE
=====

To use the system, you need to install GNU-make 3.81 or later on your
system. To check this, type "make -v"; you should see

  GNU Make 3.81
  Copyright (C) 2006  Free Software Foundation, Inc.
  ...

Then, you must set a couple of environment variables that indicate
your platform and compiler.

For gcc on Win95/WinNT with the Cygwin library:
  Notes: The CYGWIN environment variable must include "noglob" in order
         to avoid having Harbour or programs created with Harbour expand
         wildcard command line arguments (this is checked at run-time!)
  HB_PLATFORM       win
  HB_COMPILER       gcc
  HB_GT_LIB         gtwin
  CYGWIN            noglob

For gcc on Win95/WinNT with the MinGW library:
  HB_PLATFORM       win
  HB_COMPILER       mingw
  HB_GT_LIB         gtwin

For MSVC on Win95/WinNT:
  Notes: gnu make is case sensitive!  If your editor converts
         harbour.c to HARBOUR.C when it saves the file, then gnu make
         _will_not_work.
         If you have MAKE_MODE in your dos environment, make sure it is
         not set to unix

         For best results, in your copy of make_gnu.bat, also set:
  HB_PLATFORM       win
  HB_COMPILER       msvc
  HB_GT_LIB         gtwin

For GCC on BSD:
  HB_PLATFORM       bsd
  HB_COMPILER       gcc
  HB_GT_LIB         gtstd
  Notes:
    1)  You have to have bison and gmake installed in order to build
        Harbour for BSD. The file doc/howtobsd.txt gives an overview
        of what is required.
    2)  If you have an ncurses library or a slang library, you may
        want to try one of the following two values for HB_GT_LIB:
              gtcrs
              gtsln
        In which case you'll also need to export HB_SCREEN_LIB with
        the name of the appropriate screen library, if it doesn't
        match the default value in config/bsd/gcc.mk

For GCC on Linux:
  HB_PLATFORM       linux
  HB_COMPILER       gcc
  HB_GT_LIB         gtstd
  Notes:
    1)  If you have an ncurses library or a slang library, you may
        want to try one of the following two values for HB_GT_LIB:
              gtcrs
              gtsln
        In which case you'll also need to export HB_SCREEN_LIB with
        the name of the appropriate screen library, if it doesn't
        match the default value in config/linux/gcc.mk.
    2)  If you want to take advantage of compiler cache programs
        (such as http://ccaache.samba.org), you may set environment
        variable HB_CCACHE with the value containing the name of program.

For GCC on OS/2 for VIO mode:
  Note: You must point C_INCLUDE_PATH to the EMX include directory and
        you must also point LIBRARY_PATH to the EMX library directory.
  HB_PLATFORM       os2
  HB_COMPILER       gcc
  HB_GT_LIB         gtos2

For Borland C++ 5.5
  HB_PLATFORM       win
  HB_COMPILER       bcc
  HB_GT_LIB         gtwin

For Borland C++ 3.x
  HB_PLATFORM       dos
  HB_GT_LIB         gtdos

For DJGPP (GCC port for DOS)
  HB_PLATFORM       dos
  HB_COMPILER       djgpp
  HB_GT_LIB         gtdos

For Watcom C/C++ 10.x (default Makefile creates DOS4G extender executables)
  HB_PLATFORM       dos
  HB_COMPILER       watcom
  HB_GT_LIB         gtdos
  Note: It is possible that you will have to increase the space reserved for
        DOS environment variables in order to successfuly run make utility
        (Add for example:
         SHELL=C:\COMMAND.COM C:\ E=2048 /P
         to your CONFIG.SYS )

If you issue a "make install", it will try to install your doc, header,
executable and library files into directories given by

  HB_INSTALL_BIN
  HB_INSTALL_DOC
  HB_INSTALL_LIB
  HB_INSTALL_INC

You can set those as environment variables too. There is no default for
HB_INSTALL_DOC, so if you don't define it, then the doc files will not be
installed.

The most used targets are these:

* all: Same as typing "make" without arguments. It will usually try to
  compile and link the obvious target in the directory.

* clean: Clean up everything made by make.

* install: Install stuff into the appropriate directories.


NOTES
=====
In order to get a clean build after making source changes or after
receiving updated source files, you must use the following two steps:

1) make clean
3) make

Without the first step, changes to the Harbour compiler and/or various
include files will not be reflected in any object modules created from
Harbour source code.


To rebuild only a part of Harbour, go to the appropriate source directory
and then run 'make'. For example, to rebuild all of Harbour, but not
the test programs, change to the 'source' directory. To rebuild only the
test programs, change to the 'test' directory.


If you are using a DOS-based operating system, then you can build any
program in tests/working by using the build batch file. For example,
'build scroll' will rebuild the scroll.prg program and then run it. This
can also be used for modules that aren't in the Makefile. You can also
pass parameters to the program. For example, 'build readfile harbour.ini'
will rebuild the readfile.prg program and run it with 'harbour.ini' as a
command line parameter.