#
# $Id: gmake.txt,v 1.8 1999/09/16 23:52:04 dholm Exp $
#

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 ever target up to date within that
directory. There are no rules in the Makefiles, to keep them
platform-independent. The rules itself are included from the
"appropriate" configuration file.

For example, this could be the Makefile for the VM library:

--  Cut here  ---------------------------------------
#
# $Id: gmake.txt,v 1.8 1999/09/16 23:52:04 dholm Exp $
#

ROOT = ../../

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

LIB=vm

include $(TOP)$(ROOT)config/lib.cf
--  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: gmake.txt,v 1.8 1999/09/16 23:52:04 dholm Exp $
#

ROOT = ../../

YACC_SOURCE=harbour.y

LEX_SOURCE=harbour.l

C_SOURCES=\
        genobj32.c \

C_MAIN=harbour.c

include $(TOP)$(ROOT)config/bin.cf
--  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: gmake.txt,v 1.8 1999/09/16 23:52:04 dholm Exp $
#

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

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

include $(ROOT)config/dir.cf
--  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/win32: Configuration files for win32 platforms.


Finally, you will notice one thing: the build system compiles
everything into a subdirectory (for example, win32/gcc for WIN32 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.75 or later in your
system. To check this, type "make -v"; you should see

  GNU Make version 3.75, by Richard Stallman and Roland McGrath.
  ...

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

For gcc on Win95/WinNT with the Cygwin library:
  HB_ARCHITECTURE   win32
  HB_COMPILER       gcc

For gcc on Win95/WinNT with the Mingw32 library:
  HB_ARCHITECTURE   win32
  HB_COMPILER       mingw32

For MSVC on Win95/WinNT:
  HB_ARCHITECTURE   win32
  HB_COMPILER       msvc

For GCC on Linux:
  HB_ARCHITECTURE   linux
  HB_COMPILER       gcc

For GCC on OS/2:
  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_ARCHITECTURE   os2
  HB_COMPILER       gcc

For IBM Visual Age C++ on OS/2:
  Note: You must create an empty unistd.h in the IBMCPP\INCLUDE directory.
  HB_ARCHITECTURE   os2
  HB_COMPILER       icc

For Borland C++ 3.1
  HB_ARCHITECTURE   dos
  HB_COMPILER       bcc31

For DJGPP (GCC port for DOS)
  HB_ARCHITECTURE   dos
  HB_COMPILER       djgpp

For Watcom C/C++ 10.x (default Makefile creates DOS4G extender executables)
  HB_ARCHITECTURE   dos
  HB_COMPILER       watcom
  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 header,
executable and library files into directories given by

  HB_BIN_INSTALL
  HB_LIB_INSTALL
  HB_INC_INSTALL

You can set those as environment variables too.

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 -r clean
3) make -r

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.

The -r option isn't strictly necessary, but it does signficantly reduce
the number of rules that make has to evaluate otherwise, which may give
a performance boost on a slow system.


To rebuild only a part of Harbour, go to the appropriate source directory
and then run 'make -r'. 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.